doc/api/url.markdown

   1 ## URL
   2
   3 This module has utilities for URL resolution and parsing.
   4 Call `require('url')` to use it.
   5
   6 Parsed URL objects have some or all of the following fields, depending on
   7 whether or not they exist in the URL string. Any parts that are not in the URL
   8 string will not be in the parsed object. Examples are shown for the URL
   9
  10 `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
  11
  12 * `href`: The full URL that was originally parsed.
  13
  14   Example: `'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'`
  15 * `protocol`: The request protocol.
  16
  17   Example: `'http:'`
  18 * `host`: The full host portion of the URL, including port and authentication information.
  19
  20   Example: `'user:pass@host.com:8080'`
  21 * `auth`: The authentication information portion of a URL.
  22
  23   Example: `'user:pass'`
  24 * `hostname`: Just the hostname portion of the host.
  25
  26   Example: `'host.com'`
  27 * `port`: The port number portion of the host.
  28
  29   Example: `'8080'`
  30 * `pathname`: The path section of the URL, that comes after the host and before the query, including the initial slash if present.
  31
  32   Example: `'/p/a/t/h'`
  33 * `search`: The 'query string' portion of the URL, including the leading question mark.
  34
  35   Example: `'?query=string'`
  36 * `query`: Either the 'params' portion of the query string, or a querystring-parsed object.
  37
  38   Example: `'query=string'` or `{'query':'string'}`
  39 * `hash`: The 'fragment' portion of the URL including the pound-sign.
  40
  41   Example: `'#hash'`
  42
  43 The following methods are provided by the URL module:
  44
  45 ### url.parse(urlStr, parseQueryString=false)
  46
  47 Take a URL string, and return an object.  Pass `true` as the second argument to also parse
  48 the query string using the `querystring` module.
  49
  50 ### url.format(urlObj)
  51
  52 Take a parsed URL object, and return a formatted URL string.
  53
  54 ### url.resolve(from, to)
  55
  56 Take a base URL, and a href URL, and resolve them as a browser would for an anchor tag.