Mercurial > hg > nginx-site

comparison xml/en/docs/njs/index.xml @ 2244:467aef18bf12

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Renamed the "About njs" page.
author Yaroslav Zhuravlev <yar@nginx.com>
date Mon, 24 Sep 2018 19:10:17 +0300
parents xml/en/docs/njs_about.xml@f134633cff5c
children 87a0e2c73a25
comparison
equal deleted inserted replaced
2243:8cc7642ba82e 2244:467aef18bf12
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8
9 <article name="njs scripting language"
10 link="/en/docs/njs/index.html"
11 lang="en"
12 rev="23">
13
14 <section id="summary">
15
16 <para>
17 njs is a subset of the JavaScript language that allows
18 implementing location and variable handlers in
19 <link doc="../http/ngx_http_js_module.xml">http</link> and
20 <link doc="../stream/ngx_stream_js_module.xml">stream</link>.
21 njs is created in compliance with
22 <link url="http://www.ecma-international.org/ecma-262/5.1/">ECMAScript 5.1</link>
23 (strict mode) with some
24 <link url="http://www.ecma-international.org/ecma-262/6.0/">ECMAScript 6</link>
25 extensions.
26 The compliance is still evolving.
27 </para>
28
29 </section>
30
31
32 <section id="supported" name="What is currently supported">
33
34 <para>
35 <list type="bullet">
36
37 <listitem>
38 Boolean values, numbers, strings, objects, arrays,
39 functions, and regular expressions
40 </listitem>
41
42 <listitem>
43 ES5.1 operators, ES7 exponentiation operators
44 </listitem>
45
46 <listitem>
47 ES5.1 statements: <literal>var</literal>, <literal>if</literal>,
48 <literal>else</literal>, <literal>switch</literal>, <literal>for</literal>,
49 <literal>for in</literal>, <literal>while</literal>,
50 <literal>do while</literal>, <literal>break</literal>,
51 <literal>continue</literal>, <literal>return</literal>, <literal>try</literal>,
52 <literal>catch</literal>, <literal>throw</literal>, <literal>finally</literal>
53 </listitem>
54
55 <listitem>
56 ES6 <literal>Number</literal> and
57 <literal>Math</literal> properties and methods
58 </listitem>
59
60 <listitem>
61 <literal>String</literal> methods:
62 <list type="bullet">
63
64 <listitem>
65 ES5.1:
66 <literal>fromCharCode</literal>, <literal>concat</literal>,
67 <literal>slice</literal>, <literal>substring</literal>,
68 <literal>substr</literal>, <literal>charAt</literal>,
69 <literal>charCodeAt</literal>, <literal>indexOf</literal>,
70 <literal>lastIndexOf</literal>, <literal>toLowerCase</literal>,
71 <literal>toUpperCase</literal>, <literal>trim</literal>,
72 <literal>search</literal>, <literal>match</literal>, <literal>split</literal>,
73 <literal>replace</literal>
74 </listitem>
75
76 <listitem>
77 ES6:
78 <literal>fromCodePoint</literal>, <literal>codePointAt</literal>,
79 <literal>includes</literal>, <literal>startsWith</literal>,
80 <literal>endsWith</literal>, <literal>repeat</literal>
81 </listitem>
82
83 <listitem>
84 non-standard:
85 <literal>bytesFrom</literal> (0.2.3)
86 <literal>fromUTF8</literal>, <literal>toUTF8</literal>,
87 <literal>fromBytes</literal>, <literal>toBytes</literal>
88 </listitem>
89 </list>
90
91 </listitem>
92
93 <listitem>
94 <literal>Object</literal> methods:
95 <list type="bullet">
96 <listitem>
97 ES5.1:
98 <literal>create</literal> (support without properties list),
99 <literal>keys</literal>,
100 <literal>defineProperty</literal>,
101 <literal>defineProperties</literal>,
102 <literal>getOwnPropertyDescriptor</literal>,
103 <literal>getPrototypeOf</literal>,
104 <literal>hasOwnProperty</literal>,
105 <literal>isPrototypeOf</literal>,
106 <literal>preventExtensions</literal>,
107 <literal>isExtensible</literal>,
108 <literal>freeze</literal>,
109 <literal>isFrozen</literal>,
110 <literal>seal</literal>,
111 <literal>isSealed</literal>
112 </listitem>
113 </list>
114
115 </listitem>
116
117 <listitem>
118 <literal>Array</literal> methods:
119 <list type="bullet">
120 <listitem>
121 ES5.1:
122 <literal>isArray</literal>, <literal>slice</literal>, <literal>splice</literal>,
123 <literal>push</literal>, <literal>pop</literal>, <literal>unshift</literal>,
124 <literal>shift</literal>, <literal>reverse</literal>, <literal>sort</literal>,
125 <literal>join</literal>, <literal>concat</literal>, <literal>indexOf</literal>,
126 <literal>lastIndexOf</literal>, <literal>forEach</literal>,
127 <literal>some</literal>, <literal>every</literal>, <literal>filter</literal>,
128 <literal>map</literal>, <literal>reduce</literal>,
129 <literal>reduceRight</literal>
130 </listitem>
131
132 <listitem>
133 ES6:
134 <literal>of</literal>, <literal>fill</literal>, <literal>find</literal>,
135 <literal>findIndex</literal>
136 </listitem>
137
138 <listitem>
139 ES7: <literal>includes</literal>
140 </listitem>
141 </list>
142
143 </listitem>
144
145 <listitem>
146 ES5.1 <literal>Function</literal> methods:
147 <literal>call</literal>, <literal>apply</literal>, <literal>bind</literal>
148 </listitem>
149
150 <listitem>
151 ES5.1 <literal>RegExp</literal> methods:
152 <literal>test</literal>, <literal>exec</literal>
153 </listitem>
154
155 <listitem>
156 ES5.1 <literal>Date</literal> methods
157 </listitem>
158
159 <listitem>
160 ES5.1 <literal>JSON</literal> object
161 </listitem>
162
163 <listitem>
164 ES5.1 global functions:
165 <literal>isFinite</literal>, <literal>isNaN</literal>,
166 <literal>parseFloat</literal>, <literal>parseInt</literal>,
167 <literal>decodeURI</literal>, <literal>decodeURIComponent</literal>,
168 <literal>encodeURI</literal>, <literal>encodeURIComponent</literal>
169 </listitem>
170
171 <listitem>
172 <literal>Error</literal> objects:
173 <literal>Error</literal>, <literal>EvalError</literal>,
174 <literal>InternalError</literal>, <literal>RangeError</literal>,
175 <literal>ReferenceError</literal>, <literal>SyntaxError</literal>,
176 <literal>TypeError</literal>, <literal>URIError</literal>
177 </listitem>
178
179 <listitem>
180 <literal>setTimeout()</literal> and <literal>clearTimeout()</literal> functions
181 (0.2.0)
182 </listitem>
183
184 <listitem>
185 <link url="https://nodejs.org/api/fs.html#fs_file_system">Node.js style</link>
186 <literal>File system</literal> methods:
187 <literal>fs.readFile</literal>, <literal>fs.readFileSync</literal>,
188 <literal>fs.appendFile</literal>, <literal>fs.appendFileSync</literal>,
189 <literal>fs.writeFile</literal>, <literal>fs.writeFileSync</literal>
190 </listitem>
191
192 <listitem>
193 <link url="https://nodejs.org/api/crypto.html#crypto_class_hash">Node.js style</link>
194 <literal>Crypto</literal> methods (0.2.0):
195 <literal>crypto.createHash</literal>,
196 <literal>crypto.createHmac</literal>
197
198 </listitem>
199
200 </list>
201 </para>
202
203 </section>
204
205
206 <section id="not_supported" name="What is not supported yet">
207
208 <para>
209 <list type="bullet">
210
211 <listitem>
212 ES6 <literal>let</literal> and <literal>const</literal> declarations
213 </listitem>
214
215 <listitem>
216 labels
217 </listitem>
218
219 <listitem>
220 <literal>arguments</literal> array
221 </listitem>
222
223 <listitem>
224 <literal>eval</literal> function
225 </listitem>
226
227 <listitem>
228 <literal>new Function()</literal> constructor
229 </listitem>
230
231 <listitem>
232 <literal>setInterval</literal>,
233 <literal>setImmediate</literal> functions
234 </listitem>
235
236 <listitem>
237 non-integer fractions (<literal>.235</literal>)
238 </listitem>
239
240 </list>
241 </para>
242
243 </section>
244
245
246 <section id="changelog" name="Change Log">
247
248 <para>
249 The complete list of njs changes is available
250 <link doc="njs_changes.xml">here</link>.
251 </para>
252 </section>
253
254
255 <section id="njs_api" name="njs API Reference">
256
257 <para>
258 njs API reference is available
259 <link doc="njs_api.xml">here</link>.
260 </para>
261 </section>
262
263
264 <section id="install" name="Download and install">
265
266 <para>
267 njs is available in two modules:
268 <list type="bullet">
269
270 <listitem>
271 <link doc="../http/ngx_http_js_module.xml">ngx_http_js_module</link>
272 </listitem>
273
274 <listitem>
275 <link doc="../stream/ngx_stream_js_module.xml">ngx_stream_js_module</link>
276 </listitem>
277
278 </list>
279 Both modules are not built by default,
280 they should be either compiled from the sources
281 or installed as a Linux package.
282 In addition, the Linux package provides
283 njs command-line <link id="cli">utility</link>.
284 </para>
285
286
287 <section id="install_package" name="Installing as a Linux package">
288 <para>
289 For Linux, njs modules
290 <link doc="../../linux_packages.xml" id="dynmodules">packages</link> can be used:
291 <list type="bullet">
292
293 <listitem>
294 <literal>nginx-module-njs</literal> — njs
295 <link doc="../ngx_core_module.xml" id="load_module">dynamic</link> modules
296 </listitem>
297
298 <listitem>
299 <literal>nginx-module-njs-dbg</literal> — debug symbols for the
300 <literal>nginx-module-njs</literal> package
301 </listitem>
302
303 </list>
304 </para>
305
306 </section>
307
308
309 <section id="install_sources" name="Building from the sources">
310
311 <para>
312 The <link url="http://hg.nginx.org/njs">repository</link>
313 with njs sources can be cloned with the following command:
314 (requires <link url="https://www.mercurial-scm.org">Mercurial</link> client):
315 <example>
316 hg clone http://hg.nginx.org/njs
317 </example>
318 Then the modules should be compiled using the
319 <literal>--add-module</literal> configuration parameter:
320 <example>
321 ./configure --add-module=<value>path-to-njs</value>/nginx
322 </example>
323 The modules can also be built as
324 <link doc="../ngx_core_module.xml" id="load_module">dynamic</link>:
325 <example>
326 ./configure --add-dynamic-module=<value>path-to-njs</value>/nginx
327 </example>
328 </para>
329
330 <para>
331 To build only njs command-line <link id="cli">utility</link>, run
332 <literal>./configure</literal> and <literal>make njs</literal> commands
333 from njs root directory.
334 The utility is available as <literal>./build/njs</literal>.
335 </para>
336
337 </section>
338
339 </section>
340
341
342 <section id="cli" name="Command-line interface">
343
344 <para>
345 njs scripts development and debugging can be performed
346 from the command-line.
347 The command-line utility is available after the installation of
348 the Linux <link id="install_package">package</link>
349 or after building from the <link id="install_sources">sources</link>.
350 Compared to njs running inside nginx,
351 nginx objects
352 (<link doc="njs_api.xml" id="http">HTTP</link> and
353 <link doc="njs_api.xml" id="stream">Stream</link>)
354 are not available in the utility.
355 <example>
356 $ echo "2**3" | njs -
357 8
358
359 $ njs
360 >> var o = {a:[]}
361 undefined
362
363 >> JSON.stringify(o, undefined,1)
364 {
365 "a": [
366
367 ]
368 }
369 >>
370 </example>
371 </para>
372
373 </section>
374
375 </article>