lukechilds
/
node
mirror of https://github.com/lukechilds/node.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

doc/url: various improvements to WHATWG API 

Also remove executable bit from doc/api/url.md's mode.

PR-URL: https://github.com/nodejs/node/pull/11330
Fixes: 4757ddcce1 "doc: add basic documentation for WHATWG URL API"
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
v6
Timothy Gu 8 years ago
parent
6cea5dd39f
commit
bd07c8fc12
1 changed files with 195 additions and 40 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 235
      doc/api/url.md

235
doc/api/url.md
View File

@ -311,6 +311,35 @@ console.log(myURL.pathname); // /foo
*Note*: Using the `delete` keyword (e.g. `delete myURL.protocol`,
`delete myURL.pathname`, etc) has no effect but will still return `true`.
A comparison between this API and `url.parse()` is given below. Above the URL
`'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`, properties of an
object returned by `url.parse()` are shown. Below it are properties of a WHATWG
`URL` object.
*Note*: WHATWG URL's `origin` property includes `protocol` and `host`, but not
`username` or `password`.
```txt
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ href │
├──────────┬──┬─────────────────────┬─────────────────┬───────────────────────────┬───────┤
│ protocol │ │ auth │ host │ path │ hash │
│ │ │ ├──────────┬──────┼──────────┬────────────────┤ │
│ │ │ │ hostname │ port │ pathname │ search │ │
│ │ │ │ │ │ ├─┬──────────────┤ │
│ │ │ │ │ │ │ │ query │ │
" http: // user : pass @ host.com : 8080 /p/a/t/h ? query=string #hash "
│ │ │ │ │ hostname │ port │ │ │ │
│ │ │ │ ├──────────┴──────┤ │ │ │
│ protocol │ │ username │ password │ host │ │ │ │
├──────────┴──┼──────────┴──────────┼─────────────────┤ │ │ │
│ origin │ │ origin │ pathname │ search │ hash │
├─────────────┴─────────────────────┴─────────────────┴──────────┴────────────────┴───────┤
│ href │
└─────────────────────────────────────────────────────────────────────────────────────────┘
(all spaces in the "" line should be ignored -- they are purely for formatting)
```
### Class: URL
#### Constructor: new URL(input[, base])
@ -340,13 +369,15 @@ automatically converted to ASCII using the [Punycode][] algorithm.
```js
const myURL = new URL('https://你好你好');
// https://xn--6qqa088eba
// https://xn--6qqa088eba/
```
Additional [examples of parsed URLs][] may be found in the WHATWG URL Standard.
#### url.hash
* {String}
Gets and sets the fragment portion of the URL.
```js
@ -360,12 +391,14 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `hash` property
are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
are [percent-encoded][]. Note that the selection of which characters to
percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.host
* {String}
Gets and sets the host portion of the URL.
```js
@ -382,6 +415,8 @@ Invalid host values assigned to the `host` property are ignored.
#### url.hostname
* {String}
Gets and sets the hostname portion of the URL. The key difference between
`url.host` and `url.hostname` is that `url.hostname` does *not* include the
port.
@ -400,6 +435,8 @@ Invalid hostname values assigned to the `hostname` property are ignored.
#### url.href
* {String}
Gets and sets the serialized URL.
```js
@ -411,15 +448,20 @@ myURL.href = 'https://example.com/bar'
// Prints https://example.com/bar
```
Setting the value of the `href` property to a new value is equivalent to
creating a new `URL` object using `new URL(value)`. Each of the `URL` object's
properties will be modified.
Getting the value of the `href` property is equivalent to calling
[`url.toString()`][].
Setting the value of this property to a new value is equivalent to creating a
new `URL` object using [`new URL(value)`][`new URL()`]. Each of the `URL`
object's properties will be modified.
If the value assigned to the `href` property is not a valid URL, a `TypeError`
will be thrown.
#### url.origin
* {String}
Gets the read-only serialization of the URL's origin. Unicode characters that
may be contained within the hostname will be encoded as-is without [Punycode][]
encoding.
@ -441,6 +483,8 @@ console.log(idnURL.hostname);
#### url.password
* {String}
Gets and sets the password portion of the URL.
```js
@ -454,12 +498,14 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `password` property
are [percent-encoded](#whatwg-percent-encoding). Note that the selection of
which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
are [percent-encoded][]. Note that the selection of which characters to
percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.pathname
* {String}
Gets and sets the path portion of the URL.
```js
@ -473,23 +519,54 @@ console.log(myURL.href);
```
Invalid URL characters included in the value assigned to the `pathname`
property are [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property are [percent-encoded][]. Note that the selection of which characters
to percent-encode may vary somewhat from what the [`url.parse()`][] and
[`url.format()`][] methods would produce.
#### url.port
Gets and sets the port portion of the URL. When getting the port, the value
is returned as a String.
* {String}
Gets and sets the port portion of the URL.
```js
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888
// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/
myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234
// Prints https://example.org:1234/
// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234
// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678
// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234
// Out-of-range numbers are ignored
myURL.port = 1e10;
console.log(myURL.port);
// Prints 1234
```
The port value may be set as either a number or as a String containing a number
@ -497,10 +574,14 @@ in the range `0` to `65535` (inclusive). Setting the value to the default port
of the `URL` objects given `protocol` will result in the `port` value becoming
the empty string (`''`).
Invalid URL port values assigned to the `port` property are ignored.
If an invalid string is assigned to the `port` property, but it begins with a
number, the leading number is assigned to `port`. Otherwise, or if the number
lies outside the range denoted above, it is ignored.
#### url.protocol
* {String}
Gets and sets the protocol portion of the URL.
```js
@ -517,6 +598,8 @@ Invalid URL protocol values assigned to the `protocol` property are ignored.
#### url.search
* {String}
Gets and sets the serialized query portion of the URL.
```js
@ -530,17 +613,23 @@ console.log(myURL.href);
```
Any invalid URL characters appearing in the value assigned the `search`
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property will be [percent-encoded][]. Note that the selection of which
characters to percent-encode may vary somewhat from what the [`url.parse()`][]
and [`url.format()`][] methods would produce.
#### url.searchParams
Gets a [`URLSearchParams`](#url_class_urlsearchparams) object representing the
query parameters of the URL.
* {URLSearchParams}
Gets the [`URLSearchParams`][] object representing the query parameters of the
URL. This property is read-only; to replace the entirety of query parameters of
the URL, use the [`url.search`][] setter. See [`URLSearchParams`][]
documentation for details.
#### url.username
* {String}
Gets and sets the username portion of the URL.
```js
@ -554,21 +643,32 @@ console.log(myURL.href);
```
Any invalid URL characters appearing in the value assigned the `username`
property will be [percent-encoded](#whatwg-percent-encoding). Note that the
selection of which characters to percent-encode may vary somewhat from what the
[`url.parse()`][] and [`url.format()`][] methods would produce.
property will be [percent-encoded][]. Note that the selection of which
characters to percent-encode may vary somewhat from what the [`url.parse()`][]
and [`url.format()`][] methods would produce.
#### url.toString()
* Returns: {String}
The `toString()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of `url.href`.
value returned is equivalent to that of [`url.href`][].
Because of the need for standard compliance, this method does not allow users
to customize the serialization process of the URL. For more flexibility,
[`require('url').format()`][] method might be of interest.
### Class: URLSearchParams
The `URLSearchParams` object provides read and write access to the query of a
The `URLSearchParams` API provides read and write access to the query of a
`URL`. The `URLSearchParams` class can also be used standalone with one of the
four following constructors.
The WHATWG `URLSearchParams` interface and the [`querystring`][] module have
similar purpose, but the purpose of the [`querystring`][] module is more
general, as it allows the customization of delimiter characters (`&` and `=`).
On the other hand, this API is designed purely for URL query strings.
```js
const { URL, URLSearchParams } = require('url');
@ -725,36 +825,41 @@ Returns an ES6 Iterator over each of the name-value pairs in the query.
Each item of the iterator is a JavaScript Array. The first item of the Array
is the `name`, the second item of the Array is the `value`.
Alias for `urlSearchParams\[\@\@iterator\]()`.
Alias for [`urlSearchParams[@@iterator]()`][`urlSearchParams@@iterator()`].
#### urlSearchParams.forEach(fn)
#### urlSearchParams.forEach(fn[, thisArg])
* `fn` {Function} Function invoked for each name-value pair in the query.
* `thisArg` {Object} Object to be used as `this` value for when `fn` is called
Iterates over each name-value pair in the query and invokes the given function.
```js
const URL = require('url').URL;
const myURL = new URL('https://example.org/?a=b&c=d');
myURL.searchParams.forEach((value, name) => {
console.log(name, value);
myURL.searchParams.forEach((value, name, searchParams) => {
console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
// a b true
// c d true
```
#### urlSearchParams.get(name)
* `name` {String}
* Returns: {String} or `null` if there is no name-value pair with the given
`name`.
* Returns: {String | Null}
Returns the value of the first name-value pair whose name is `name`.
Returns the value of the first name-value pair whose name is `name`. If there
are no such pairs, `null` is returned.
#### urlSearchParams.getAll(name)
* `name` {String}
* Returns: {Array}
Returns the values of all name-value pairs whose name is `name`.
Returns the values of all name-value pairs whose name is `name`. If there are
no such pairs, an empty array is returned.
#### urlSearchParams.has(name)
@ -769,13 +874,42 @@ Returns `true` if there is at least one name-value pair whose name is `name`.
Returns an ES6 Iterator over the names of each name-value pair.
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&foo=baz');
for (const name of params.keys()) {
console.log(name);
}
// Prints:
// foo
// foo
```
#### urlSearchParams.set(name, value)
* `name` {String}
* `value` {String}
Remove any existing name-value pairs whose name is `name` and append a new
name-value pair.
Sets the value in the `URLSearchParams` object associated with `name` to
`value`. If there are any pre-existing name-value pairs whose names are `name`,
set the first such pair's value to `value` and remove all others. If not,
append the name-value pair to the query string.
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&foo=baz&abc=def
params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&abc=def&xyz=opq
```
#### urlSearchParams.sort()
@ -796,7 +930,8 @@ console.log(params.toString());
* Returns: {String}
Returns the search parameters serialized as a URL-encoded string.
Returns the search parameters serialized as a string, with characters
percent-encoded where necessary.
#### urlSearchParams.values()
@ -804,7 +939,7 @@ Returns the search parameters serialized as a URL-encoded string.
Returns an ES6 Iterator over the values of each name-value pair.
#### urlSearchParams\[\@\@iterator\]()
#### urlSearchParams\[@@iterator\]()
* Returns: {Iterator}
@ -812,7 +947,18 @@ Returns an ES6 Iterator over each of the name-value pairs in the query string.
Each item of the iterator is a JavaScript Array. The first item of the Array
is the `name`, the second item of the Array is the `value`.
Alias for `urlSearchParams.entries()`.
Alias for [`urlSearchParams.entries()`][].
```js
const { URLSearchParams } = require('url');
const params = new URLSearchParams('foo=bar&xyz=baz');
for (const [name, value] of params) {
console.log(name, value);
}
// Prints:
// foo bar
// xyz baz
```
### require('url').domainToAscii(domain)
@ -883,8 +1029,17 @@ console.log(myURL.origin);
[examples of parsed URLs]: https://url.spec.whatwg.org/#example-url-parsing
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
[`url.format()`]: #url_url_format_urlobject
[`require('url').format()`]: #url_url_format_url_options
[`url.toString()`]: #url_url_tostring
[Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
[`array.toString()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/toString
[WHATWG URL]: #url_the_whatwg_url_api
[`new URL()`]: #url_constructor_new_url_input_base
[`url.href`]: #url_url_href
[`url.search`]: #url_url_search
[percent-encoded]: #whatwg-percent-encoding
[`URLSearchParams`]: #url_class_urlsearchparams
[`urlSearchParams.entries()`]: #url_urlsearchparams_entries
[`urlSearchParams@@iterator()`]: #url_urlsearchparams_iterator
[stable sorting algorithm]: https://en.wikipedia.org/wiki/Sorting_algorithm#Stability

Write Preview
Loading…
Cancel
Save