yume/juniper
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
juniper/url/index.html

320 lines
20 KiB
HTML
Raw Normal View History

Update documentation for Juniper
2016-09-11 13:41:24 -05:00
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="rustdoc">
<meta name="description" content="API documentation for the Rust `url` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, url">
<title>url - Rust</title>
<link rel="stylesheet" type="text/css" href="../rustdoc.css">
<link rel="stylesheet" type="text/css" href="../main.css">
</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
This old browser is unsupported and will most likely display funky
things.
</div>
<![endif]-->
<nav class="sidebar">
<p class='location'></p><script>window.sidebarCurrent = {name: 'url', ty: 'mod', relpath: '../'};</script>
</nav>
<nav class="sub">
<form class="search-form js-only">
<div class="search-container">
<input class="search-input" name="search"
autocomplete="off"
placeholder="Click or press ‘S’ to search, ‘?’ for more options…"
type="search">
</div>
</form>
</nav>
<section id='main' class="content mod">
<h1 class='fqn'><span class='in-band'>Crate <a class='mod' href=''>url</a></span><span class='out-of-band'><span id='render-detail'>
<a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">
[<span class='inner'>&#x2212;</span>]
</a>
</span><a id='src-0' class='srclink' href='../src/url/lib.rs.html#9-1421' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>rust-url is an implementation of the <a href="http://url.spec.whatwg.org/">URL Standard</a>
for the <a href="http://rust-lang.org/">Rust</a> programming language.</p>
<p>It builds with <a href="http://crates.io/">Cargo</a>.
To use it in your project, add this to your <code>Cargo.toml</code> file:</p>
<pre><code class="language-Cargo">[dependencies.url]
git = &quot;https://github.com/servo/rust-url&quot;
</code></pre>
<p>Supporting encodings other than UTF-8 in query strings is an optional feature
that requires <a href="https://github.com/lifthrasiir/rust-encoding">rust-encoding</a>
and is off by default.
You can enable it with
<a href="http://doc.crates.io/manifest.html#the-%5Bfeatures%5D-section">Cargo’s <em>features</em> mechanism</a>:</p>
<pre><code class="language-Cargo">[dependencies.url]
git = &quot;https://github.com/servo/rust-url&quot;
features = [&quot;query_encoding&quot;]
</code></pre>
<p>… or by passing <code>--cfg &#39;feature=&quot;query_encoding&quot;&#39;</code> to rustc.</p>
<h1 id='url-parsing-and-data-structures' class='section-header'><a href='#url-parsing-and-data-structures'>URL parsing and data structures</a></h1>
<p>First, URL parsing may fail for various reasons and therefore returns a <code>Result</code>.</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>url</span>::{<span class='ident'>Url</span>, <span class='ident'>ParseError</span>};
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>Url</span>::<span class='ident'>parse</span>(<span class='string'>&quot;http://[:::1]&quot;</span>) <span class='op'>==</span> <span class='prelude-val'>Err</span>(<span class='ident'>ParseError</span>::<span class='ident'>InvalidIpv6Address</span>))</pre>
<p>Let’s parse a valid URL and look at its components.</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>url</span>::{<span class='ident'>Url</span>, <span class='ident'>Host</span>};
<span class='kw'>let</span> <span class='ident'>issue_list_url</span> <span class='op'>=</span> <span class='ident'>Url</span>::<span class='ident'>parse</span>(
<span class='string'>&quot;https://github.com/rust-lang/rust/issues?labels=E-easy&amp;state=open&quot;</span>
).<span class='ident'>unwrap</span>();
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>scheme</span>() <span class='op'>==</span> <span class='string'>&quot;https&quot;</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>username</span>() <span class='op'>==</span> <span class='string'>&quot;&quot;</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>password</span>() <span class='op'>==</span> <span class='prelude-val'>None</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>host_str</span>() <span class='op'>==</span> <span class='prelude-val'>Some</span>(<span class='string'>&quot;github.com&quot;</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>host</span>() <span class='op'>==</span> <span class='prelude-val'>Some</span>(<span class='ident'>Host</span>::<span class='ident'>Domain</span>(<span class='string'>&quot;github.com&quot;</span>)));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>port</span>() <span class='op'>==</span> <span class='prelude-val'>None</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>path</span>() <span class='op'>==</span> <span class='string'>&quot;/rust-lang/rust/issues&quot;</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>path_segments</span>().<span class='ident'>map</span>(<span class='op'>|</span><span class='ident'>c</span><span class='op'>|</span> <span class='ident'>c</span>.<span class='ident'>collect</span>::<span class='op'>&lt;</span><span class='ident'>Vec</span><span class='op'>&lt;</span>_<span class='op'>&gt;&gt;</span>()) <span class='op'>==</span>
<span class='prelude-val'>Some</span>(<span class='macro'>vec</span><span class='macro'>!</span>[<span class='string'>&quot;rust-lang&quot;</span>, <span class='string'>&quot;rust&quot;</span>, <span class='string'>&quot;issues&quot;</span>]));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>query</span>() <span class='op'>==</span> <span class='prelude-val'>Some</span>(<span class='string'>&quot;labels=E-easy&amp;state=open&quot;</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>issue_list_url</span>.<span class='ident'>fragment</span>() <span class='op'>==</span> <span class='prelude-val'>None</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='op'>!</span><span class='ident'>issue_list_url</span>.<span class='ident'>cannot_be_a_base</span>());</pre>
<p>Some URLs are said to be <em>cannot-be-a-base</em>:
they don’t have a username, password, host, or port,
and their &quot;path&quot; is an arbitrary string rather than slash-separated segments:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>url</span>::<span class='ident'>Url</span>;
<span class='kw'>let</span> <span class='ident'>data_url</span> <span class='op'>=</span> <span class='ident'>Url</span>::<span class='ident'>parse</span>(<span class='string'>&quot;data:text/plain,Hello?World#&quot;</span>).<span class='ident'>unwrap</span>();
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>cannot_be_a_base</span>());
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>scheme</span>() <span class='op'>==</span> <span class='string'>&quot;data&quot;</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>path</span>() <span class='op'>==</span> <span class='string'>&quot;text/plain,Hello&quot;</span>);
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>path_segments</span>().<span class='ident'>is_none</span>());
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>query</span>() <span class='op'>==</span> <span class='prelude-val'>Some</span>(<span class='string'>&quot;World&quot;</span>));
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>data_url</span>.<span class='ident'>fragment</span>() <span class='op'>==</span> <span class='prelude-val'>Some</span>(<span class='string'>&quot;&quot;</span>));</pre>
<h1 id='base-url' class='section-header'><a href='#base-url'>Base URL</a></h1>
<p>Many contexts allow URL <em>references</em> that can be relative to a <em>base URL</em>:</p>
<pre><code class="language-html">&lt;link rel=&quot;stylesheet&quot; href=&quot;../main.css&quot;&gt;
</code></pre>
<p>Since parsed URL are absolute, giving a base is required for parsing relative URLs:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>url</span>::{<span class='ident'>Url</span>, <span class='ident'>ParseError</span>};
<span class='macro'>assert</span><span class='macro'>!</span>(<span class='ident'>Url</span>::<span class='ident'>parse</span>(<span class='string'>&quot;../main.css&quot;</span>) <span class='op'>==</span> <span class='prelude-val'>Err</span>(<span class='ident'>ParseError</span>::<span class='ident'>RelativeUrlWithoutBase</span>))</pre>
<p>Use the <code>join</code> method on an <code>Url</code> to use it as a base URL:</p>
<pre class='rust rust-example-rendered'>
<span class='kw'>use</span> <span class='ident'>url</span>::<span class='ident'>Url</span>;
<span class='kw'>let</span> <span class='ident'>this_document</span> <span class='op'>=</span> <span class='ident'>Url</span>::<span class='ident'>parse</span>(<span class='string'>&quot;http://servo.github.io/rust-url/url/index.html&quot;</span>).<span class='ident'>unwrap</span>();
<span class='kw'>let</span> <span class='ident'>css_url</span> <span class='op'>=</span> <span class='ident'>this_document</span>.<span class='ident'>join</span>(<span class='string'>&quot;../main.css&quot;</span>).<span class='ident'>unwrap</span>();
<span class='macro'>assert_eq</span><span class='macro'>!</span>(<span class='ident'>css_url</span>.<span class='ident'>as_str</span>(), <span class='string'>&quot;http://servo.github.io/rust-url/main.css&quot;</span>)</pre>
</div><h2 id='reexports' class='section-header'><a href="#reexports">Reexports</a></h2>
<table><tr><td><code>pub extern crate <a class='mod' href='../idna/index.html' title='idna'>idna</a>;</code></td></tr></table><h2 id='modules' class='section-header'><a href="#modules">Modules</a></h2>
<table>
<tr class=' module-item'>
<td><a class='mod' href='form_urlencoded/index.html'
title='url::form_urlencoded'>form_urlencoded</a></td>
<td class='docblock short'>
<p>Parser and serializer for the <a href="http://url.spec.whatwg.org/#application/x-www-form-urlencoded"><code>application/x-www-form-urlencoded</code> syntax</a>,
as used by HTML forms.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='mod' href='percent_encoding/index.html'
title='url::percent_encoding'>percent_encoding</a></td>
<td class='docblock short'>
</td>
</tr>
<tr class=' module-item'>
<td><a class='mod' href='quirks/index.html'
title='url::quirks'>quirks</a></td>
<td class='docblock short'>
<p>Getters and setters for URL components implemented per <a href="https://url.spec.whatwg.org/#api">https://url.spec.whatwg.org/#api</a></p>
</td>
</tr></table><h2 id='macros' class='section-header'><a href="#macros">Macros</a></h2>
<table>
<tr class=' module-item'>
<td><a class='macro' href='macro.define_encode_set!.html'
title='url::define_encode_set!'>define_encode_set!</a></td>
<td class='docblock short'>
<p>Define a new struct
that implements the <a href="percent_encoding/trait.EncodeSet.html"><code>EncodeSet</code></a> trait,
for use in <a href="percent_encoding/fn.percent_encode.html"><code>percent_decode()</code></a>
and related functions.</p>
</td>
</tr></table><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class='struct' href='struct.HostAndPort.html'
title='url::HostAndPort'>HostAndPort</a></td>
<td class='docblock short'>
<p>This mostly exists because coherence rules don’t allow us to implement
<code>ToSocketAddrs for (Host&lt;S&gt;, u16)</code>.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.OpaqueOrigin.html'
title='url::OpaqueOrigin'>OpaqueOrigin</a></td>
<td class='docblock short'>
<p>Opaque identifier for URLs that have file or other schemes</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.ParseOptions.html'
title='url::ParseOptions'>ParseOptions</a></td>
<td class='docblock short'>
<p>Full configuration for the URL parser.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.PathSegmentsMut.html'
title='url::PathSegmentsMut'>PathSegmentsMut</a></td>
<td class='docblock short'>
<p>Exposes methods to manipulate the path of an URL that is not cannot-be-base.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.SocketAddrs.html'
title='url::SocketAddrs'>SocketAddrs</a></td>
<td class='docblock short'>
<p>Socket addresses for an URL.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.Url.html'
title='url::Url'>Url</a></td>
<td class='docblock short'>
<p>A parsed URL record.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='struct' href='struct.UrlQuery.html'
title='url::UrlQuery'>UrlQuery</a></td>
<td class='docblock short'>
<p>Implementation detail of <code>Url::query_pairs_mut</code>. Typically not used directly.</p>
</td>
</tr></table><h2 id='enums' class='section-header'><a href="#enums">Enums</a></h2>
<table>
<tr class=' module-item'>
<td><a class='enum' href='enum.Host.html'
title='url::Host'>Host</a></td>
<td class='docblock short'>
<p>The host name of an URL.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='enum' href='enum.Origin.html'
title='url::Origin'>Origin</a></td>
<td class='docblock short'>
<p>The origin of an URL</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='enum' href='enum.ParseError.html'
title='url::ParseError'>ParseError</a></td>
<td class='docblock short'>
<p>Errors that can occur during parsing.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class='enum' href='enum.Position.html'
title='url::Position'>Position</a></td>
<td class='docblock short'>
<p>Indicates a position within a URL based on its components.</p>
</td>
</tr></table></section>
<section id='search' class="content hidden"></section>
<section class="footer"></section>
<aside id="help" class="hidden">
<div>
<h1 class="hidden">Help</h1>
<div class="shortcuts">
<h2>Keyboard Shortcuts</h2>
<dl>
<dt>?</dt>
<dd>Show this help dialog</dd>
<dt>S</dt>
<dd>Focus the search field</dd>
<dt>&larrb;</dt>
<dd>Move up in search results</dd>
<dt>&rarrb;</dt>
<dd>Move down in search results</dd>
<dt>&#9166;</dt>
<dd>Go to active search result</dd>
<dt>+</dt>
<dd>Collapse/expand all sections</dd>
</dl>
</div>
<div class="infos">
<h2>Search Tricks</h2>
<p>
Prefix searches with a type followed by a colon (e.g.
<code>fn:</code>) to restrict the search to a given type.
</p>
<p>
Accepted types are: <code>fn</code>, <code>mod</code>,
<code>struct</code>, <code>enum</code>,
<code>trait</code>, <code>type</code>, <code>macro</code>,
and <code>const</code>.
</p>
<p>
Search functions by type signature (e.g.
<code>vec -> usize</code> or <code>* -> vec</code>)
</p>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "url";
window.playgroundUrl = "";
</script>
<script src="../jquery.js"></script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>
Reference in a new issue Copy permalink