Mercurial > hg > nginx-site

comparison xml/en/docs/njs/njs_api.xml @ 2214:e029f4bc7ede

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added quotes to njs examples.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 31 Jul 2018 17:07:36 +0300
parents c34a885b9d99
children 5268c13196f2
comparison
equal deleted inserted replaced
2213:821807549005 2214:e029f4bc7ede
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="njs API" 9 <article name="njs API"
10 link="/en/docs/njs/njs_api.html" 10 link="/en/docs/njs/njs_api.html"
11 lang="en" 11 lang="en"
12 rev="5"> 12 rev="6">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="../njs_about.xml">njs</link> provides objects, methods and properties 17 <link doc="../njs_about.xml">njs</link> provides objects, methods and properties
43 to external data and deserialize from external sources. 43 to external data and deserialize from external sources.
44 For example, the <link id="string_toutf8">toUTF8()</link> method serializes 44 For example, the <link id="string_toutf8">toUTF8()</link> method serializes
45 a Unicode string to a byte string using UTF8 encoding: 45 a Unicode string to a byte string using UTF8 encoding:
46 <example> 46 <example>
47 >> '£'.toUTF8().toString('hex') 47 >> '£'.toUTF8().toString('hex')
48 c2a3 /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */ 48 'c2a3' /* C2 A3 is the UTF8 representation of 00A3 ('£') code point */
49 </example> 49 </example>
50 The <link id="string_tobytes">toBytes()</link> method serializes 50 The <link id="string_tobytes">toBytes()</link> method serializes
51 a Unicode string with code points up to 255 into a byte string, 51 a Unicode string with code points up to 255 into a byte string,
52 otherwise, <literal>null</literal> is returned: 52 otherwise, <literal>null</literal> is returned:
53 <example> 53 <example>
54 >> '£'.toBytes().toString('hex') 54 >> '£'.toBytes().toString('hex')
55 a3 /* a3 is a byte equal to 00A3 ('£') code point */ 55 'a3' /* a3 is a byte equal to 00A3 ('£') code point */
56 </example> 56 </example>
57 Only byte strings can be converted to different encodings. 57 Only byte strings can be converted to different encodings.
58 For example, a string cannot be encoded to <literal>hex</literal> directly: 58 For example, a string cannot be encoded to <literal>hex</literal> directly:
59 <example> 59 <example>
60 >> 'αβγδ'.toString('base64') 60 >> 'αβγδ'.toString('base64')
64 </example> 64 </example>
65 To convert a Unicode string to hex, 65 To convert a Unicode string to hex,
66 first, it should be converted to a byte string and then to hex: 66 first, it should be converted to a byte string and then to hex:
67 <example> 67 <example>
68 >> 'αβγδ'.toUTF8().toString('base64') 68 >> 'αβγδ'.toUTF8().toString('base64')
69 zrHOss6zzrQ= 69 'zrHOss6zzrQ='
70 </example> 70 </example>
71 71
72 <list type="tag"> 72 <list type="tag">
73 73
74 <tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value> 74 <tag-name id="string_bytesfrom"><literal>String.bytesFrom(<value>array</value>
93 <value>codePoint2</value>]])</literal></tag-name> 93 <value>codePoint2</value>]])</literal></tag-name>
94 <tag-desc> 94 <tag-desc>
95 Returns a string from one or more Unicode code points. 95 Returns a string from one or more Unicode code points.
96 <example> 96 <example>
97 >> String.fromCodePoint(97, 98, 99, 100) 97 >> String.fromCodePoint(97, 98, 99, 100)
98 abcd 98 'abcd'
99 </example> 99 </example>
100 </tag-desc> 100 </tag-desc>
101 101
102 <tag-name><literal>String.prototype.concat(<value>string1</value>[, ..., 102 <tag-name><literal>String.prototype.concat(<value>string1</value>[, ...,
103 <value>stringN</value>])</literal></tag-name> 103 <value>stringN</value>])</literal></tag-name>
104 <tag-desc> 104 <tag-desc>
105 Returns a string that contains the concatenation of specified 105 Returns a string that contains the concatenation of specified
106 <literal>strings</literal>. 106 <literal>strings</literal>.
107 <example> 107 <example>
108 >> "a".concat("b", "c") 108 >> "a".concat("b", "c")
109 abc 109 'abc'
110 </example> 110 </example>
111 </tag-desc> 111 </tag-desc>
112 112
113 <tag-name><literal>String.prototype.endsWith(<value>searchString</value>[, 113 <tag-name><literal>String.prototype.endsWith(<value>searchString</value>[,
114 <value>length</value>])</literal></tag-name> 114 <value>length</value>])</literal></tag-name>
201 <tag-name><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name> 201 <tag-name><literal>String.prototype.match([<value>regexp</value>])</literal></tag-name>
202 <tag-desc> 202 <tag-desc>
203 Matches a string against a <literal>regexp</literal>. 203 Matches a string against a <literal>regexp</literal>.
204 <example> 204 <example>
205 >> 'nginx'.match( /ng/i ) 205 >> 'nginx'.match( /ng/i )
206 ng 206 'ng'
207 </example> 207 </example>
208 </tag-desc> 208 </tag-desc>
209 209
210 <tag-name id="string_padend"><literal>String.prototype.padEnd(<value>length</value> 210 <tag-name id="string_padend"><literal>String.prototype.padEnd(<value>length</value>
211 [, <value>string</value>])</literal></tag-name> 211 [, <value>string</value>])</literal></tag-name>
235 <tag-desc> 235 <tag-desc>
236 Returns a string 236 Returns a string
237 with the specified <literal>number</literal> of copies of the string. 237 with the specified <literal>number</literal> of copies of the string.
238 <example> 238 <example>
239 >> 'abc'.repeat(3) 239 >> 'abc'.repeat(3)
240 abcabcabc 240 'abcabcabc'
241 </example> 241 </example>
242 </tag-desc> 242 </tag-desc>
243 243
244 <tag-name><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[, 244 <tag-name><literal>String.prototype.replace([<value>regexp</value>|<value>string</value>[,
245 <value>string</value>|<value>function</value>]])</literal></tag-name> 245 <value>string</value>|<value>function</value>]])</literal></tag-name>
247 Returns a new string with matches of a pattern 247 Returns a new string with matches of a pattern
248 (<literal>string</literal> or a <literal>regexp</literal>) 248 (<literal>string</literal> or a <literal>regexp</literal>)
249 replaced by a <literal>string</literal> or a <literal>function</literal>. 249 replaced by a <literal>string</literal> or a <literal>function</literal>.
250 <example> 250 <example>
251 >> 'abcdefgh'.replace('d', 1) 251 >> 'abcdefgh'.replace('d', 1)
252 abc1efgh 252 'abc1efgh'
253 </example> 253 </example>
254 </tag-desc> 254 </tag-desc>
255 255
256 <tag-name><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name> 256 <tag-name><literal>String.prototype.search([<value>regexp</value>])</literal></tag-name>
257 <tag-desc> 257 <tag-desc>
269 original string between <literal>start</literal> 269 original string between <literal>start</literal>
270 and <literal>end</literal> or 270 and <literal>end</literal> or
271 from <literal>start</literal> to the end of the string. 271 from <literal>start</literal> to the end of the string.
272 <example> 272 <example>
273 >> 'abcdefghijklmno'.slice(NaN, 5) 273 >> 'abcdefghijklmno'.slice(NaN, 5)
274 abcde 274 'abcde'
275 </example> 275 </example>
276 </tag-desc> 276 </tag-desc>
277 277
278 <tag-name><literal>String.prototype.startsWith(<value>searchString</value>[, 278 <tag-name><literal>String.prototype.startsWith(<value>searchString</value>[,
279 <value>position</value>])</literal></tag-name> 279 <value>position</value>])</literal></tag-name>
297 Returns the part of the string of the specified <literal>length</literal> 297 Returns the part of the string of the specified <literal>length</literal>
298 from <literal>start</literal> 298 from <literal>start</literal>
299 or from <literal>start</literal> to the end of the string. 299 or from <literal>start</literal> to the end of the string.
300 <example> 300 <example>
301 >> 'abcdefghijklmno'.substr(3, 5) 301 >> 'abcdefghijklmno'.substr(3, 5)
302 defgh 302 'defgh'
303 </example> 303 </example>
304 </tag-desc> 304 </tag-desc>
305 305
306 <tag-name><literal>String.prototype.substring(<value>start</value>[, 306 <tag-name><literal>String.prototype.substring(<value>start</value>[,
307 <value>end</value>])</literal></tag-name> 307 <value>end</value>])</literal></tag-name>
309 Returns the part of the string between 309 Returns the part of the string between
310 <literal>start</literal> and <literal>end</literal> or 310 <literal>start</literal> and <literal>end</literal> or
311 from <literal>start</literal> to the end of the string. 311 from <literal>start</literal> to the end of the string.
312 <example> 312 <example>
313 >> 'abcdefghijklmno'.substring(3, 5) 313 >> 'abcdefghijklmno'.substring(3, 5)
314 de 314 'de'
315 </example> 315 </example>
316 </tag-desc> 316 </tag-desc>
317 317
318 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[, 318 <tag-name id="string_tobytes"><literal>String.prototype.toBytes(start[,
319 end])</literal></tag-name> 319 end])</literal></tag-name>
327 <tag-desc> 327 <tag-desc>
328 Converts a string to lower case. 328 Converts a string to lower case.
329 The method supports only simple Unicode folding. 329 The method supports only simple Unicode folding.
330 <example> 330 <example>
331 >> 'ΑΒΓΔ'.toLowerCase() 331 >> 'ΑΒΓΔ'.toLowerCase()
332 αβγδ 332 'αβγδ'
333 </example> 333 </example>
334 </tag-desc> 334 </tag-desc>
335 335
336 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name> 336 <tag-name><literal>String.prototype.toString([<value>encoding</value>])</literal></tag-name>
337 <tag-desc> 337 <tag-desc>
347 <literal>base64</literal>, or 347 <literal>base64</literal>, or
348 <literal>base64url</literal>. 348 <literal>base64url</literal>.
349 </para> 349 </para>
350 <example> 350 <example>
351 >> 'αβγδ'.toUTF8().toString('base64url') 351 >> 'αβγδ'.toUTF8().toString('base64url')
352 zrHOss6zzrQ 352 'zrHOss6zzrQ'
353 </example> 353 </example>
354 </tag-desc> 354 </tag-desc>
355 355
356 <tag-name><literal>String.prototype.toUpperCase()</literal></tag-name> 356 <tag-name><literal>String.prototype.toUpperCase()</literal></tag-name>
357 <tag-desc> 357 <tag-desc>
358 Converts a string to upper case. 358 Converts a string to upper case.
359 The method supports only simple Unicode folding. 359 The method supports only simple Unicode folding.
360 <example> 360 <example>
361 >> 'αβγδ'.toUpperCase() 361 >> 'αβγδ'.toUpperCase()
362 ΑΒΓΔ 362 'ΑΒΓΔ'
363 </example> 363 </example>
364 </tag-desc> 364 </tag-desc>
365 365
366 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[, 366 <tag-name id="string_toutf8"><literal>String.prototype.toUTF8(<value>start</value>[,
367 <value>end</value>])</literal></tag-name> 367 <value>end</value>])</literal></tag-name>
379 <tag-name><literal>String.prototype.trim()</literal></tag-name> 379 <tag-name><literal>String.prototype.trim()</literal></tag-name>
380 <tag-desc> 380 <tag-desc>
381 Removes whitespaces from both ends of a string. 381 Removes whitespaces from both ends of a string.
382 <example> 382 <example>
383 >> ' abc '.trim() 383 >> ' abc '.trim()
384 abc 384 'abc'
385 </example> 385 </example>
386 </tag-desc> 386 </tag-desc>
387 387
388 <tag-name><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[, 388 <tag-name><literal>String.prototype.split(([<value>string</value>|<value>regexp</value>[,
389 <value>limit</value>]]))</literal></tag-name> 389 <value>limit</value>]]))</literal></tag-name>
391 Returns match of a string against a <literal>regexp</literal>. 391 Returns match of a string against a <literal>regexp</literal>.
392 The optional <literal>limit</literal> parameter is an integer that specifies 392 The optional <literal>limit</literal> parameter is an integer that specifies
393 a limit on the number of splits to be found. 393 a limit on the number of splits to be found.
394 <example> 394 <example>
395 >> 'abc'.split('') 395 >> 'abc'.split('')
396 a,b,c 396 [
397 'a',
398 'b',
399 'c'
400 ]
397 </example> 401 </example>
398 </tag-desc> 402 </tag-desc>
399 403
400 <tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name> 404 <tag-name id="encodeuri"><literal>encodeURI(<value>URI</value>)</literal></tag-name>
401 <tag-desc> 405 <tag-desc>
402 encodes a URI by replacing each instance of certain characters by 406 encodes a URI by replacing each instance of certain characters by
403 one, two, three, or four escape sequences 407 one, two, three, or four escape sequences
404 representing the UTF-8 encoding of the character 408 representing the UTF-8 encoding of the character
405 <example> 409 <example>
406 >> encodeURI('012αβγδ') 410 >> encodeURI('012αβγδ')
407 012%CE%B1%CE%B2%CE%B3%CE%B4 411 '012%CE%B1%CE%B2%CE%B3%CE%B4'
408 </example> 412 </example>
409 </tag-desc> 413 </tag-desc>
410 414
411 <tag-name><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name> 415 <tag-name><literal>encodeURIComponent(<value>encodedURIString</value>)</literal></tag-name>
412 <tag-desc> 416 <tag-desc>
413 Encodes a URI by replacing each instance of certain characters 417 Encodes a URI by replacing each instance of certain characters
414 by one, two, three, or four escape sequences 418 by one, two, three, or four escape sequences
415 representing the UTF-8 encoding of the character. 419 representing the UTF-8 encoding of the character.
416 <example> 420 <example>
417 >> encodeURIComponent('[@?=') 421 >> encodeURIComponent('[@?=')
418 %5B%40%3F%3D 422 '%5B%40%3F%3D'
419 </example> 423 </example>
420 </tag-desc> 424 </tag-desc>
421 425
422 <tag-name><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name> 426 <tag-name><literal>decodeURI(<value>encodedURI</value>)</literal></tag-name>
423 <tag-desc> 427 <tag-desc>
424 Decodes a previously <link id="encodeuri">encoded</link> URI. 428 Decodes a previously <link id="encodeuri">encoded</link> URI.
425 <example> 429 <example>
426 >> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4') 430 >> decodeURI('012%CE%B1%CE%B2%CE%B3%CE%B4')
427 012αβγδ 431 '012αβγδ'
428 </example> 432 </example>
429 </tag-desc> 433 </tag-desc>
430 434
431 <tag-name><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name> 435 <tag-name><literal>decodeURIComponent(<value>decodedURIString</value>)</literal></tag-name>
432 <tag-desc> 436 <tag-desc>
433 Decodes an encoded component of a previously encoded URI. 437 Decodes an encoded component of a previously encoded URI.
434 <example> 438 <example>
435 >> decodeURIComponent('%5B%40%3F%3D') 439 >> decodeURIComponent('%5B%40%3F%3D')
436 [@?= 440 '[@?='
437 </example> 441 </example>
438 </tag-desc> 442 </tag-desc>
439 443
440 </list> 444 </list>
441 </para> 445 </para>
488 >> var json = JSON.parse('{"a":1, "b":true}') 492 >> var json = JSON.parse('{"a":1, "b":true}')
489 >> json.a 493 >> json.a
490 1 494 1
491 495
492 >> JSON.stringify(json) 496 >> JSON.stringify(json)
493 {"a":1,"b":true} 497 '{"a":1,"b":true}'
494 498
495 >> JSON.stringify(json, undefined, 1) 499 >> JSON.stringify(json, undefined, 1)
496 { 500 '{\n "a": 1,\n "b": true\n}'
497 "a": 1,
498 "b": true
499 }
500 501
501 >> JSON.stringify({ x: [10, undefined, function(){}] }) 502 >> JSON.stringify({ x: [10, undefined, function(){}] })
502 {"x":[10,null,null]} 503 '{"x":[10,null,null]}'
503 504
504 >> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}}) 505 >> JSON.stringify({"a":1, "toJSON": function() {return "xxx"}})
505 "xxx" 506 '"xxx"'
506 507
507 # Example with function replacer 508 # Example with function replacer
508 509
509 >> function replacer(key, value) {return (typeof value === 'string') ? undefined : value} 510 >> function replacer(key, value) {return (typeof value === 'string') ? undefined : value}
510 >>JSON.stringify({a:1, b:"b", c:true}, replacer) 511 >>JSON.stringify({a:1, b:"b", c:true}, replacer)
511 {"a":1,"c":true} 512 '{"a":1,"c":true}'
512 </example> 513 </example>
513 </para> 514 </para>
514 515
515 </section> 516 </section>
516 517
579 <example> 580 <example>
580 >> var cr = require('crypto') 581 >> var cr = require('crypto')
581 undefined 582 undefined
582 583
583 >> cr.createHash('sha1').update('A').update('B').digest('base64url') 584 >> cr.createHash('sha1').update('A').update('B').digest('base64url')
584 BtlFlCqiamG-GMPiK_GbvKjdK10 585 'BtlFlCqiamG-GMPiK_GbvKjdK10'
585 </example> 586 </example>
586 </para> 587 </para>
587 588
588 </section> 589 </section>
589 590
615 <example> 616 <example>
616 >> var cr = require('crypto') 617 >> var cr = require('crypto')
617 undefined 618 undefined
618 619
619 >> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url') 620 >> cr.createHmac('sha1', 'secret.key').update('AB').digest('base64url')
620 Oglm93xn23_MkiaEq_e9u8zk374 621 'Oglm93xn23_MkiaEq_e9u8zk374'
621 </example> 622 </example>
622 </para> 623 </para>
623 624
624 </section> 625 </section>
625 626