Trait URL

Source

pub trait URLwhere
    Self: Debug + Display,{
    // Required methods
    fn context(&self) -> &UrlContext;
    fn relative(&self, path: &str) -> UrlRef;
    fn conform(&mut self) -> Result<(), UrlError>;
    fn conform_async(&self) -> Result<ConformFuture, UrlError>;
    fn open(&self) -> Result<ReadRef, UrlError>;
    fn open_async(&self) -> Result<OpenFuture, UrlError>;

    // Provided methods
    fn key(&self) -> String { ... }
    fn query(&self) -> Option<UrlQuery> { ... }
    fn fragment(&self) -> Option<String> { ... }
    fn format(&self) -> Option<String> { ... }
    fn local(&self) -> Option<PathBuf> { ... }
    fn base(&self) -> Option<UrlRef> { ... }
}

Expand description

URL.

Required Methods§

Source

fn context(&self) -> &UrlContext

The UrlContext used to create this URL.

Source

fn relative(&self, path: &str) -> UrlRef

Parses the argument as a path relative to the URL. That means that this URL is treated as a “base directory” (see base). The argument supports “..” and “.”, with the returned URL path always being absolute.

The relative URL will normally not have the query and fragment of this URL.

Source

fn conform(&mut self) -> Result<(), UrlError>

Available on crate feature blocking only.

Ensures that the URL conforms with the expectations of its functions. If successful, this function may change the URL appropriately, e.g. a relative path would be turned into an absolute path.

This includes the expectation that open would minimally succeed, e.g. that the file exists or that the network endpoint is responsive. It does not otherwise guarantee that reading would be successful.

Source

fn conform_async(&self) -> Result<ConformFuture, UrlError>

Available on crate feature async only.

Async version of URL::conform.

Am important difference is that instead of mutating the URL it returns the new conformed version.

Source

fn open(&self) -> Result<ReadRef, UrlError>

Available on crate feature blocking only.

Opens the URL for reading by providing a dyn Read.

Note that for some URLs it may involve lengthy operations, e.g. cloning a remote repository, download a file, and/or unpacking an archive.

Thus, an effort is made to not repeat these lengthy operations by caching relevant state via the URL’s UrlContext. For example, when accessing a “git:” URL on a remote repository that repository will be cloned locally only if it’s the first time the repository has been referred to for the UrlContext. Subsequent open calls for URLs that refer to the same git repository will reuse the existing clone.

An effect of this optimization is that you might not be reading the most recent version of the resource the URL points to. If that is undesirable, call reset on the UrlContext cache.

Source

fn open_async(&self) -> Result<OpenFuture, UrlError>

Available on crate feature async only.

Async version of URL::open. Provides a dyn AsyncRead.

Provided Methods§

Source

fn key(&self) -> String

Returns a string that uniquely identifies the URL.

Useful as a map or cache key.

Source

fn query(&self) -> Option<UrlQuery>

The optional query.

Source

fn fragment(&self) -> Option<String>

The optional fragment.

Source

fn format(&self) -> Option<String>

Format of the URL content’s canonical representation.

Can return “text”, “yaml”, “json”, “tar”, “tar.gz”, etc.

The format is often derived from a file extension if available, otherwise it might be retrieved from metadata.

An attempt is made to standardize the return values, e.g. a “yml” file extension is always returned as “yaml”, and a “tgz” file extension is always returned as “tar.gz”.

Source