Struct Selector 

pub struct Selector { /* private fields */ }

Selector.

Selectors are used to match identifiers. Like identifiers, they consist of six components, which can be set to specific values or left empty to act as wildcards. Each component can be set to a glob as supported by globset, which allows for powerful matching capabilities.

Selectors are no means to an end, but rather a building block to associate data or functions to identifiers via the construction of a Matcher, which uses an efficient algorithm to match an arbitrary set of selectors in linear time. While it’s recommended to use Selector::builder together with the associated methods to create a new selector, selectors can also be created from a structured string representation with Selector::from_str, which is used internally for serializing them to persistent storage:

zrs:<provider>:<resource>:<variant>:<context>:<location>:<fragment>

This ensures blazing fast cloning and editing. Additionally, selectors are guaranteed to not contain backslashes or path traversals in components. An empty component is interpreted as a wildcard, and thus matches all values in that component for any given selector.

Examples

Create a selector:

use zrx_id::Selector;

// Create selector builder
let builder = Selector::builder().location("**/*.md");

// Create selector from builder
let selector = builder.build()?;
assert_eq!(selector.as_str(), "zrs:::::**/*.md:");

Create a selector from a string:

use zrx_id::Selector;

// Create selector from string
let selector: Selector = "zrs:::::**/*.md:".parse()?;

Implementations

impl Selector

pub fn builder<'a>() -> Builder<'a>

Creates a selector builder.

Examples

use zrx_id::Selector;

// Create selector builder
let builder = Selector::builder();

pub fn to_builder(&self) -> Builder<'_>

Creates a builder from the selector.

This method creates a builder from the current selector, which allows to modify components and build a new selector from an existing one.

Examples

use zrx_id::Selector;

// Create selector from string
let selector: Selector = "zrs:::::**/*.md:".parse()?;

// Create selector builder
let builder = selector.to_builder().location("index.md");

// Create selector from builder
let selector = builder.build()?;
assert_eq!(selector.as_str(), "zrs:::::index.md:");

impl Selector

pub fn as_str(&self) -> &str

Returns the string representation.

Examples

use zrx_id::Selector;

// Create selector from string
let selector: Selector = "zrs:::::**/*.md:".parse()?;

// Obtain string representation
assert_eq!(selector.as_str(), "zrs:::::**/*.md:");

impl Selector

pub fn provider(&self) -> Option<Cow<'_, str>>

Returns the provider component, if any.

pub fn resource(&self) -> Option<Cow<'_, str>>

Returns the resource component, if any.

pub fn variant(&self) -> Option<Cow<'_, str>>

Returns the variant component, if any.

pub fn context(&self) -> Option<Cow<'_, str>>

Returns the context component, if any.

pub fn location(&self) -> Option<Cow<'_, str>>

Returns the location component, if any.

pub fn fragment(&self) -> Option<Cow<'_, str>>

Returns the fragment component, if any.

Trait Implementations

impl AsRef<Format<7>> for Selector

fn as_ref(&self) -> &Format<7>

Returns the formatted string.

Note that it’s normally not necessary to access the formatted string directly, as all components can be accessed via the respective methods. We need to access the underlying formatted string in our internal APIs, e.g., to compute the Specificity for the given Selector.

impl Clone for Selector

fn clone(&self) -> Selector

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Selector

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

Formats the selector for debugging.

impl Display for Selector

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

Formats the selector for display.

impl From<Selector> for Term

fn from(selector: Selector) -> Self

Creates a term from a selector.

impl FromStr for Selector

fn from_str(value: &str) -> Result<Self>

Attempts to create a selector from a string.

The string must adhere to the following format and include exactly six : separators, even if some components are empty. All components are optional, which means they can be left empty, which is equivalent to setting them to a ** wildcard.

zrs:<provider>:<resource>:<variant>:<context>:<location>:<fragment>

Errors

Returns Error::Prefix if the prefix isn’t zrs. Low-level format errors are returned as part of Error::Format.

Examples

use zrx_id::Selector;

// Create selector from string
let selector: Selector = "zrs:::::**/*.md:".parse()?;

type Err = Error

The associated error which can be returned from parsing.

impl Hash for Selector

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the selector.

Since selectors are immutable, we can use a precomputed hash for fast hashing. This is especially useful when selectors are used as keys in hash maps or hash sets, where hashing is a frequent operation, as the performance gains are significant.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Selector

fn cmp(&self, other: &Self) -> Ordering

Orders two selectors.

Examples

use zrx_id::Selector;

// Create and compare selectors
let a: Selector = "zrs:::::**/*.md:".parse()?;
let b: Selector = "zrs:::::**/*.rs:".parse()?;
assert!(a < b);

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Selector

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

Compares two selectors for equality.

Examples

use zrx_id::Selector;

// Create and compare selectors
let a: Selector = "zrs:::::**/*.md:".parse()?;
let b: Selector = "zrs:::::**/*.md:".parse()?;
assert_eq!(a, b);

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 PartialOrd for Selector

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

Orders two selectors.

Examples

use zrx_id::Selector;

// Create and compare selectors
let a: Selector = "zrs:::::**/*.md:".parse()?;
let b: Selector = "zrs:::::**/*.rs:".parse()?;
assert!(a < b);

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl ToSpecificity for Selector

fn to_specificity(&self) -> Specificity

Computes the specificity of the selector.

Examples

use zrx_id::selector;
use zrx_id::specificity::ToSpecificity;

// Create selector and compute specificity
let selector = selector!(location = "**/*.md")?;
assert_eq!(selector.to_specificity(), (0, 1, 1, 3).into());

impl TryFrom<Id> for Selector

fn try_from(id: Id) -> Result<Self>

Attempts to create a selector from an identifier.

An Id can be converted into a Selector because all identifiers are also valid selectors, as they represent exact matches. However, the reverse is not true, as selectors can contain wildcards, as well as optional components, which identifiers cannot.

Examples

use zrx_id::{Id, Selector};

// Create selector from identifier
let id: Id = "zri:file:::docs:index.md:".parse()?;
let selector: Selector = id.try_into()?;

type Error = Error

The type returned in the event of a conversion error.

impl TryFrom<Term> for Selector

fn try_from(term: Term) -> Result<Self>

Attempts to create a selector from a term.

Examples

use zrx_id::expression::Term;
use zrx_id::{Id, Selector};

// Create selector from identifier
let id: Id = "zri:file:::docs:index.md:".parse()?;
let selector: Selector = Term::from(id).try_into()?;

type Error = Error

The type returned in the event of a conversion error.

impl TryToSelector for Selector

fn try_to_selector(&self) -> Result<Cow<'_, Selector>>

Attempts to convert to a selector.

impl Eq for Selector