Mercurial > hg > nginx-site

comparison xml/en/docs/njs/reference.xml @ 2583:cd97adddd757

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Documented Query String in njs Reference.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 11 Aug 2020 12:35:32 +0100
parents e162a71453b0
children 7035221dbe37
comparison
equal deleted inserted replaced
2582:e162a71453b0 2583:cd97adddd757
7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd"> 7 <!DOCTYPE article SYSTEM "../../../../dtd/article.dtd">
8 8
9 <article name="Reference" 9 <article name="Reference"
10 link="/en/docs/njs/reference.html" 10 link="/en/docs/njs/reference.html"
11 lang="en" 11 lang="en"
12 rev="51"> 12 rev="52">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 <link doc="index.xml">njs</link> provides objects, methods and properties 17 <link doc="index.xml">njs</link> provides objects, methods and properties
1252 1252
1253 </section> 1253 </section>
1254 1254
1255 </section> 1255 </section>
1256 1256
1257
1258 <section id="querystring" name="Query String">
1259
1260 <para>
1261 The Query String module provides support
1262 for parsing and formatting URL query strings
1263 (<link doc="changes.xml" id="njs0.4.3">0.4.3</link>).
1264 The Query String module object is returned by
1265 <literal>require('querystring')</literal>.
1266 </para>
1267
1268 <para>
1269 <list type="tag">
1270
1271 <tag-name id="querystring_decode"><literal>querystring.decode()</literal></tag-name>
1272 <tag-desc>
1273 is an alias for
1274 <link id="querystring_parse"><literal>querystring.parse()</literal></link>.
1275 </tag-desc>
1276
1277 <tag-name id="querystring_encode"><literal>querystring.encode()</literal></tag-name>
1278 <tag-desc>
1279 is an alias for
1280 <link id="querystring_stringify"><literal>querystring.stringify()</literal></link>.
1281 </tag-desc>
1282
1283 <tag-name id="querystring_escape"><literal>querystring.escape(<value>string</value>)</literal></tag-name>
1284 <tag-desc>
1285 <para>
1286 Performs URL encoding of the given <literal>string</literal>,
1287 returns an escaped query string.
1288 The method is used by
1289 <link id="querystring_stringify"><literal>querystring.stringify()</literal></link>
1290 and should not be used directly.
1291 </para>
1292 </tag-desc>
1293
1294 <tag-name id="querystring_parse"><literal>querystring.parse(<value>string</value>[,
1295 <value>separator</value>[,
1296 <value>equal</value>[,
1297 <value>options</value>]]])</literal></tag-name>
1298 <tag-desc>
1299 <para>
1300 Parses the query string URL and returns an object.
1301 </para>
1302
1303 <para>
1304 The <literal>separator</literal> parameter is a substring
1305 for delimiting key and value pairs in the query string,
1306 by default is “<literal>&amp;</literal>”.
1307 </para>
1308
1309 <para>
1310 The <literal>equal</literal> parameter is a substring
1311 for delimiting keys and values in the query string,
1312 by default is “<literal>=</literal>”.
1313 </para>
1314
1315 <para>
1316 The <literal>options</literal> parameter is expected to be
1317 an object with the following keys:
1318 <list type="tag">
1319 <tag-name><literal>decodeURIComponent</literal>
1320 <value>function</value></tag-name>
1321 <tag-desc>
1322 Function used
1323 to decode percent-encoded characters in the query string,
1324 by default is
1325 <link id="querystring_unescape"><literal>querystring.unescape()</literal></link>
1326 </tag-desc>
1327
1328 <tag-name><literal>maxKeys</literal>
1329 <value>number</value></tag-name>
1330 <tag-desc>
1331 the maximum number of keys to parse,
1332 by default is <literal>1000</literal>.
1333 The <literal>0</literal> value removes limitations for counting keys.
1334 </tag-desc>
1335
1336 </list>
1337 By default, percent-encoded characters within the query string are assumed
1338 to use the UTF-8 encoding,
1339 invalid UTF-8 sequences will be replaced with
1340 the <literal>U+FFFD</literal> replacement character.
1341 </para>
1342
1343 <para>
1344 For example, for the following query string
1345 <example>
1346 'foo=bar&amp;abc=xyz&amp;abc=123'
1347 </example>
1348 the output will be:
1349 <example>
1350 {
1351 foo: 'bar',
1352 abc: ['xyz', '123']
1353 }
1354 </example>
1355 </para>
1356
1357 </tag-desc>
1358
1359 <tag-name id="querystring_stringify"><literal>querystring.stringify(<value>object</value>[,
1360 <value>separator</value>[,
1361 <value>equal</value>[,
1362 <value>options</value>]]])</literal></tag-name>
1363 <tag-desc>
1364 <para>
1365 Serializes an object and returns a URL query string.
1366 </para>
1367
1368 <para>
1369 The <literal>separator</literal> parameter is a substring
1370 for delimiting key and value pairs in the query string,
1371 by default is “<literal>&amp;</literal>”.
1372 </para>
1373
1374 <para>
1375 The <literal>equal</literal> parameter is a substring
1376 for delimiting keys and values in the query string,
1377 by default is “<literal>=</literal>”.
1378 </para>
1379
1380 <para>
1381 The <literal>options</literal> parameter is expected to be
1382 an object with the following keys:
1383 <list type="tag">
1384 <tag-name><literal>encodeURIComponent</literal>
1385 <value>function</value></tag-name>
1386 <tag-desc>
1387 The function to use when converting
1388 URL-unsafe characters to percent-encoding in the query string,
1389 by default is
1390 <link id="querystring_escape"><literal>querystring.escape()</literal></link>.
1391 </tag-desc>
1392
1393 </list>
1394 </para>
1395
1396 <para>
1397 By default, characters that require percent-encoding within the query string
1398 are encoded as UTF-8.
1399 If other encoding is required, then
1400 <literal>encodeURIComponent</literal> option should be specified.
1401 </para>
1402
1403 <para>
1404 For example, for the following command
1405 <example>
1406 querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], 123: '' });
1407 </example>
1408 the query string will be:
1409 <example>
1410 'foo=bar&amp;baz=qux&amp;baz=quux&amp;123='
1411 </example>
1412 </para>
1413
1414 </tag-desc>
1415
1416 <tag-name id="querystring_unescape"><literal>querystring.unescape(<value>string</value>)</literal></tag-name>
1417 <tag-desc>
1418 <para>
1419 Performs decoding of URL percent-encoded characters
1420 of the <literal>string</literal>,
1421 returns an unescaped query string.
1422 The method is used by
1423 <link id="querystring_parse"><literal>querystring.parse()</literal></link>
1424 and should not be used directly.
1425 </para>
1426 </tag-desc>
1427
1428 </list>
1429 </para>
1430
1431 </section>
1432
1257 </section> 1433 </section>
1258 1434
1259 </article> 1435 </article>