diff options
author | James M Snell <jasnell@gmail.com> | 2016-05-27 21:33:07 +0300 |
---|---|---|
committer | James M Snell <jasnell@gmail.com> | 2016-06-06 18:35:19 +0300 |
commit | 80f1fbb00fbb02b68f23b4fd1ce8e5ae22c2eee3 (patch) | |
tree | acb597563024939108ec4f584247b518f6fa6047 /doc/api/querystring.md | |
parent | 267556762dee3daf723c2ea617d413d42ba6d59a (diff) |
doc: general improvements to querystring.md copy
PR-URL: https://github.com/nodejs/node/pull/7023
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
Diffstat (limited to 'doc/api/querystring.md')
-rw-r--r-- | doc/api/querystring.md | 119 |
1 files changed, 84 insertions, 35 deletions
diff --git a/doc/api/querystring.md b/doc/api/querystring.md index 263f44e1990..9b87e76f649 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -4,58 +4,94 @@ <!--name=querystring--> -This module provides utilities for dealing with query strings. -It provides the following methods: +The `querystring` module provides utilities for parsing and formatting URL +query strings. It can be accessed using: -## querystring.escape +```js +const querystring = require('querystring'); +``` + +## querystring.escape(str) <!-- YAML added: v0.1.25 --> -The escape function used by `querystring.stringify`, -provided so that it could be overridden if necessary. +* `str` {String} + +The `querystring.escape()` method performs URL percent-encoding on the given +`str` in a manner that is optimized for the specific requirements of URL +query strings. -## querystring.parse(str[, sep][, eq][, options]) +The `querystring.escape()` method is used by `querystring.stringify()` and is +generally not expected to be used directly. It is exported primarily to allow +application code to provide a replacement percent-encoding implementation if +necessary by assigning `querystring.escape` to an alternative function. + +## querystring.parse(str[, sep[, eq[, options]]]) <!-- YAML added: v0.1.25 --> -Deserialize a query string to an object. -Optionally override the default separator (`'&'`) and assignment (`'='`) -characters. +* `str` {String} The URL query string to parse +* `sep` {String} The substring used to delimit key and value pairs in the + query string. Defaults to `'&'`. +* `eq` {String}. The substring used to delimit keys and values in the + query string. Defaults to `'='`. +* `options` {Object} + * `decodeURIComponent` {Function} The function to use when decoding + percent-encoded characters in the query string. Defaults to + `querystring.unescape()`. + * `maxKeys` {number} Specifies the maximum number of keys to parse. + Defaults to `1000`. Specify `0` to remove key counting limitations. + +The `querystring.parse()` method parses a URL query string (`str`) into a +collection of key and value pairs. -Options object may contain `maxKeys` property (equal to 1000 by default), it'll -be used to limit processed keys. Set it to 0 to remove key count limitation. +For example, the query string `'foo=bar&abc=xyz&abc=123'` is parsed into: -Options object may contain `decodeURIComponent` property (`querystring.unescape` by default), -it can be used to decode a `non-utf8` encoding string if necessary. +```js +{ + foo: 'bar', + abc: ['xyz', '123'] +} +``` -Example: +*Note*: The object returned by the `querystring.parse()` method _does not_ +prototypically extend from the JavaScript `Object`. This means that the +typical `Object` methods such as `obj.toString()`, `obj.hashOwnProperty()`, +and others are not defined and *will not work*. + +By default, percent-encoded characters within the query string will be assumed +to use UTF-8 encoding. If an alternative character encoding is used, then an +alternative `decodeURIComponent` option will need to be specified as illustrated +in the following example: ```js -querystring.parse('foo=bar&baz=qux&baz=quux&corge') -// returns { foo: 'bar', baz: ['qux', 'quux'], corge: '' } +// Assuming gbkDecodeURIComponent function already exists... -// Suppose gbkDecodeURIComponent function already exists, -// it can decode `gbk` encoding string querystring.parse('w=%D6%D0%CE%C4&foo=bar', null, null, { decodeURIComponent: gbkDecodeURIComponent }) -// returns { w: '中文', foo: 'bar' } ``` -## querystring.stringify(obj[, sep][, eq][, options]) +## querystring.stringify(obj[, sep[, eq[, options]]]) <!-- YAML added: v0.1.25 --> -Serialize an object to a query string. -Optionally override the default separator (`'&'`) and assignment (`'='`) -characters. +* `obj` {Object} The object to serialize into a URL query string +* `sep` {String} The substring used to delimit key and value pairs in the + query string. Defaults to `'&'`. +* `eq` {String}. The substring used to delimit keys and values in the + query string. Defaults to `'='`. +* `options` + * `encodeURIComponent` {Function} The function to use when converting + URL-unsafe characters to percent-encoding in the query string. Defaults to + `querystring.escape()`. -Options object may contain `encodeURIComponent` property (`querystring.escape` by default), -it can be used to encode string with `non-utf8` encoding if necessary. +The `querystring.stringify()` method produces a URL query string from a +given `obj` by iterating through the object's "own properties". -Example: +For example: ```js querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' }) @@ -63,22 +99,35 @@ querystring.stringify({ foo: 'bar', baz: ['qux', 'quux'], corge: '' }) querystring.stringify({foo: 'bar', baz: 'qux'}, ';', ':') // returns 'foo:bar;baz:qux' +``` + +By default, characters requiring percent-encoding within the query string will +be encoded as UTF-8. If an alternative encoding is required, then an alternative +`encodeURIComponent` option will need to be specified as illustrated in the +following example: + +```js +// Assuming gbkEncodeURIComponent function already exists, -// Suppose gbkEncodeURIComponent function already exists, -// it can encode string with `gbk` encoding querystring.stringify({ w: '中文', foo: 'bar' }, null, null, { encodeURIComponent: gbkEncodeURIComponent }) -// returns 'w=%D6%D0%CE%C4&foo=bar' ``` -## querystring.unescape +## querystring.unescape(str) <!-- YAML added: v0.1.25 --> +* `str` {String} + + +The `querystring.unescape()` method performs decoding of URL percent-encoded +characters on the given `str`. -The unescape function used by `querystring.parse`, -provided so that it could be overridden if necessary. +The `querystring.unescape()` method is used by `querystring.parse()` and is +generally not expected to be used directly. It is exported primarily to allow +application code to provide a replacement decoding implementation if +necessary by assigning `querystring.unescape` to an alternative function. -It will try to use `decodeURIComponent` in the first place, -but if that fails it falls back to a safer equivalent that -doesn't throw on malformed URLs. +By default, the `querystring.unescape()` method will attempt to use the +JavaScript built-in `decodeURIComponent()` method to decode. If that fails, +a safer equivalent that does not throw on malformed URLs will be used. |