Struct SubjectScheme 

pub struct SubjectScheme { /* private fields */ }

How a subject is composed: literal segments and placeholders in braces, as in /tenant/{tenant}/workshop/{workshop}.

A scheme works in both directions. build composes a subject from values, and match_subject takes one apart again, or value takes a single value out of it, which a projection needs to recover the ID of an aggregate that the events themselves do not carry:

use architecturekit::SubjectScheme;

let workshops = SubjectScheme::new("/tenant/{tenant}/workshop/{workshop}");

let subject = workshops.build(&["acme", "event-sourcing"]);
assert_eq!(subject.as_str(), "/tenant/acme/workshop/event-sourcing");

assert_eq!(workshops.value(&subject, "workshop"), Some("event-sourcing"));

EventSourcingDB allows only ASCII letters and digits, underscores, and hyphens in a segment of a subject (see Subject), so this is what the literal segments of a pattern and the values of its placeholders may contain. The names of its placeholders follow the same rule, so that a typo, such as a brace too many, is not taken for a name.

Implementations

impl SubjectScheme

pub fn new(pattern: &str) -> Self

Parses a pattern.

Panics

A malformed pattern, including one with a literal segment or a placeholder name that contains a character EventSourcingDB does not allow in a subject, is a programming error, so this panics while the scheme is being built.

pub fn pattern(&self) -> &str

Returns the pattern the scheme was built from.

pub fn root(&self) -> Subject

Returns the subject that every subject of the scheme lies under: the literal segments before the first placeholder, as /tenant for /tenant/{tenant}/workshop/{workshop}, or / if the pattern starts with a placeholder. Reading or observing recursively from it yields the events of all subjects the scheme describes, and possibly of others under the same root, which match_subject tells apart.

pub fn placeholders(&self) -> &[String]

Returns the placeholder names, in the order build expects their values.

pub fn build<V: AsRef<str>>(&self, values: &[V]) -> Subject

Composes a subject. The values fill the placeholders in the order they appear in the pattern.

Panics

A wrong number of values, or one that check refuses, such as an empty one or one with a slash or a dot, is a programming error, so this panics. Values that come from outside, such as an ID in a request, may well be like that, so build from them with try_build instead.

pub fn try_build<V: AsRef<str>>( &self, values: &[V], ) -> Result<Subject, SubjectValuesError>

Composes a subject from values that come from outside, such as an ID in a request, as build does, but refuses values that check refuses, rather than panicking:

use architecturekit::SubjectScheme;

let books = SubjectScheme::new("/books/{book_id}");

assert_eq!(books.try_build(&["42"])?.as_str(), "/books/42");
assert!(books.try_build(&["a.b"]).is_err());

Errors

Fails with what check fails with.

pub fn check<V: AsRef<str>>( &self, values: &[V], ) -> Result<(), SubjectValuesError>

Tells whether the values can compose a subject: one per placeholder, none of them empty, and each made only of the characters EventSourcingDB allows in a segment of a subject, which are A-Z, a-z, 0-9, underscores, and hyphens. It is what build insists on, as an error rather than a panic, for values that come from outside.

The error may reach the caller of an API, so it names the placeholder of a value, but neither the crate nor the pattern, as in: value for “id” must not be empty. The panic of build names both, since it is for the developer.

Errors

Fails if the values can not compose a subject, as described above.

pub fn match_subject<'scheme, 'subject, S>( &'scheme self, subject: &'subject S, ) -> Option<HashMap<&'scheme str, &'subject str>>

where S: AsRef<str> + ?Sized,

Takes a subject apart, into the value of every placeholder, by its name. It returns None if the subject does not follow the pattern, which is an ordinary case for a projection reading recursively across several schemes. A subject with a value that check refuses does not follow it either, so that this takes apart only what build composes.

It is called match_subject rather than match, which is a keyword in Rust. To take a single value out of a subject, use value, which panics for a name the pattern does not have. It takes a Subject as well as text.

pub fn value<'subject, S>( &self, subject: &'subject S, placeholder: &str, ) -> Option<&'subject str>

where S: AsRef<str> + ?Sized,

Takes the value of a single placeholder out of a subject. It returns None if the subject does not follow the pattern, as match_subject does. To take several values out of the same subject, use match_subject.

Panics

A placeholder that the pattern does not have, such as one with a typo, is a programming error, so this panics, whatever the subject is.

Trait Implementations

impl Clone for SubjectScheme

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SubjectScheme

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

Formats the value using the given formatter.

impl Eq for SubjectScheme

impl PartialEq for SubjectScheme

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for SubjectScheme