[−][src]Crate earl

rust-url is an implementation of the URL Standard for the Rust programming language.

URL parsing and data structures

First, URL parsing may fail for various reasons and therefore returns a Result.

use earl::{Url, ParseError};

assert!(Url::parse("http://[:::1]") == Err(ParseError::InvalidIpv6Address))

Let’s parse a valid URL and look at its components.

use earl::{Url, Host, Position};
let issue_list_url = Url::parse(
    "https://github.com/rust-lang/rust/issues?labels=E-easy&state=open"
)?;


assert!(issue_list_url.scheme() == "https");
assert!(issue_list_url.username() == "");
assert!(issue_list_url.password() == None);
assert!(issue_list_url.host_str() == Some("github.com"));
assert!(issue_list_url.host() == Some(Host::Domain("github.com")));
assert!(issue_list_url.port() == None);
assert!(issue_list_url.path() == "/rust-lang/rust/issues");
assert!(issue_list_url.path_segments().map(|c| c.collect::<Vec<_>>()) ==
        Some(vec!["rust-lang", "rust", "issues"]));
assert!(issue_list_url.query() == Some("labels=E-easy&state=open"));
assert!(&issue_list_url[Position::BeforePath..] == "/rust-lang/rust/issues?labels=E-easy&state=open");
assert!(issue_list_url.fragment() == None);
assert!(!issue_list_url.cannot_be_a_base());

Some URLs are said to be cannot-be-a-base: they don’t have a username, password, host, or port, and their "path" is an arbitrary string rather than slash-separated segments:

use earl::Url;

let data_url = Url::parse("data:text/plain,Hello?World#")?;

assert!(data_url.cannot_be_a_base());
assert!(data_url.scheme() == "data");
assert!(data_url.path() == "text/plain,Hello");
assert!(data_url.path_segments().is_none());
assert!(data_url.query() == Some("World"));
assert!(data_url.fragment() == Some(""));

Base URL

Many contexts allow URL references that can be relative to a base URL:

<link rel="stylesheet" href="../main.css">

Since parsed URLs are absolute, giving a base is required for parsing relative URLs:

use earl::{Url, ParseError};

assert!(Url::parse("../main.css") == Err(ParseError::RelativeUrlWithoutBase))

Use the join method on an Url to use it as a base URL:

use earl::Url;

let this_document = Url::parse("http://servo.github.io/rust-url/url/index.html")?;
let css_url = this_document.join("../main.css")?;
assert_eq!(css_url.as_str(), "http://servo.github.io/rust-url/main.css");

Re-exports

pub extern crate percent_encoding;

pub use idna;

Modules

form_urlencoded

Parser and serializer for the application/x-www-form-urlencoded syntax, as used by HTML forms.

Macros

define_encode_set

Define a new struct that implements the EncodeSet trait, for use in percent_decode() and related functions.

Structs

HostAndPort	This mostly exists because coherence rules don’t allow us to implement `ToSocketAddrs for (Host<S>, u16)`.
OpaqueOrigin	Opaque identifier for URLs that have file or other schemes
ParseOptions	Full configuration for the URL parser.
PathSegmentsMut	Exposes methods to manipulate the path of an URL that is not cannot-be-base.
SocketAddrs	Socket addresses for an URL.
Url	A parsed URL record.
UrlQuery	Implementation detail of `Url::query_pairs_mut`. Typically not used directly.

Enums

Host	The host name of an URL.
Origin	The origin of an URL
ParseError	Errors that can occur during parsing.
Position	Indicates a position within a URL based on its components.
SyntaxViolation	Non-fatal syntax violations that can occur during parsing.