www.aleph1.co.uk Git - yaffs-website/blob - node_modules/punycode/README.md

   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
   3 A 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
   5 This 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
  13 This 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
  17 Via [npm](https://www.npmjs.com/) (only required for Node.js releases older than v0.6.2):
  18
  19 ```bash
  20 npm install punycode
  21 ```
  22
  23 Via [Bower](http://bower.io/):
  24
  25 ```bash
  26 bower install punycode
  27 ```
  28
  29 Via [Component](https://github.com/component/component):
  30
  31 ```bash
  32 component install bestiejs/punycode.js
  33 ```
  34
  35 In a browser:
  36
  37 ```html
  38 <script src="punycode.js"></script>
  39 ```
  40
  41 In [Node.js](https://nodejs.org/), [io.js](https://iojs.org/), [Narwhal](http://narwhaljs.org/), and [RingoJS](http://ringojs.org/):
  42
  43 ```js
  44 var punycode = require('punycode');
  45 ```
  46
  47 In [Rhino](http://www.mozilla.org/rhino/):
  48
  49 ```js
  50 load('punycode.js');
  51 ```
  52
  53 Using an AMD loader like [RequireJS](http://requirejs.org/):
  54
  55 ```js
  56 require(
  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
  73 Converts a Punycode string of ASCII symbols to a string of Unicode symbols.
  74
  75 ```js
  76 // decode domain name parts
  77 punycode.decode('maana-pta'); // 'mañana'
  78 punycode.decode('--dqo34k'); // '☃-⌘'
  79 ```
  80
  81 ### `punycode.encode(string)`
  82
  83 Converts a string of Unicode symbols to a Punycode string of ASCII symbols.
  84
  85 ```js
  86 // encode domain name parts
  87 punycode.encode('mañana'); // 'maana-pta'
  88 punycode.encode('☃-⌘'); // '--dqo34k'
  89 ```
  90
  91 ### `punycode.toUnicode(input)`
  92
  93 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.
  94
  95 ```js
  96 // decode domain names
  97 punycode.toUnicode('xn--maana-pta.com');
  98 // → 'mañana.com'
  99 punycode.toUnicode('xn----dqo34k.com');
 100 // → '☃-⌘.com'
 101
 102 // decode email addresses
 103 punycode.toUnicode('джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq');
 104 // → 'джумла@джpумлатест.bрфa'
 105 ```
 106
 107 ### `punycode.toASCII(input)`
 108
 109 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.
 110
 111 ```js
 112 // encode domain names
 113 punycode.toASCII('mañana.com');
 114 // → 'xn--maana-pta.com'
 115 punycode.toASCII('☃-⌘.com');
 116 // → 'xn----dqo34k.com'
 117
 118 // encode email addresses
 119 punycode.toASCII('джумла@джpумлатест.bрфa');
 120 // → 'джумла@xn--p-8sbkgc5ag7bhce.xn--ba-lmcq'
 121 ```
 122
 123 ### `punycode.ucs2`
 124
 125 #### `punycode.ucs2.decode(string)`
 126
 127 Creates 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
 130 punycode.ucs2.decode('abc');
 131 // → [0x61, 0x62, 0x63]
 132 // surrogate pair for U+1D306 TETRAGRAM FOR CENTRE:
 133 punycode.ucs2.decode('\uD834\uDF06');
 134 // → [0x1D306]
 135 ```
 136
 137 #### `punycode.ucs2.encode(codePoints)`
 138
 139 Creates a string based on an array of numeric code point values.
 140
 141 ```js
 142 punycode.ucs2.encode([0x61, 0x62, 0x63]);
 143 // → 'abc'
 144 punycode.ucs2.encode([0x1D306]);
 145 // → '\uD834\uDF06'
 146 ```
 147
 148 ### `punycode.version`
 149
 150 A string representing the current Punycode.js version number.
 151
 152 ## Unit tests & code coverage
 153
 154 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`.
 155
 156 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`.
 157
 158 To generate the code coverage report, use `grunt cover`.
 159
 160 Feel 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
 176 Punycode.js is available under the [MIT](https://mths.be/mit) license.