fluent_uri/lib.rs
1#![warn(
2 future_incompatible,
3 missing_debug_implementations,
4 missing_docs,
5 nonstandard_style,
6 rust_2018_idioms,
7 clippy::checked_conversions,
8 clippy::if_not_else,
9 clippy::ignored_unit_patterns,
10 clippy::map_unwrap_or,
11 clippy::missing_errors_doc,
12 clippy::must_use_candidate,
13 // clippy::redundant_closure_for_method_calls,
14 clippy::semicolon_if_nothing_returned,
15 clippy::single_match_else,
16)]
17#![forbid(unsafe_code)]
18#![cfg_attr(docsrs, feature(doc_auto_cfg))]
19#![no_std]
20
21//! A generic URI/IRI handling library compliant with [RFC 3986] and [RFC 3987].
22//!
23//! [RFC 3986]: https://datatracker.ietf.org/doc/html/rfc3986
24//! [RFC 3987]: https://datatracker.ietf.org/doc/html/rfc3987
25//!
26//! **Examples:** [Parsing](Uri#examples). [Building](Builder#examples).
27//! [Reference resolution](UriRef::resolve_against). [Normalization](Uri::normalize).
28//! [Percent-decoding](crate::encoding::EStr#examples).
29//! [Percent-encoding](crate::encoding::EString#examples).
30//!
31//! # Terminology
32//!
33//! A *[URI reference]* is either a *[URI]* or a *[relative reference]*. If it starts with a *[scheme]*
34//! (like `http`, `ftp`, `mailto`, etc.) followed by a colon (`:`), it is a URI. For example,
35//! `http://example.com/` and `mailto:user@example.com` are URIs. Otherwise, it is
36//! a relative reference. For example, `//example.org/`, `/index.html`, `../`, `foo`,
37//! `?bar`, and `#baz` are relative references.
38//!
39//! An *[IRI]* (reference) is an internationalized version of URI (reference)
40//! which may contain non-ASCII characters.
41//!
42//! [URI]: https://datatracker.ietf.org/doc/html/rfc3986#section-3
43//! [URI reference]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.1
44//! [IRI]: https://datatracker.ietf.org/doc/html/rfc3987#section-2
45//! [relative reference]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.2
46//! [scheme]: https://datatracker.ietf.org/doc/html/rfc3986#section-3.1
47//!
48//! # Guidance for crate users
49//!
50//! Advice for designers of new URI schemes can be found in [RFC 7595].
51//! Guidance on the specification of URI substructure in standards
52//! can be found in [RFC 8820]. The crate author recommends [RFC 9413]
53//! for further reading as the long-term interoperability
54//! of URI schemes may be of concern.
55//!
56//! [RFC 7595]: https://datatracker.ietf.org/doc/html/rfc7595
57//! [RFC 8820]: https://datatracker.ietf.org/doc/html/rfc8820
58//! [RFC 9413]: https://datatracker.ietf.org/doc/html/rfc9413
59//!
60//! # Crate features
61//!
62//! - `std` (default): Enables [`std`] support. Required for [`Error`] implementations
63//! and [`Authority::socket_addrs`].
64//!
65//! - `net`: Enables [`std::net`] or [`core::net`] support.
66//! Required for IP address fields in [`Host`], for [`Builder::host`] to take an IP
67//! address as argument, and for [`Authority::socket_addrs`].
68//! Disabling `std` while enabling `net` requires a minimum Rust version of 1.77.
69//!
70//! - `serde`: Enables [`serde`] support. Required for [`Serialize`] and [`Deserialize`]
71//! implementations.
72//!
73//! [`Host`]: component::Host
74//! [`Authority::socket_addrs`]: component::Authority::socket_addrs
75//! [`Error`]: std::error::Error
76//! [`Serialize`]: serde::Serialize
77//! [`Deserialize`]: serde::Deserialize
78
79mod builder;
80pub mod component;
81pub mod encoding;
82pub mod error;
83mod fmt;
84mod internal;
85mod normalizer;
86mod parser;
87mod resolver;
88mod ri;
89
90pub use builder::Builder;
91pub use ri::{Iri, IriRef, Uri, UriRef};
92
93#[cfg(feature = "std")]
94extern crate std;
95
96extern crate alloc;
97
98#[cfg(all(feature = "net", not(feature = "std")))]
99use core::net;
100#[cfg(all(feature = "net", feature = "std"))]
101use std::net;