1 | # jsesc [![Build status](https://travis-ci.org/mathiasbynens/jsesc.svg?branch=master)](https://travis-ci.org/mathiasbynens/jsesc) [![Code coverage status](http://img.shields.io/coveralls/mathiasbynens/jsesc/master.svg)](https://coveralls.io/r/mathiasbynens/jsesc) [![Dependency status](https://gemnasium.com/mathiasbynens/jsesc.svg)](https://gemnasium.com/mathiasbynens/jsesc)
|
---|
2 |
|
---|
3 | This is a JavaScript library for [escaping JavaScript strings](http://mathiasbynens.be/notes/javascript-escapes) while generating the shortest possible valid ASCII-only output. [Here’s an online demo.](http://mothereff.in/js-escapes)
|
---|
4 |
|
---|
5 | This can be used to avoid [mojibake](http://en.wikipedia.org/wiki/Mojibake) and other encoding issues, or even to [avoid errors](https://twitter.com/annevk/status/380000829643571200) when passing JSON-formatted data (which may contain U+2028 LINE SEPARATOR, U+2029 PARAGRAPH SEPARATOR, or [lone surrogates](http://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)) to a JavaScript parser or an UTF-8 encoder, respectively.
|
---|
6 |
|
---|
7 | Feel free to fork if you see possible improvements!
|
---|
8 |
|
---|
9 | ## Installation
|
---|
10 |
|
---|
11 | Via [Bower](http://bower.io/):
|
---|
12 |
|
---|
13 | ```bash
|
---|
14 | bower install jsesc
|
---|
15 | ```
|
---|
16 |
|
---|
17 | Via [Component](https://github.com/component/component):
|
---|
18 |
|
---|
19 | ```bash
|
---|
20 | component install mathiasbynens/jsesc
|
---|
21 | ```
|
---|
22 |
|
---|
23 | Via [npm](http://npmjs.org/):
|
---|
24 |
|
---|
25 | ```bash
|
---|
26 | npm install jsesc
|
---|
27 | ```
|
---|
28 |
|
---|
29 | In a browser:
|
---|
30 |
|
---|
31 | ```html
|
---|
32 | <script src="jsesc.js"></script>
|
---|
33 | ```
|
---|
34 |
|
---|
35 | In [Node.js](http://nodejs.org/) and [RingoJS](http://ringojs.org/):
|
---|
36 |
|
---|
37 | ```js
|
---|
38 | var jsesc = require('jsesc');
|
---|
39 | ```
|
---|
40 |
|
---|
41 | In [Narwhal](http://narwhaljs.org/):
|
---|
42 |
|
---|
43 | ```js
|
---|
44 | var jsesc = require('jsesc').jsesc;
|
---|
45 | ```
|
---|
46 |
|
---|
47 | In [Rhino](http://www.mozilla.org/rhino/):
|
---|
48 |
|
---|
49 | ```js
|
---|
50 | load('jsesc.js');
|
---|
51 | ```
|
---|
52 |
|
---|
53 | Using an AMD loader like [RequireJS](http://requirejs.org/):
|
---|
54 |
|
---|
55 | ```js
|
---|
56 | require(
|
---|
57 | {
|
---|
58 | 'paths': {
|
---|
59 | 'jsesc': 'path/to/jsesc'
|
---|
60 | }
|
---|
61 | },
|
---|
62 | ['jsesc'],
|
---|
63 | function(jsesc) {
|
---|
64 | console.log(jsesc);
|
---|
65 | }
|
---|
66 | );
|
---|
67 | ```
|
---|
68 |
|
---|
69 | ## API
|
---|
70 |
|
---|
71 | ### `jsesc(value, options)`
|
---|
72 |
|
---|
73 | This function takes a value and returns an escaped version of the value where any characters that are not printable ASCII symbols are escaped using the shortest possible (but valid) [escape sequences for use in JavaScript strings](http://mathiasbynens.be/notes/javascript-escapes). The first supported value type is strings:
|
---|
74 |
|
---|
75 | ```js
|
---|
76 | jsesc('Ich ♥ Bücher');
|
---|
77 | // → 'Ich \\u2665 B\\xFCcher'
|
---|
78 |
|
---|
79 | jsesc('foo 𝌆 bar');
|
---|
80 | // → 'foo \\uD834\\uDF06 bar'
|
---|
81 | ```
|
---|
82 |
|
---|
83 | Instead of a string, the `value` can also be an array, or an object. In such cases, `jsesc` will return a stringified version of the value where any characters that are not printable ASCII symbols are escaped in the same way.
|
---|
84 |
|
---|
85 | ```js
|
---|
86 | // Escaping an array
|
---|
87 | jsesc([
|
---|
88 | 'Ich ♥ Bücher', 'foo 𝌆 bar'
|
---|
89 | ]);
|
---|
90 | // → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'
|
---|
91 |
|
---|
92 | // Escaping an object
|
---|
93 | jsesc({
|
---|
94 | 'Ich ♥ Bücher': 'foo 𝌆 bar'
|
---|
95 | });
|
---|
96 | // → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'
|
---|
97 | ```
|
---|
98 |
|
---|
99 | The optional `options` argument accepts an object with the following options:
|
---|
100 |
|
---|
101 | #### `quotes`
|
---|
102 |
|
---|
103 | The default value for the `quotes` option is `'single'`. This means that any occurences of `'` in the input string will be escaped as `\'`, so that the output can be used in a string literal wrapped in single quotes.
|
---|
104 |
|
---|
105 | ```js
|
---|
106 | jsesc('Lorem ipsum "dolor" sit \'amet\' etc.');
|
---|
107 | // → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
|
---|
108 |
|
---|
109 | jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
|
---|
110 | 'quotes': 'single'
|
---|
111 | });
|
---|
112 | // → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
|
---|
113 | // → "Lorem ipsum \"dolor\" sit \\'amet\\' etc."
|
---|
114 | ```
|
---|
115 |
|
---|
116 | If you want to use the output as part of a string literal wrapped in double quotes, set the `quotes` option to `'double'`.
|
---|
117 |
|
---|
118 | ```js
|
---|
119 | jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
|
---|
120 | 'quotes': 'double'
|
---|
121 | });
|
---|
122 | // → 'Lorem ipsum \\"dolor\\" sit \'amet\' etc.'
|
---|
123 | // → "Lorem ipsum \\\"dolor\\\" sit 'amet' etc."
|
---|
124 | ```
|
---|
125 |
|
---|
126 | This setting also affects the output for arrays and objects:
|
---|
127 |
|
---|
128 | ```js
|
---|
129 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
130 | 'quotes': 'double'
|
---|
131 | });
|
---|
132 | // → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'
|
---|
133 |
|
---|
134 | jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
|
---|
135 | 'quotes': 'double'
|
---|
136 | });
|
---|
137 | // → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'
|
---|
138 | ```
|
---|
139 |
|
---|
140 | #### `wrap`
|
---|
141 |
|
---|
142 | The `wrap` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output will be a valid JavaScript string literal wrapped in quotes. The type of quotes can be specified through the `quotes` setting.
|
---|
143 |
|
---|
144 | ```js
|
---|
145 | jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
|
---|
146 | 'quotes': 'single',
|
---|
147 | 'wrap': true
|
---|
148 | });
|
---|
149 | // → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
|
---|
150 | // → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"
|
---|
151 |
|
---|
152 | jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
|
---|
153 | 'quotes': 'double',
|
---|
154 | 'wrap': true
|
---|
155 | });
|
---|
156 | // → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
|
---|
157 | // → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
|
---|
158 | ```
|
---|
159 |
|
---|
160 | #### `es6`
|
---|
161 |
|
---|
162 | The `es6` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, any astral Unicode symbols in the input will be escaped using [ECMAScript 6 Unicode code point escape sequences](http://mathiasbynens.be/notes/javascript-escapes#unicode-code-point) instead of using separate escape sequences for each surrogate half. If backwards compatibility with ES5 environments is a concern, don’t enable this setting. If the `json` setting is enabled, the value for the `es6` setting is ignored (as if it was `false`).
|
---|
163 |
|
---|
164 | ```js
|
---|
165 | // By default, the `es6` option is disabled:
|
---|
166 | jsesc('foo 𝌆 bar 💩 baz');
|
---|
167 | // → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'
|
---|
168 |
|
---|
169 | // To explicitly disable it:
|
---|
170 | jsesc('foo 𝌆 bar 💩 baz', {
|
---|
171 | 'es6': false
|
---|
172 | });
|
---|
173 | // → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'
|
---|
174 |
|
---|
175 | // To enable it:
|
---|
176 | jsesc('foo 𝌆 bar 💩 baz', {
|
---|
177 | 'es6': true
|
---|
178 | });
|
---|
179 | // → 'foo \\u{1D306} bar \\u{1F4A9} baz'
|
---|
180 | ```
|
---|
181 |
|
---|
182 | #### `escapeEverything`
|
---|
183 |
|
---|
184 | The `escapeEverything` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, all the symbols in the output will be escaped, even printable ASCII symbols.
|
---|
185 |
|
---|
186 | ```js
|
---|
187 | jsesc('lolwat"foo\'bar', {
|
---|
188 | 'escapeEverything': true
|
---|
189 | });
|
---|
190 | // → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
|
---|
191 | // → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"
|
---|
192 | ```
|
---|
193 |
|
---|
194 | This setting also affects the output for arrays and objects:
|
---|
195 |
|
---|
196 | ```js
|
---|
197 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
198 | 'escapeEverything': true
|
---|
199 | });
|
---|
200 | // → '{\'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72\':\'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72\'}'
|
---|
201 | // → "{'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72':'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72'}"
|
---|
202 |
|
---|
203 | jsesc([ 'Ich ♥ Bücher': 'foo 𝌆 bar' ], {
|
---|
204 | 'escapeEverything': true
|
---|
205 | });
|
---|
206 | // → '[\'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72\',\'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72\']'
|
---|
207 | ```
|
---|
208 |
|
---|
209 | #### `compact`
|
---|
210 |
|
---|
211 | The `compact` option takes a boolean value (`true` or `false`), and defaults to `true` (enabled). When enabled, the output for arrays and objects will be as compact as possible; it won’t be formatted nicely.
|
---|
212 |
|
---|
213 | ```js
|
---|
214 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
215 | 'compact': true // this is the default
|
---|
216 | });
|
---|
217 | // → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'
|
---|
218 |
|
---|
219 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
220 | 'compact': false
|
---|
221 | });
|
---|
222 | // → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
|
---|
223 |
|
---|
224 | jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
|
---|
225 | 'compact': false
|
---|
226 | });
|
---|
227 | // → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'
|
---|
228 | ```
|
---|
229 |
|
---|
230 | This setting has no effect on the output for strings.
|
---|
231 |
|
---|
232 | #### `indent`
|
---|
233 |
|
---|
234 | The `indent` option takes a string value, and defaults to `'\t'`. When the `compact` setting is enabled (`true`), the value of the `indent` option is used to format the output for arrays and objects.
|
---|
235 |
|
---|
236 | ```js
|
---|
237 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
238 | 'compact': false,
|
---|
239 | 'indent': '\t' // this is the default
|
---|
240 | });
|
---|
241 | // → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
|
---|
242 |
|
---|
243 | jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
|
---|
244 | 'compact': false,
|
---|
245 | 'indent': ' '
|
---|
246 | });
|
---|
247 | // → '{\n \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
|
---|
248 |
|
---|
249 | jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
|
---|
250 | 'compact': false,
|
---|
251 | 'indent': ' '
|
---|
252 | });
|
---|
253 | // → '[\n \'Ich \u2665 B\xFCcher\',\n\ t\'foo \uD834\uDF06 bar\'\n]'
|
---|
254 | ```
|
---|
255 |
|
---|
256 | This setting has no effect on the output for strings.
|
---|
257 |
|
---|
258 | #### `json`
|
---|
259 |
|
---|
260 | The `json` option takes a boolean value (`true` or `false`), and defaults to `false` (disabled). When enabled, the output is valid JSON. [Hexadecimal character escape sequences](http://mathiasbynens.be/notes/javascript-escapes#hexadecimal) and [the `\v` or `\0` escape sequences](http://mathiasbynens.be/notes/javascript-escapes#single) will not be used. Setting `json: true` implies `quotes: 'double', wrap: true, es6: false`, although these values can still be overridden if needed — but in such cases, the output won’t be valid JSON anymore.
|
---|
261 |
|
---|
262 | ```js
|
---|
263 | jsesc('foo\x00bar\xFF\uFFFDbaz', {
|
---|
264 | 'json': true
|
---|
265 | });
|
---|
266 | // → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'
|
---|
267 |
|
---|
268 | jsesc({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
|
---|
269 | 'json': true
|
---|
270 | });
|
---|
271 | // → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'
|
---|
272 |
|
---|
273 | jsesc([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
|
---|
274 | 'json': true
|
---|
275 | });
|
---|
276 | // → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'
|
---|
277 |
|
---|
278 | // Values that are acceptable in JSON but aren’t strings, arrays, or object
|
---|
279 | // literals can’t be escaped, so they’ll just be preserved:
|
---|
280 | jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
|
---|
281 | 'json': true
|
---|
282 | });
|
---|
283 | // → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
|
---|
284 | // Values that aren’t allowed in JSON are run through `JSON.stringify()`:
|
---|
285 | jsesc([ undefined, -Infinity ], {
|
---|
286 | 'json': true
|
---|
287 | });
|
---|
288 | // → '[null,null]'
|
---|
289 | ```
|
---|
290 |
|
---|
291 | **Note:** Using this option on objects or arrays that contain non-string values relies on `JSON.stringify()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](http://bestiejs.github.io/json3/).
|
---|
292 |
|
---|
293 | ### `jsesc.version`
|
---|
294 |
|
---|
295 | A string representing the semantic version number.
|
---|
296 |
|
---|
297 | ### Using the `jsesc` binary
|
---|
298 |
|
---|
299 | To use the `jsesc` binary in your shell, simply install jsesc globally using npm:
|
---|
300 |
|
---|
301 | ```bash
|
---|
302 | npm install -g jsesc
|
---|
303 | ```
|
---|
304 |
|
---|
305 | After that you will be able to escape strings from the command line:
|
---|
306 |
|
---|
307 | ```bash
|
---|
308 | $ jsesc 'föo ♥ bår 𝌆 baz'
|
---|
309 | f\xF6o \u2665 b\xE5r \uD834\uDF06 baz
|
---|
310 | ```
|
---|
311 |
|
---|
312 | To escape arrays or objects containing string values, use the `-o`/`--object` option:
|
---|
313 |
|
---|
314 | ```bash
|
---|
315 | $ jsesc --object '{ "föo": "♥", "bår": "𝌆 baz" }'
|
---|
316 | {'f\xF6o':'\u2665','b\xE5r':'\uD834\uDF06 baz'}
|
---|
317 | ```
|
---|
318 |
|
---|
319 | To prettify the output in such cases, use the `-p`/`--pretty` option:
|
---|
320 |
|
---|
321 | ```bash
|
---|
322 | $ jsesc --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
|
---|
323 | {
|
---|
324 | 'f\xF6o': '\u2665',
|
---|
325 | 'b\xE5r': '\uD834\uDF06 baz'
|
---|
326 | }
|
---|
327 | ```
|
---|
328 |
|
---|
329 | For valid JSON output, use the `-j`/`--json` option:
|
---|
330 |
|
---|
331 | ```bash
|
---|
332 | $ jsesc --json --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
|
---|
333 | {
|
---|
334 | "f\u00F6o": "\u2665",
|
---|
335 | "b\u00E5r": "\uD834\uDF06 baz"
|
---|
336 | }
|
---|
337 | ```
|
---|
338 |
|
---|
339 | Read a local JSON file, escape any non-ASCII symbols, and save the result to a new file:
|
---|
340 |
|
---|
341 | ```bash
|
---|
342 | $ jsesc --json --object < data-raw.json > data-escaped.json
|
---|
343 | ```
|
---|
344 |
|
---|
345 | Or do the same with an online JSON file:
|
---|
346 |
|
---|
347 | ```bash
|
---|
348 | $ curl -sL "http://git.io/aorKgQ" | jsesc --json --object > data-escaped.json
|
---|
349 | ```
|
---|
350 |
|
---|
351 | See `jsesc --help` for the full list of options.
|
---|
352 |
|
---|
353 | ## Support
|
---|
354 |
|
---|
355 | This library has been tested in at least Chrome 27-29, Firefox 3-22, Safari 4-6, Opera 10-12, IE 6-10, Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, PhantomJS 1.9.0, and Rhino 1.7RC4.
|
---|
356 |
|
---|
357 | **Note:** Using the `json` option on objects or arrays that contain non-string values relies on `JSON.parse()`. For legacy environments like IE ≤ 7, use [a `JSON` polyfill](http://bestiejs.github.io/json3/).
|
---|
358 |
|
---|
359 | ## Unit tests & code coverage
|
---|
360 |
|
---|
361 | 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`.
|
---|
362 |
|
---|
363 | 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`.
|
---|
364 |
|
---|
365 | To generate the code coverage report, use `grunt cover`.
|
---|
366 |
|
---|
367 | ## Author
|
---|
368 |
|
---|
369 | | [![twitter/mathias](https://gravatar.com/avatar/24e08a9ea84deb17ae121074d0f17125?s=70)](https://twitter.com/mathias "Follow @mathias on Twitter") |
|
---|
370 | |---|
|
---|
371 | | [Mathias Bynens](http://mathiasbynens.be/) |
|
---|
372 |
|
---|
373 | ## License
|
---|
374 |
|
---|
375 | This library is available under the [MIT](http://mths.be/mit) license.
|
---|