doc/api/url.markdown

   1 # URL
   2
   3     Stability: 2 - Stable
   4
   5 This module has utilities for URL resolution and parsing.
   6 Call `require('url')` to use it.
   7
   8 Parsed URL objects have some or all of the following fields, depending on
   9 whether or not they exist in the URL string. Any parts that are not in the URL
  10 string will not be in the parsed object. Examples are shown for the URL
  11
  12 `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
  13
  14 * `href`: The full URL that was originally parsed. Both the protocol and host are lowercased.
  15
  16     Example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
  17
  18 * `protocol`: The request protocol, lowercased.
  19
  20     Example: `'http:'`
  21
  22 * `slashes`: The protocol requires slashes after the colon.
  23
  24     Example: true or false
  25
  26 * `host`: The full lowercased host portion of the URL, including port
  27   information.
  28
  29     Example: `'host.com:8080'`
  30
  31 * `auth`: The authentication information portion of a URL.
  32
  33     Example: `'user:pass'`
  34
  35 * `hostname`: Just the lowercased hostname portion of the host.
  36
  37     Example: `'host.com'`
  38
  39 * `port`: The port number portion of the host.
  40
  41     Example: `'8080'`
  42
  43 * `pathname`: The path section of the URL, that comes after the host and
  44   before the query, including the initial slash if present.
  45
  46     Example: `'/p/a/t/h'`
  47
  48 * `search`: The 'query string' portion of the URL, including the leading
  49   question mark.
  50
  51     Example: `'?query=string'`
  52
  53 * `path`: Concatenation of `pathname` and `search`.
  54
  55     Example: `'/p/a/t/h?query=string'`
  56
  57 * `query`: Either the 'params' portion of the query string, or a
  58   querystring-parsed object.
  59
  60     Example: `'query=string'` or `{'query':'string'}`
  61
  62 * `hash`: The 'fragment' portion of the URL including the pound-sign.
  63
  64     Example: `'#hash'`
  65
  66 The following methods are provided by the URL module:
  67
  68 ## url.parse(urlStr[, parseQueryString][, slashesDenoteHost])
  69
  70 Take a URL string, and return an object.
  71
  72 Pass `true` as the second argument to also parse the query string using the
  73 `querystring` module. If `true` then the `query` property will always be
  74 assigned an object, and the `search` property will always be a (possibly
  75 empty) string.  Defaults to `false`.
  76
  77 Pass `true` as the third argument to treat `//foo/bar` as
  78 `{ host: 'foo', pathname: '/bar' }` rather than
  79 `{ pathname: '//foo/bar' }`. Defaults to `false`.
  80
  81 ## url.format(urlObj)
  82
  83 Take a parsed URL object, and return a formatted URL string.
  84
  85 Here's how the formatting process works:
  86
  87 * `href` will be ignored.
  88 * `protocol` is treated the same with or without the trailing `:` (colon).
  89   * The protocols `http`, `https`, `ftp`, `gopher`, `file` will be
  90     postfixed with `://` (colon-slash-slash).
  91   * All other protocols `mailto`, `xmpp`, `aim`, `sftp`, `foo`, etc will
  92     be postfixed with `:` (colon).
  93 * `slashes` set to `true` if the protocol requires `://` (colon-slash-slash)
  94   * Only needs to be set for protocols not previously listed as requiring
  95     slashes, such as `mongodb://localhost:8000/`.
  96 * `auth` will be used if present.
  97 * `hostname` will only be used if `host` is absent.
  98 * `port` will only be used if `host` is absent.
  99 * `host` will be used in place of `hostname` and `port`.
 100 * `pathname` is treated the same with or without the leading `/` (slash).
 101 * `query` (object; see `querystring`) will only be used if `search` is absent.
 102 * `search` will be used in place of `query`.
 103   * It is treated the same with or without the leading `?` (question mark).
 104 * `hash` is treated the same with or without the leading `#` (pound sign, anchor).
 105
 106 ## url.resolve(from, to)
 107
 108 Take a base URL, and a href URL, and resolve them as a browser would for
 109 an anchor tag.  Examples:
 110
 111     url.resolve('/one/two/three', 'four')         // '/one/two/four'
 112     url.resolve('http://example.com/', '/one')    // 'http://example.com/one'
 113     url.resolve('http://example.com/one', '/two') // 'http://example.com/two'