Skip to content
A robust & character encoding–agnostic JavaScript implementation of the `Q` encoding as defined by RFC 2047.
JavaScript HTML
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin Test in Node.js v0.12, io.js, and Rhino 1.7R5 Feb 24, 2015
man Test in Node.js v0.12, io.js, and Rhino 1.7R5 Feb 24, 2015
scripts Make `q.encode()` safe for email headers Nov 14, 2016
src Test in Node.js v0.12, io.js, and Rhino 1.7R5 Feb 24, 2015
tests Make `q.encode()` safe for email headers Nov 14, 2016
.gitattributes Initial commit May 5, 2014
.gitignore Initial commit May 5, 2014
.travis.yml
Gruntfile.js Test in Node.js v0.12, io.js, and Rhino 1.7R5 Feb 24, 2015
LICENSE-MIT.txt Test in Node.js v0.12, io.js, and Rhino 1.7R5 Feb 24, 2015
README.md README: Link to online demo Nov 14, 2016
bower.json
component.json Release v1.0.0 Nov 14, 2016
package.json Release v1.0.0 Nov 14, 2016
q.js Release v1.0.0 Nov 14, 2016

README.md

q-encoding Build status Dependency status

q-encoding is a character encoding–agnostic JavaScript implementation of the Q encoding as defined by RFC 2047. It can be used to encode data with any character encoding to its Q-encoded form, or the other way around (i.e. decoding).

An online demo is available.

Installation

Via npm:

npm install q-encoding

Via Bower:

bower install q-encoding

Via Component:

component install mathiasbynens/q-encoding

In a browser:

<script src="q.js"></script>

In Narwhal, Node.js, and RingoJS:

var q = require('q-encoding');

In Rhino:

load('q.js');

Using an AMD loader like RequireJS:

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

API

q.version

A string representing the semantic version number.

q.encode(input)

This function takes an encoded byte string (the input parameter) and Q-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');

q.encode(utf8.encode('foo = bar'));
// → 'foo_=3D_bar'

q.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=A9'

q.decode(text)

This function takes a Q-encoded string of text (the text parameter) and Q-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(q.decode('foo_=3D_bar'));
// → 'foo = bar'

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

Using the q binary

To use the q binary in your shell, simply install q-encoding globally using npm:

npm install -g q-encoding

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

$ q --encode 'foo = bar'
foo_=3D_bar

$ q --decode 'foo_=3D_bar'
foo = bar

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

$ q --encode < foo.txt > foo-q.txt

Or do the same with an online text file:

$ curl -sL 'https://mths.be/brh' | q --encode > q.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:

$ q --decode < q.txt > original.txt

See q --help for the full list of options.

Support

q-encoding is designed to work in at least Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, 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

twitter/mathias
Mathias Bynens

License

q-encoding is available under the MIT license.

You can’t perform that action at this time.