Crate rdftk_iri[−][src]

Expand description

iri This crate provides an implementation of the IRI and URI specifications. It provides IRI and IRIRef types that supports the semantics of the IRI, URI, URL, and URN specifications.

Examples

The most common use is the parsing of an IRI value from a string.

use rdftk_iri::IRI;
use std::str::FromStr;

let result = IRI::from_str(
    "https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top",
);

Once parsed it is easy to then extract the components of the IRI, as shown below.

use rdftk_iri::IRI;
use std::str::FromStr;

let result = IRI::from_str(
    "https://john.doe@www.example.com:123/forum/questions/?tag=networking&order=newest#top",
);

let iri = result.unwrap();

println!("scheme:   {}", iri.scheme().as_ref().unwrap());
println!("user:     {}", iri.authority().as_ref().unwrap().user_info().as_ref().unwrap().user_name());
println!("host:     {}", iri.authority().as_ref().unwrap().host());
println!("port:     {}", iri.authority().as_ref().unwrap().port().as_ref().unwrap());
println!("path:     {}", iri.path());
println!("query:    {}", iri.query().as_ref().unwrap());
println!("fragment: {}", iri.fragment().as_ref().unwrap());

The previous code should result in the following:

scheme:   https
user:     john.doe
host:     www.example.com
port:     123
path:     /forum/questions/
query:    tag=networking&order=newest
fragment: top

The builder module allows for more programmatic construction of IRIs.

use rdftk_iri::{IRI, Scheme};
use rdftk_iri::builder::IriBuilder;
use rdftk_iri::error::Result as IriResult;
use std::convert::TryInto;

let mut builder = IriBuilder::default();
let result: IriResult<IRI> = builder
    .scheme(&Scheme::https())
    .user_name("john.doe")
    .host_str("www.example.com")?
    .port(123.into())
    .path_str("/forum/questions/")?
    .query_str("tag=networking&order=newest")?
    .fragment_str("top")?
    .try_into();

Note also the use of Scheme::https(), both the Scheme and Port types include associated functions to construct well-known values.

Features

The following features are present in this crate.

  • builder [default] – include the builder module, which in turn includes the IriBuilder type.
  • genid [default] – includes a constructor to create "genid" well-known IRI values.
  • path_iri [default] – provides an implementation of TryFrom<&PathBuf> and TryFrom<PathBuf> for IRI.
  • uuid_iri [default] – provides an implementation of TryFrom<&Uuid> and TryFrom<Uuid> for IRI.

Specifications

  1. RFC-1630 Universal Resource Identifiers in WWW: A Unifying Syntax for the Expression of Names and Addresses of Objects on the Network as used in the World-Wide Web
  2. RFC-1736 Functional Recommendations for Internet Resource Locators
  3. RFC-1737 Functional Requirements for Uniform Resource Names
  4. RFC-1738 Uniform Resource Locators (URL)
  5. RFC-1808 Relative Uniform Resource Locators
  6. RFC-2141 URN Syntax
  7. RFC-2396 Uniform Resource Identifiers (URI): Generic Syntax
  8. RFC-2616 Hypertext Transfer Protocol – HTTP/1.1; §3.2 Uniform Resource Identifiers
  9. RFC-2717 Registration Procedures for URL Scheme Names
  10. RFC-2732 Format for Literal IPv6 Addresses in URL’s
  11. RFC-3305 Report from the Joint W3C/IETF URI Planning Interest Group: Uniform Resource Identifiers (URIs), URLs, and Uniform Resource Names (URNs): Clarifications and Recommendations
  12. RFC-3987 Internationalized Resource Identifiers (IRIs)
  13. RFC-6963 A Uniform Resource Name (URN) Namespace for Examples
  14. RFC-8141 Uniform Resource Names (URNs)

From RFC-2396, appendix A. Collected BNF for URI:

URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]
absoluteURI   = scheme ":" ( hier_part | opaque_part )
relativeURI   = ( net_path | abs_path | rel_path ) [ "?" query ]

hier_part     = ( net_path | abs_path ) [ "?" query ]
opaque_part   = uric_no_slash *uric

uric_no_slash = unreserved | escaped | ";" | "?" | ":" | "@" |
                "&" | "=" | "+" | "$" | ","

net_path      = "//" authority [ abs_path ]
abs_path      = "/"  path_segments
rel_path      = rel_segment [ abs_path ]

rel_segment   = 1*( unreserved | escaped |
                    ";" | "@" | "&" | "=" | "+" | "$" | "," )

scheme        = alpha *( alpha | digit | "+" | "-" | "." )

authority     = server | reg_name

reg_name      = 1*( unreserved | escaped | "$" | "," |
                    ";" | ":" | "@" | "&" | "=" | "+" )

server        = [ [ userinfo "@" ] hostport ]
userinfo      = *( unreserved | escaped |
                   ";" | ":" | "&" | "=" | "+" | "$" | "," )

hostport      = host [ ":" port ]
host          = hostname | IPv4address
hostname      = *( domainlabel "." ) toplabel [ "." ]
domainlabel   = alphanum | alphanum *( alphanum | "-" ) alphanum
toplabel      = alpha | alpha *( alphanum | "-" ) alphanum
IPv4address   = 1*digit "." 1*digit "." 1*digit "." 1*digit
port          = *digit

path          = [ abs_path | opaque_part ]
path_segments = segment *( "/" segment )
segment       = *pchar *( ";" param )
param         = *pchar
pchar         = unreserved | escaped |
                ":" | "@" | "&" | "=" | "+" | "$" | ","

query         = *uric

fragment      = *uric
uric          = reserved | unreserved | escaped
reserved      = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
                "$" | ","
unreserved    = alphanum | mark
mark          = "-" | "_" | "." | "!" | "~" | "*" | "'" |
                "(" | ")"

escaped       = "%" hex hex
hex           = digit | "A" | "B" | "C" | "D" | "E" | "F" |
                        "a" | "b" | "c" | "d" | "e" | "f"

alphanum      = alpha | digit
alpha         = lowalpha | upalpha

lowalpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" |
           "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" |
           "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z"
upalpha  = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" |
           "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" |
           "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z"
digit    = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" |
           "8" | "9"

Also, Excluded US-ASCII Characters:

control  = <US-ASCII coded characters 00-1F and 7F hexadecimal>
space    = <US-ASCII coded character 20 hexadecimal>
delims   = "<" | ">" | "#" | "%" | <">
unwise   = "{" | "}" | "|" | "\" | "^" | "[" | "]" | "`"

To support IPv6 addresses the following changes were made in RFC-2732:

The following changes to the syntax in RFC 2396 are made:
(1) change the 'host' non-terminal to add an IPv6 option:

   host          = hostname | IPv4address | IPv6reference
   ipv6reference = "[" IPv6address "]"

where IPv6address is defined as in RFC2373 [ARCH].

(2) Replace the definition of 'IPv4address' with that of RFC 2373, as
it correctly defines an IPv4address as consisting of at most three
decimal digits per segment.

(3) Add "[" and "]" to the set of 'reserved' characters:

   reserved    = ";" | "/" | "?" | ":" | "@" | "&" | "=" | "+" |
                 "$" | "," | "[" | "]"

and remove them from the 'unwise' set:

   unwise      = "{" | "}" | "|" | "\" | "^" | "`"

Modules

builder

Provides a builder experience for creating IRI instances. The IriBuilder type provides a simple API to create new IRI instances in a fluent style.

error

Provides the IRI specific Error and Result types.

Structs

Authority

Provides the Authority component of an IRI comprising host, user information, and port sub-components. All but the host sub-components are optional.

Fragment

The fragment component of an IRI contains a fragment identifier providing direction to a secondary resource, such as a section heading in an article identified by the remainder of the URI. When the primary resource is an HTML document, the fragment is often an id attribute of a specific element, and web browsers will scroll this element into view.

Host

This type wraps the specific HostKind and provides a common place for host-related operations.

IRI

The IRI type comprised of Scheme, Authority, Path, Query, and Fragment components. Note that for most APIs the use of IRIRef is preferred over IRI directly.

Path

The path is a component of the “generic URI”, perRFC 3296 §3:

Port

This type represents the port component, it is a 16 bit unsigned integer.

Query

This type holds the query component of the IRI. While it is common in URLs to see queries of the form key=value&key=value... this is not part of the specification which explicitly makes the format of queries opaque:

Scheme

Provides the Scheme component of an IRI as well as a set of known schemes.

UserInfo

The user information sub-component of an IRIs Authority.

Enums

HostKind

This type holds the host details in their parsed form. It is an enumeration of the set of valid host representations allowed by the IRI specification.

Traits

Normalize

This trait is used on the IRI and it’s components to normalize their value according to the relevant RFC rules.

PercentEncoding

Encode the corresponding type using percent-encoding rules.

ValidateStr

This trait is implemented by most components to provide a way to determine whether a string value is valid. It can be assumed that the action is less expensive than performing the FromStr conversion and checking it’s result.

Type Definitions

IRIRef

A preferred reference-counted type to wrap an IRI. For RDF where IRIs are extensively reused as model.graph nodes, the requirement to use a reference type is very important to reduce duplication.