quoted-printable

What is quoted-printable?

The quoted-printable npm package is used for encoding and decoding data in the quoted-printable format, which is commonly used in email and MIME (Multipurpose Internet Mail Extensions) to encode binary data into a text format that can be safely transmitted over protocols that are not 8-bit clean.

What are quoted-printable's main functionalities?

Encoding

This feature allows you to encode a string into the quoted-printable format. The example encodes the string 'Hello, World!' into its quoted-printable representation.

const quotedPrintable = require('quoted-printable');
const encoded = quotedPrintable.encode('Hello, World!');
console.log(encoded); // Outputs: 'Hello=2C=20World=21'

Decoding

This feature allows you to decode a quoted-printable encoded string back into its original form. The example decodes the quoted-printable string 'Hello=2C=20World=21' back to 'Hello, World!'.

const quotedPrintable = require('quoted-printable');
const decoded = quotedPrintable.decode('Hello=2C=20World=21');
console.log(decoded); // Outputs: 'Hello, World!'

Other packages similar to quoted-printable

emailjs-mime-codec

The emailjs-mime-codec package provides utilities for encoding and decoding MIME content, including quoted-printable and base64. It offers more comprehensive MIME handling capabilities compared to quoted-printable, making it suitable for more complex email processing tasks.

mimelib

The mimelib package is a library for handling MIME email messages, including encoding and decoding quoted-printable and base64 content. It provides a broader set of features for working with MIME messages, such as parsing headers and handling attachments, which makes it more versatile than quoted-printable.

README

quoted-printable

quoted-printable is a character encoding–agnostic JavaScript implementation of the Quoted-Printable content transfer encoding as defined by RFC 2045. It can be used to encode plaintext to its Quoted-Printable encoding, or the other way around (i.e. decoding). Here’s an online demo using the UTF-8 character encoding.

Installation

Via npm:

npm install quoted-printable

Via Bower:

bower install quoted-printable

Via Component:

component install mathiasbynens/quoted-printable

In a browser:

<script src="quoted-printable.js"></script>

In Node.js, io.js, Narwhal, and RingoJS:

var quotedPrintable = require('quoted-printable');

In Rhino:

load('quoted-printable.js');

Using an AMD loader like RequireJS:

require(
  {
    'paths': {
      'quoted-printable': 'path/to/quoted-printable'
    }
  },
  ['quoted-printable'],
  function(quotedPrintable) {
    console.log(quotedPrintable);
  }
);

API

quotedPrintable.version

A string representing the semantic version number.

quotedPrintable.encode(input)

This function takes an encoded byte string (the input parameter) and Quoted-Printable-encodes it. Each item in the input string represents an octet as per the desired character encoding. Here’s an example that uses UTF-8:

var utf8 = require('utf8');

quotedPrintable.encode(utf8.encode('foo=bar'));
// → 'foo=3Dbar'

quotedPrintable.encode(utf8.encode('Iñtërnâtiônàlizætiøn☃💩'));
// → 'I=C3=B1t=C3=ABrn=C3=A2ti=C3=B4n=C3=A0liz=C3=A6ti=C3=B8n=E2=98=83=F0=9F=92=\r\n=A9'

quotedPrintable.decode(text)

This function takes a string of text (the text parameter) and Quoted-Printable-decodes it. The return value is a ‘byte string’, i.e. a string of which each item represents an octet as per the character encoding that’s being used. Here’s an example that uses UTF-8:

var utf8 = require('utf8');

utf8.decode(quotedPrintable.decode('foo=3Dbar'));
// → 'foo=bar'

utf8.decode(quotedPrintable.decode('I=C3=B1t=C3=ABrn=C3=A2ti=C3=B4n=C3=A0liz=C3=A6ti=C3=B8n=E2=98=83=F0=9F=92=\r\n=A9'));
// → 'Iñtërnâtiônàlizætiøn☃💩'

Using the quoted-printable binary

To use the quoted-printable binary in your shell, simply install quoted-printable globally using npm:

npm install -g quoted-printable

After that, you’ll be able to use quoted-printable on the command line. Note that while the quoted-printable library itself is character encoding–agnostic, the command-line tool applies the UTF-8 character encoding on all input.

$ quoted-printable --encode 'foo=bar'
foo=3Dbar

$ quoted-printable --decode 'foo=3Dbar'
foo=bar

Read a local text file, Quoted-Printable-encode it, and save the result to a new file:

$ quoted-printable --encode < foo.txt > foo-quoted-printable.txt

Or do the same with an online text file:

$ curl -sL 'https://mths.be/brh' | quoted-printable --encode > quoted-printable.txt

Or, the opposite — read a local file containing a Quoted-Printable-encoded message, decode it back to plain text, and save the result to a new file:

$ quoted-printable --decode < quoted-printable.txt > original.txt

See quoted-printable --help for the full list of options.

Support

quoted-printable is designed to work in at least Node.js v0.10.0, io.js v1.0.0, Narwhal 0.3.2, RingoJS 0.8-0.11, PhantomJS 1.9.0, Rhino 1.7RC4, as well as old and modern versions of Chrome, Firefox, Safari, Opera, and Internet Explorer.

Unit tests & code coverage

After cloning this repository, run npm install to install the dependencies needed for development and testing. You may want to install Istanbul globally using npm install istanbul -g.

Once that’s done, you can run the unit tests in Node using npm test or node tests/tests.js. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use grunt test.

To generate the code coverage report, use grunt cover.

Author

Mathias Bynens

License

quoted-printable is available under the MIT license.