BlueGit

blue-star danique-bot

Files

danique-bot / node_modules / punycode / README.md

README.md

Import template
timfa Tim · pushed by timfa · 4 years ago
c788ad20 History
README.md 6.0 KiB Download Raw

Punycode.js Build status Code coverage status Dependency status

A robust Punycode converter that fully complies to RFC 3492 and RFC 5891, and works on nearly all JavaScript platforms.

This JavaScript library is the result of comparing, optimizing and documenting different open-source implementations of the Punycode algorithm:

This project is bundled with Node.js v0.6.2+ and io.js v1.0.0+.

Installation

Via npm (only required for Node.js releases older than v0.6.2):

npm install punycode

Via Bower:

bower install punycode

Via Component:

component install bestiejs/punycode.js

In a browser:

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

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

var punycode = require('punycode');

In Rhino:

load('punycode.js');

Using an AMD loader like RequireJS:

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

API

punycode.decode(string)

Converts a Punycode string of ASCII symbols to a string of Unicode symbols.

// decode domain name parts
punycode.decode('maana-pta'); // 'mañana'
punycode.decode('--dqo34k'); // '☃-⌘'

punycode.encode(string)

Converts a string of Unicode symbols to a Punycode string of ASCII symbols.

// encode domain name parts
punycode.encode('mañana'); // 'maana-pta'
punycode.encode('☃-⌘'); // '--dqo34k'

punycode.toUnicode(input)

Converts a Punycode string representing a domain name or an email address to Unicode. Only the Punycoded parts of the input will be converted, i.e. it doesn’t matter if you call it on a string that has already been converted to Unicode.

// decode domain names
punycode.toUnicode('xn--maana-pta.com');
// → 'mañana.com'
punycode.toUnicode('xn----dqo34k.com');
// → '☃-⌘.com'

// decode email addresses
punycode.toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');
// → 'джумла@джpумлатест.bрфa'

punycode.toASCII(input)

Converts a lowercased Unicode string representing a domain name or an email address to Punycode. Only the non-ASCII parts of the input will be converted, i.e. it doesn’t matter if you call it with a domain that’s already in ASCII.

// encode domain names
punycode.toASCII('mañana.com');
// → 'xn--maana-pta.com'
punycode.toASCII('☃-⌘.com');
// → 'xn----dqo34k.com'

// encode email addresses
punycode.toASCII('джумла@джpумлатест.bрфa');
// → 'джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq'

punycode.ucs2

punycode.ucs2.decode(string)

Creates an array containing the numeric code point values of each Unicode symbol in the string. While JavaScript uses UCS-2 internally, this function will convert a pair of surrogate halves (each of which UCS-2 exposes as separate characters) into a single code point, matching UTF-16.

punycode.ucs2.decode('abc');
// → [0x61, 0x62, 0x63]
// surrogate pair for U+1D306 TETRAGRAM FOR CENTRE:
punycode.ucs2.decode('\uD834\uDF06');
// → [0x1D306]

punycode.ucs2.encode(codePoints)

Creates a string based on an array of numeric code point values.

punycode.ucs2.encode([0x61, 0x62, 0x63]);
// → 'abc'
punycode.ucs2.encode([0x1D306]);
// → '\uD834\uDF06'

punycode.version

A string representing the current Punycode.js version number.

Unit tests & code coverage

After cloning this repository, run npm install --dev to install the dependencies needed for Punycode.js 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, PhantomJS, and web browsers as well, use grunt test.

To generate the code coverage report, use grunt cover.

Feel free to fork if you see possible improvements!

Author

twitter/mathias
Mathias Bynens

Contributors

twitter/jdalton
John-David Dalton

License

Punycode.js is available under the MIT license.

Source
1# Punycode.js [![Build status](https://travis-ci.org/bestiejs/punycode.js.svg?branch=master)](https://travis-ci.org/bestiejs/punycode.js) [![Code coverage status](http://img.shields.io/coveralls/bestiejs/punycode.js/master.svg)](https://coveralls.io/r/bestiejs/punycode.js) [![Dependency status](https://gemnasium.com/bestiejs/punycode.js.svg)](https://gemnasium.com/bestiejs/punycode.js)
2
3A robust Punycode converter that fully complies to [RFC 3492](https://tools.ietf.org/html/rfc3492) and [RFC 5891](https://tools.ietf.org/html/rfc5891), and works on nearly all JavaScript platforms.
4
5This JavaScript library is the result of comparing, optimizing and documenting different open-source implementations of the Punycode algorithm:
6
7* [The C example code from RFC 3492](https://tools.ietf.org/html/rfc3492#appendix-C)
8* [`punycode.c` by _Markus W. Scherer_ (IBM)](http://opensource.apple.com/source/ICU/ICU-400.42/icuSources/common/punycode.c)
9* [`punycode.c` by _Ben Noordhuis_](https://github.com/bnoordhuis/punycode/blob/master/punycode.c)
10* [JavaScript implementation by _some_](http://stackoverflow.com/questions/183485/can-anyone-recommend-a-good-free-javascript-for-punycode-to-unicode-conversion/301287#301287)
11* [`punycode.js` by _Ben Noordhuis_](https://github.com/joyent/node/blob/426298c8c1c0d5b5224ac3658c41e7c2a3fe9377/lib/punycode.js) (note: [not fully compliant](https://github.com/joyent/node/issues/2072))
12
13This project is [bundled](https://github.com/joyent/node/blob/master/lib/punycode.js) with [Node.js v0.6.2+](https://github.com/joyent/node/compare/975f1930b1...61e796decc) and [io.js v1.0.0+](https://github.com/iojs/io.js/blob/v1.x/lib/punycode.js).
14
15## Installation
16
17Via [npm](https://www.npmjs.com/) (only required for Node.js releases older than v0.6.2):
18
19```bash
20npm install punycode
21```
22
23Via [Bower](http://bower.io/):
24
25```bash
26bower install punycode
27```
28
29Via [Component](https://github.com/component/component):
30
31```bash
32component install bestiejs/punycode.js
33```
34
35In a browser:
36
37```html
38<script src="punycode.js"></script>
39```
40
41In [Node.js](https://nodejs.org/), [io.js](https://iojs.org/), [Narwhal](http://narwhaljs.org/), and [RingoJS](http://ringojs.org/):
42
43```js
44var punycode = require('punycode');
45```
46
47In [Rhino](http://www.mozilla.org/rhino/):
48
49```js
50load('punycode.js');
51```
52
53Using an AMD loader like [RequireJS](http://requirejs.org/):
54
55```js
56require(
57 {
58 'paths': {
59 'punycode': 'path/to/punycode'
60 }
61 },
62 ['punycode'],
63 function(punycode) {
64 console.log(punycode);
65 }
66);
67```
68
69## API
70
71### `punycode.decode(string)`
72
73Converts a Punycode string of ASCII symbols to a string of Unicode symbols.
74
75```js
76// decode domain name parts
77punycode.decode('maana-pta'); // 'mañana'
78punycode.decode('--dqo34k'); // '☃-⌘'
79```
80
81### `punycode.encode(string)`
82
83Converts a string of Unicode symbols to a Punycode string of ASCII symbols.
84
85```js
86// encode domain name parts
87punycode.encode('mañana'); // 'maana-pta'
88punycode.encode('☃-⌘'); // '--dqo34k'
89```
90
91### `punycode.toUnicode(input)`
92
93Converts a Punycode string representing a domain name or an email address to Unicode. Only the Punycoded parts of the input will be converted, i.e. it doesn’t matter if you call it on a string that has already been converted to Unicode.
94
95```js
96// decode domain names
97punycode.toUnicode('xn--maana-pta.com');
98// → 'mañana.com'
99punycode.toUnicode('xn----dqo34k.com');
100// → '☃-⌘.com'
101
102// decode email addresses
103punycode.toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');
104// → 'джумла@джpумлатест.bрфa'
105```
106
107### `punycode.toASCII(input)`
108
109Converts a lowercased Unicode string representing a domain name or an email address to Punycode. Only the non-ASCII parts of the input will be converted, i.e. it doesn’t matter if you call it with a domain that’s already in ASCII.
110
111```js
112// encode domain names
113punycode.toASCII('mañana.com');
114// → 'xn--maana-pta.com'
115punycode.toASCII('☃-⌘.com');
116// → 'xn----dqo34k.com'
117
118// encode email addresses
119punycode.toASCII('джумла@джpумлатест.bрфa');
120// → 'джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq'
121```
122
123### `punycode.ucs2`
124
125#### `punycode.ucs2.decode(string)`
126
127Creates an array containing the numeric code point values of each Unicode symbol in the string. While [JavaScript uses UCS-2 internally](https://mathiasbynens.be/notes/javascript-encoding), this function will convert a pair of surrogate halves (each of which UCS-2 exposes as separate characters) into a single code point, matching UTF-16.
128
129```js
130punycode.ucs2.decode('abc');
131// → [0x61, 0x62, 0x63]
132// surrogate pair for U+1D306 TETRAGRAM FOR CENTRE:
133punycode.ucs2.decode('\uD834\uDF06');
134// → [0x1D306]
135```
136
137#### `punycode.ucs2.encode(codePoints)`
138
139Creates a string based on an array of numeric code point values.
140
141```js
142punycode.ucs2.encode([0x61, 0x62, 0x63]);
143// → 'abc'
144punycode.ucs2.encode([0x1D306]);
145// → '\uD834\uDF06'
146```
147
148### `punycode.version`
149
150A string representing the current Punycode.js version number.
151
152## Unit tests & code coverage
153
154After cloning this repository, run `npm install --dev` to install the dependencies needed for Punycode.js development and testing. You may want to install Istanbul _globally_ using `npm install istanbul -g`.
155
156Once 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, PhantomJS, and web browsers as well, use `grunt test`.
157
158To generate the code coverage report, use `grunt cover`.
159
160Feel free to fork if you see possible improvements!
161
162## Author
163
164| [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
165|---|
166| [Mathias Bynens](https://mathiasbynens.be/) |
167
168## Contributors
169
170| [![twitter/jdalton](https://gravatar.com/avatar/299a3d891ff1920b69c364d061007043?s=70)](https://twitter.com/jdalton "Follow @jdalton on Twitter") |
171|---|
172| [John-David Dalton](http://allyoucanleet.com/) |
173
174## License
175
176Punycode.js is available under the [MIT](https://mths.be/mit) license.