Enum BaseInfo 

pub enum BaseInfo {
    None,
    NoRoot(Url),
    Full {
        origin: Url,
        path: String,
    },
}

Information used for resolving relative URLs within a particular input source. There should be a 1:1 correspondence between each BaseInfo and its originating InputSource. The main entry point for constructing is BaseInfo::from_source_url.

Once constructed, BaseInfo::parse_url_text can be used to parse and resolve a (possibly relative) URL obtained from within the associated InputSource.

A BaseInfo may be built from input sources which cannot resolve relative links—for instance, stdin. It may also be built from input sources which can resolve locally-relative links, but not root-relative links.

Variants

None

No base information is available. This is for sources with no base information, such as [ResolvedInputSource::Stdin], and for URLs which cannot be a base, such as data: and tel:. BaseInfo::None can resolve no relative links; only fully-qualified links will be parsed successfully.

NoRoot(Url)

A base which cannot resolve root-relative links. This is for file: URLs where the root directory is not known. As such, you can traverse relative to the current URL (by traversing the filesystem), but you cannot jump to the “root”.

Full

A full base made up of origin and path. This can resolve all kinds of relative links.

All non-file: URLs which can be a base fall into this case. For these, origin and path are obtained by dividing the source URL into its origin and path. When joined, ${origin}/${path} should be equivalent to the source’s original URL.

This also represents file: URLs with a known root. The origin field records the file: URL which will be used to resolve root-relative links. The path field is the subpath to a particular input source within the root. This is retained to resolve locally-relative links.

In all cases, the fields should satisfy origin.join(path) == input_source_url where input_source_url is the URL of the originating input source.

Fields

origin: Url

A file: or can be a base URL which acts as the origin. If this is a file: URL, root-relative links will resolve to subpaths of this URL. See the BaseInfo::Full for more information.

path: String

The path field is conditionally joined with origin to resolve links. This is a (possibly-empty) locally- or root-relative link and should not be a full URL or a scheme-relative link.

Implementations

impl BaseInfo

pub const fn none() -> Self

Constructs BaseInfo::None.

pub const fn full(origin: Url, path: String) -> Self

Constructs BaseInfo::Full with the given fields.

pub fn from_source_url(url: &Url) -> Self

Constructs a BaseInfo, with the variant being determined by the given URL.

• A Url::cannot_be_a_base URL will yield BaseInfo::None.
• A file: URL will yield BaseInfo::NoRoot.
• For other URLs, a BaseInfo::Full will be constructed from the URL’s origin and path.

Compared to BaseInfo::from_base_url, this function is more lenient in what it accepts because this function should return a result for all input source URLs.

pub fn from_base_url(url: &Url) -> Result<BaseInfo, ErrorKind>

Constructs a BaseInfo from the given URL, requiring that the given path be acceptable as a base URL. That is, it cannot be a special scheme like data:.

Errors

Errors if the given URL cannot be a base.

pub fn from_path(path: &Path) -> Result<BaseInfo, ErrorKind>

Constructs a BaseInfo from the given filesystem path, requiring that the given path be absolute. Assumes that the given path represents a directory.

This constructs a BaseInfo::Full where root-relative links will go to the given path.

Errors

Errors if the given path is not an absolute path.

pub fn use_fs_root_as_origin(&self) -> Cow<'_, Self>

If this is a BaseInfo::NoRoot, promote it to a BaseInfo::Full by using the filesystem root as the “origin” for root-relative links. Root-relative links will go to the filesystem root.

Generally, this function should be avoided in favour of a more explicit user-provided root directory. The filesystem root is rarely a good place to look for files.

Makes no change to other BaseInfo variants.

Panics

If unable to split a BaseInfo::NoRoot into origin and path.

pub fn use_fs_path_as_origin(&self) -> Cow<'_, Self>

If this is a BaseInfo::NoRoot, promote it to a BaseInfo::Full by using the entire filesystem path as the “origin” for root-relative links. Root-relative links will go to the URL that was previously within NoRoot.

Generally, this function should be avoided in favour of a more explicit user-provided root directory.

Makes no change to other BaseInfo variants.

pub fn url(&self) -> Option<Url>

Returns the URL for the current BaseInfo, joining the origin and path if needed.

pub fn to_file_path(&self) -> Option<PathBuf>

Returns the filesystem path for the current BaseInfo if the underlying URL is a file: URL.

pub fn scheme(&self) -> Option<&str>

Returns the scheme of the underlying URL.

pub const fn is_none(&self) -> bool

Returns whether this value is BaseInfo::None.

pub const fn supports_root_relative(&self) -> bool

Returns whether this BaseInfo variant supports resolving root-relative links.

If true, implies BaseInfo::supports_locally_relative.

pub const fn supports_locally_relative(&self) -> bool

Returns whether this BaseInfo variant supports resolving locally-relative links.

pub const fn or_fallback<'a>(&'a self, fallback: &'a Self) -> &'a Self

Returns the BaseInfo which has more information between self and the given fallback.

BaseInfo::Full is preferred over BaseInfo::NoRoot which is preferred over BaseInfo::None. If both self and fallback are the same variant, then self will be preferred.

pub fn parse_url_text(&self, text: &str) -> Result<Url, ErrorKind>

Parses the given URL text into a fully-qualified URL, including resolving relative links if supported by the current BaseInfo.

To parse and resolve relative links, this uses Url::join with the current BaseInfo’s URL as a base, as applicable.

Errors

Returns an error if the text is an invalid URL, or if the text is a relative link and this BaseInfo variant cannot resolve the relative link.

pub fn resolve_relative_link( &self, rel: &RelativeUri<'_>, ) -> Result<Url, ErrorKind>

Resolves the given relative link into a fully-qualified URL, if supported by the current BaseInfo.

Errors

Returns an error if the text is an invalid URL, or if the current BaseInfo is not capable of resolving the given relative link. Returned errors include ErrorKind::RootRelativeLinkWithoutRoot and ParseError::RelativeUrlWithoutBase (within ErrorKind::ParseUrl).

pub fn parse_url_text_with_root_dir( &self, text: &str, root_dir: Option<&Url>, ) -> Result<Url, ErrorKind>

Parses the given URL text into a fully-qualified URL, including resolving relative links if supported by the current BaseInfo and applying the given root-dir if necessary.

The root-dir is applied if the current BaseInfo is BaseInfo::None or has a file: URL and if the given text is a root-relative link. In these cases, the given root_dir will override the original BaseInfo.

Errors

Propagates errors from BaseInfo::parse_url_text.

Trait Implementations

impl Clone for BaseInfo

fn clone(&self) -> BaseInfo

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BaseInfo

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BaseInfo

fn default() -> BaseInfo

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for BaseInfo

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for BaseInfo

fn eq(&self, other: &BaseInfo) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<&str> for BaseInfo

Attempts to parse a base from the given string which may be a URL or a filesystem path. In both cases, the string must represent a valid base (i.e., not resulting in BaseInfo::None). Otherwise, an error will be returned.

Note that this makes a distinction between filesystem paths as paths and filesystem paths as URLs. When specified as a path, they will become BaseInfo::Full but when specified as a URL, they will become BaseInfo::NoRoot.

Additionally, the empty string is accepted and will be parsed to BaseInfo::None.

type Error = ErrorKind

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, ErrorKind>

Performs the conversion.

impl TryFrom<String> for BaseInfo

type Error = ErrorKind

The type returned in the event of a conversion error.

fn try_from(value: String) -> Result<Self, ErrorKind>

Performs the conversion.

impl Eq for BaseInfo

impl StructuralPartialEq for BaseInfo