diff options
Diffstat (limited to 'doc/api/url.md')
-rw-r--r-- | doc/api/url.md | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/doc/api/url.md b/doc/api/url.md new file mode 100644 index 00000000000..ab29c500d80 --- /dev/null +++ b/doc/api/url.md @@ -0,0 +1,131 @@ +# 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' +``` |