mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
e436272897
This changes the code blocks from 4-space indentation to ``` fences for better syntax highlighting and future linting support. Minor On-the-fly changes for typos and highlight breaking markdown have been made. JSON-Style objects have been changed so their closing bracket is on the same line as the opening one. Known issues: * Not every JSON / object notation has been improved. Should make another run for this. * Some example functions break hightlighting due to various combinations of brackets. However changing them means leaving the code style. Fixes: https://github.com/nodejs/node/issues/4726 PR-URL: https://github.com/nodejs/node/pull/4733 Reviewed-By: Roman Reiss <me@silverwind.io>
132 lines
4.2 KiB
Markdown
132 lines
4.2 KiB
Markdown
# URL
|
|
|
|
Stability: 2 - Stable
|
|
|
|
This module has utilities for URL resolution and parsing.
|
|
Call `require('url')` to use it.
|
|
|
|
## URL Parsing
|
|
|
|
Parsed URL objects have some or all of the following fields, depending on
|
|
whether or not they exist in the URL string. Any parts that are not in the URL
|
|
string will not be in the parsed object. Examples are shown for the URL
|
|
|
|
`'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
|
|
|
|
* `href`: The full URL that was originally parsed. Both the protocol and host are lowercased.
|
|
|
|
Example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
|
|
|
|
* `protocol`: The request protocol, lowercased.
|
|
|
|
Example: `'http:'`
|
|
|
|
* `slashes`: The protocol requires slashes after the colon.
|
|
|
|
Example: true or false
|
|
|
|
* `host`: The full lowercased host portion of the URL, including port
|
|
information.
|
|
|
|
Example: `'host.com:8080'`
|
|
|
|
* `auth`: The authentication information portion of a URL.
|
|
|
|
Example: `'user:pass'`
|
|
|
|
* `hostname`: Just the lowercased hostname portion of the host.
|
|
|
|
Example: `'host.com'`
|
|
|
|
* `port`: The port number portion of the host.
|
|
|
|
Example: `'8080'`
|
|
|
|
* `pathname`: The path section of the URL, that comes after the host and
|
|
before the query, including the initial slash if present. No decoding is
|
|
performed.
|
|
|
|
Example: `'/p/a/t/h'`
|
|
|
|
* `search`: The 'query string' portion of the URL, including the leading
|
|
question mark.
|
|
|
|
Example: `'?query=string'`
|
|
|
|
* `path`: Concatenation of `pathname` and `search`. No decoding is performed.
|
|
|
|
Example: `'/p/a/t/h?query=string'`
|
|
|
|
* `query`: Either the 'params' portion of the query string, or a
|
|
querystring-parsed object.
|
|
|
|
Example: `'query=string'` or `{'query':'string'}`
|
|
|
|
* `hash`: The 'fragment' portion of the URL including the pound-sign.
|
|
|
|
Example: `'#hash'`
|
|
|
|
### Escaped Characters
|
|
|
|
Spaces (`' '`) and the following characters will be automatically escaped in the
|
|
properties of URL objects:
|
|
|
|
```
|
|
< > " ` \r \n \t { } | \ ^ '
|
|
```
|
|
|
|
---
|
|
|
|
The following methods are provided by the URL module:
|
|
|
|
## url.format(urlObj)
|
|
|
|
Take a parsed URL object, and return a formatted URL string.
|
|
|
|
Here's how the formatting process works:
|
|
|
|
* `href` will be ignored.
|
|
* `path` will be ignored.
|
|
* `protocol` is treated the same with or without the trailing `:` (colon).
|
|
* The protocols `http`, `https`, `ftp`, `gopher`, `file` will be
|
|
postfixed with `://` (colon-slash-slash) as long as `host`/`hostname` are present.
|
|
* All other protocols `mailto`, `xmpp`, `aim`, `sftp`, `foo`, etc will
|
|
be postfixed with `:` (colon).
|
|
* `slashes` set to `true` if the protocol requires `://` (colon-slash-slash)
|
|
* Only needs to be set for protocols not previously listed as requiring
|
|
slashes, such as `mongodb://localhost:8000/`, or if `host`/`hostname` are absent.
|
|
* `auth` will be used if present.
|
|
* `hostname` will only be used if `host` is absent.
|
|
* `port` will only be used if `host` is absent.
|
|
* `host` will be used in place of `hostname` and `port`.
|
|
* `pathname` is treated the same with or without the leading `/` (slash).
|
|
* `query` (object; see `querystring`) will only be used if `search` is absent.
|
|
* `search` will be used in place of `query`.
|
|
* It is treated the same with or without the leading `?` (question mark).
|
|
* `hash` is treated the same with or without the leading `#` (pound sign, anchor).
|
|
|
|
## url.parse(urlStr[, parseQueryString][, slashesDenoteHost])
|
|
|
|
Take a URL string, and return an object.
|
|
|
|
Pass `true` as the second argument to also parse the query string using the
|
|
`querystring` module. If `true` then the `query` property will always be
|
|
assigned an object, and the `search` property will always be a (possibly
|
|
empty) string. If `false` then the `query` property will not be parsed or
|
|
decoded. Defaults to `false`.
|
|
|
|
Pass `true` as the third argument to treat `//foo/bar` as
|
|
`{ host: 'foo', pathname: '/bar' }` rather than
|
|
`{ pathname: '//foo/bar' }`. Defaults to `false`.
|
|
|
|
## url.resolve(from, to)
|
|
|
|
Take a base URL, and a href URL, and resolve them as a browser would for
|
|
an anchor tag. Examples:
|
|
|
|
```js
|
|
url.resolve('/one/two/three', 'four') // '/one/two/four'
|
|
url.resolve('http://example.com/', '/one') // 'http://example.com/one'
|
|
url.resolve('http://example.com/one', '/two') // 'http://example.com/two'
|
|
```
|