1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
|
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>URL | Node.js v4.8.2 Manual & Documentation</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic">
<link rel="stylesheet" href="assets/style.css">
<link rel="stylesheet" href="assets/sh.css">
<link rel="canonical" href="https://nodejs.org/api/url.html">
</head>
<body class="alt apidoc" id="api-section-url">
<div id="content" class="clearfix">
<div id="column2" class="interior">
<div id="intro" class="interior">
<a href="/" title="Go back to the home page">
Node.js
</a>
</div>
<ul>
<li><a class="nav-documentation" href="documentation.html">About these Docs</a></li>
<li><a class="nav-synopsis" href="synopsis.html">Usage & Example</a></li>
</ul>
<div class="line"></div>
<ul>
<li><a class="nav-assert" href="assert.html">Assertion Testing</a></li>
<li><a class="nav-buffer" href="buffer.html">Buffer</a></li>
<li><a class="nav-addons" href="addons.html">C/C++ Addons</a></li>
<li><a class="nav-child_process" href="child_process.html">Child Processes</a></li>
<li><a class="nav-cluster" href="cluster.html">Cluster</a></li>
<li><a class="nav-cli" href="cli.html">Command Line Options</a></li>
<li><a class="nav-console" href="console.html">Console</a></li>
<li><a class="nav-crypto" href="crypto.html">Crypto</a></li>
<li><a class="nav-debugger" href="debugger.html">Debugger</a></li>
<li><a class="nav-dns" href="dns.html">DNS</a></li>
<li><a class="nav-domain" href="domain.html">Domain</a></li>
<li><a class="nav-errors" href="errors.html">Errors</a></li>
<li><a class="nav-events" href="events.html">Events</a></li>
<li><a class="nav-fs" href="fs.html">File System</a></li>
<li><a class="nav-globals" href="globals.html">Globals</a></li>
<li><a class="nav-http" href="http.html">HTTP</a></li>
<li><a class="nav-https" href="https.html">HTTPS</a></li>
<li><a class="nav-modules" href="modules.html">Modules</a></li>
<li><a class="nav-net" href="net.html">Net</a></li>
<li><a class="nav-os" href="os.html">OS</a></li>
<li><a class="nav-path" href="path.html">Path</a></li>
<li><a class="nav-process" href="process.html">Process</a></li>
<li><a class="nav-punycode" href="punycode.html">Punycode</a></li>
<li><a class="nav-querystring" href="querystring.html">Query Strings</a></li>
<li><a class="nav-readline" href="readline.html">Readline</a></li>
<li><a class="nav-repl" href="repl.html">REPL</a></li>
<li><a class="nav-stream" href="stream.html">Stream</a></li>
<li><a class="nav-string_decoder" href="string_decoder.html">String Decoder</a></li>
<li><a class="nav-timers" href="timers.html">Timers</a></li>
<li><a class="nav-tls" href="tls.html">TLS/SSL</a></li>
<li><a class="nav-tty" href="tty.html">TTY</a></li>
<li><a class="nav-dgram" href="dgram.html">UDP/Datagram</a></li>
<li><a class="nav-url active" href="url.html">URL</a></li>
<li><a class="nav-util" href="util.html">Utilities</a></li>
<li><a class="nav-v8" href="v8.html">V8</a></li>
<li><a class="nav-vm" href="vm.html">VM</a></li>
<li><a class="nav-zlib" href="zlib.html">ZLIB</a></li>
</ul>
<div class="line"></div>
<ul>
<li><a class="nav-https-github-com-nodejs-node" href="https://github.com/nodejs/node">GitHub Repo & Issue Tracker</a></li>
<li><a class="nav-http-groups-google-com-group-nodejs" href="http://groups.google.com/group/nodejs">Mailing List</a></li>
</ul>
</div>
<div id="column1" data-id="url" class="interior">
<header>
<h1>Node.js v4.8.2 Documentation</h1>
<div id="gtoc">
<p>
<a href="index.html" name="toc">Index</a> |
<a href="all.html">View on single page</a> |
<a href="url.json">View as JSON</a>
</p>
</div>
<hr>
</header>
<div id="toc">
<h2>Table of Contents</h2>
<ul>
<li><span class="stability_2"><a href="#url_url">URL</a></span><ul>
<li><span class="stability_undefined"><a href="#url_url_parsing">URL Parsing</a></span><ul>
<li><span class="stability_undefined"><a href="#url_escaped_characters">Escaped Characters</a></span></li>
</ul>
</li>
<li><span class="stability_undefined"><a href="#url_url_format_urlobj">url.format(urlObj)</a></span></li>
<li><span class="stability_undefined"><a href="#url_url_parse_urlstr_parsequerystring_slashesdenotehost">url.parse(urlStr[, parseQueryString][, slashesDenoteHost])</a></span></li>
<li><span class="stability_undefined"><a href="#url_url_resolve_from_to">url.resolve(from, to)</a></span></li>
</ul>
</li>
</ul>
</div>
<div id="apicontent">
<h1>URL<span><a class="mark" href="#url_url" id="url_url">#</a></span></h1>
<pre class="api_stability api_stability_2">Stability: 2 - Stable</pre><p>This module has utilities for URL resolution and parsing.
Call <code>require('url')</code> to use it.</p>
<h2>URL Parsing<span><a class="mark" href="#url_url_parsing" id="url_url_parsing">#</a></span></h2>
<p>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</p>
<p><code>'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'</code></p>
<ul>
<li><p><code>href</code>: The full URL that was originally parsed. Both the protocol and host are lowercased.</p>
<p> Example: <code>'http://user:pass@host.com:8080/p/a/t/h?query=string#hash'</code></p>
</li>
<li><p><code>protocol</code>: The request protocol, lowercased.</p>
<p> Example: <code>'http:'</code></p>
</li>
<li><p><code>slashes</code>: The protocol requires slashes after the colon.</p>
<p> Example: true or false</p>
</li>
<li><p><code>host</code>: The full lowercased host portion of the URL, including port
information.</p>
<p> Example: <code>'host.com:8080'</code></p>
</li>
<li><p><code>auth</code>: The authentication information portion of a URL.</p>
<p> Example: <code>'user:pass'</code></p>
</li>
<li><p><code>hostname</code>: Just the lowercased hostname portion of the host.</p>
<p> Example: <code>'host.com'</code></p>
</li>
<li><p><code>port</code>: The port number portion of the host.</p>
<p> Example: <code>'8080'</code></p>
</li>
<li><p><code>pathname</code>: 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.</p>
<p> Example: <code>'/p/a/t/h'</code></p>
</li>
<li><p><code>search</code>: The 'query string' portion of the URL, including the leading
question mark.</p>
<p> Example: <code>'?query=string'</code></p>
</li>
<li><p><code>path</code>: Concatenation of <code>pathname</code> and <code>search</code>. No decoding is performed.</p>
<p> Example: <code>'/p/a/t/h?query=string'</code></p>
</li>
<li><p><code>query</code>: Either the 'params' portion of the query string, or a
querystring-parsed object.</p>
<p> Example: <code>'query=string'</code> or <code>{'query':'string'}</code></p>
</li>
<li><p><code>hash</code>: The 'fragment' portion of the URL including the pound-sign.</p>
<p> Example: <code>'#hash'</code></p>
</li>
</ul>
<h3>Escaped Characters<span><a class="mark" href="#url_escaped_characters" id="url_escaped_characters">#</a></span></h3>
<p>Spaces (<code>' '</code>) and the following characters will be automatically escaped in the
properties of URL objects:</p>
<pre><code>< > " ` \r \n \t { } | \ ^ '
</code></pre><hr>
<p>The following methods are provided by the URL module:</p>
<h2>url.format(urlObj)<span><a class="mark" href="#url_url_format_urlobj" id="url_url_format_urlobj">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.25</span>
</div><p>Take a parsed URL object, and return a formatted URL string.</p>
<p>Here's how the formatting process works:</p>
<ul>
<li><code>href</code> will be ignored.</li>
<li><code>path</code> will be ignored.</li>
<li><code>protocol</code> is treated the same with or without the trailing <code>:</code> (colon).<ul>
<li>The protocols <code>http</code>, <code>https</code>, <code>ftp</code>, <code>gopher</code>, <code>file</code> will be
postfixed with <code>://</code> (colon-slash-slash) as long as <code>host</code>/<code>hostname</code> are present.</li>
<li>All other protocols <code>mailto</code>, <code>xmpp</code>, <code>aim</code>, <code>sftp</code>, <code>foo</code>, etc will
be postfixed with <code>:</code> (colon).</li>
</ul>
</li>
<li><code>slashes</code> set to <code>true</code> if the protocol requires <code>://</code> (colon-slash-slash)<ul>
<li>Only needs to be set for protocols not previously listed as requiring
slashes, such as <code>mongodb://localhost:8000/</code>, or if <code>host</code>/<code>hostname</code> are absent.</li>
</ul>
</li>
<li><code>auth</code> will be used if present.</li>
<li><code>hostname</code> will only be used if <code>host</code> is absent.</li>
<li><code>port</code> will only be used if <code>host</code> is absent.</li>
<li><code>host</code> will be used in place of <code>hostname</code> and <code>port</code>.</li>
<li><code>pathname</code> is treated the same with or without the leading <code>/</code> (slash).</li>
<li><code>query</code> (object; see <code>querystring</code>) will only be used if <code>search</code> is absent.</li>
<li><code>search</code> will be used in place of <code>query</code>.<ul>
<li>It is treated the same with or without the leading <code>?</code> (question mark).</li>
</ul>
</li>
<li><code>hash</code> is treated the same with or without the leading <code>#</code> (pound sign, anchor).</li>
</ul>
<h2>url.parse(urlStr[, parseQueryString][, slashesDenoteHost])<span><a class="mark" href="#url_url_parse_urlstr_parsequerystring_slashesdenotehost" id="url_url_parse_urlstr_parsequerystring_slashesdenotehost">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.25</span>
</div><p>Take a URL string, and return an object.</p>
<p>Pass <code>true</code> as the second argument to also parse the query string using the
<code>querystring</code> module. If <code>true</code> then the <code>query</code> property will always be
assigned an object, and the <code>search</code> property will always be a (possibly
empty) string. If <code>false</code> then the <code>query</code> property will not be parsed or
decoded. Defaults to <code>false</code>.</p>
<p>Pass <code>true</code> as the third argument to treat <code>//foo/bar</code> as
<code>{ host: 'foo', pathname: '/bar' }</code> rather than
<code>{ pathname: '//foo/bar' }</code>. Defaults to <code>false</code>.</p>
<h2>url.resolve(from, to)<span><a class="mark" href="#url_url_resolve_from_to" id="url_url_resolve_from_to">#</a></span></h2>
<div class="api_metadata">
<span>Added in: v0.1.25</span>
</div><p>Take a base URL, and a href URL, and resolve them as a browser would for
an anchor tag. Examples:</p>
<pre><code class="lang-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'
</code></pre>
</div>
</div>
</div>
<script src="assets/sh_main.js"></script>
<script src="assets/sh_javascript.min.js"></script>
<script>highlight(undefined, undefined, 'pre');</script>
<!-- __TRACKING__ -->
</body>
</html>
|
