Skip to content

Commit

Permalink
doc: add documentation for url.format(URL[, options]);
Browse files Browse the repository at this point in the history
Backport-of: #10857
  • Loading branch information
jasnell authored and italoacasas committed Feb 22, 2017
1 parent 7aaa960 commit 5a2db15
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 1 deletion.
42 changes: 42 additions & 0 deletions doc/api/url.md
Original file line number Diff line number Diff line change
Expand Up @@ -198,6 +198,47 @@ The formatting process operates as follows:
string, an [`Error`][] is thrown.
* `result` is returned.

## url.format(URL[, options])

> Stability: 1 - Experimental
* `URL` {URL} A [WHATWG URL][] object
* `options` {Object}
* `auth` {Boolean} `true` if the serialized URL string should include the
username and password, `false` otherwise. Defaults to `true`.
* `fragment` {Boolean} `true` if the serialized URL string should include the
fragment, `false` otherwise. Defaults to `true`.
* `search` {Boolean} `true` if the serialized URL string should include the
search query, `false` otherwise. Defaults to `true`.
* `unicode` (Boolean) `true` if Unicode characters appearing in the host
component of the URL string should be encoded directly as opposed to being
Punycode encoded. Defaults to `false`.

Returns a customizable serialization of a URL String representation of a
[WHATWG URL][] object.

The URL object has both a `toString()` method and `href` property that return
string serializations of the URL. These are not, however, customizable in
any way. The `url.format(URL[, options])` method allows for basic customization
of the output.

For example:

```js
const myURL = new URL('https://a:b@你好你好?abc#foo');

console.log(myURL.href);
// Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(myURL.toString());
// Prints https://a:b@xn--6qqa088eba/?abc#foo

console.log(url.format(myURL, {fragment: false, unicode: true, auth: false}));
// Prints 'https://你好你好?abc'
```

*Note*: This variation of the `url.format()` method is currently considered to
be experimental.

## url.parse(urlString[, parseQueryString[, slashesDenoteHost]])
<!-- YAML
Expand Down Expand Up @@ -712,3 +753,4 @@ console.log(myURL.origin);
[`url.parse()`]: #url_url_parse_urlstring_parsequerystring_slashesdenotehost
[`url.format()`]: #url_url_format_urlobject
[Punycode]: https://tools.ietf.org/html/rfc5891#section-4.4
[WHATWG URL]: #url_the_whatwg_url_api
3 changes: 2 additions & 1 deletion tools/doc/type-parser.js
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ const typeMap = {
'http.Server': 'http.html#http_class_http_server',
'http.ServerResponse': 'http.html#http_class_http_serverresponse',
'Iterator': jsDocPrefix +
'Reference/Iteration_protocols#The_iterator_protocol'
'Reference/Iteration_protocols#The_iterator_protocol',
'URL': 'url.html#url_the_whatwg_url_api'
};

module.exports = {
Expand Down

1 comment on commit 5a2db15

@MylesBorins
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This did not land with appropriate meta data, is breaking tooling

Please sign in to comment.