Node.js v4.3.1-rc.3 Documentation
Table of Contents
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 ofpathname
andsearch
. 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 ashost
/hostname
are present. - All other protocols
mailto
,xmpp
,aim
,sftp
,foo
, etc will be postfixed with:
(colon).
- The protocols
slashes
set totrue
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 ifhost
/hostname
are absent.
- Only needs to be set for protocols not previously listed as requiring
slashes, such as
auth
will be used if present.hostname
will only be used ifhost
is absent.port
will only be used ifhost
is absent.host
will be used in place ofhostname
andport
.pathname
is treated the same with or without the leading/
(slash).query
(object; seequerystring
) will only be used ifsearch
is absent.search
will be used in place ofquery
.- It is treated the same with or without the leading
?
(question mark).
- It is treated the same with or without the leading
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:
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'