Struct initiative_core::app::CommandMatches

pub struct CommandMatches<T> {
    pub canonical_match: Option<T>,
    pub fuzzy_matches: Vec<T>,
}

Represents all possible parse results for a given input.

One of the key usability features (and major headaches) of initiative.sh is its use of fuzzy command matching. Most parsers assume only one possible valid interpretation, but initiative.sh has the concept of canonical and fuzzy matches.

Canonical matches are inputs that cannot possibly conflict with one another. This is achieved using differing prefixes, eg. all SRD reference lookups are prefixed as “srd item shield” (or “srd spell shield”).

Fuzzy matches are commands that the user could possibly have meant with a given input. The reason we need to be particularly careful with fuzzy matches is because the user can add arbitrary names to their journal, and typing that arbitrary name is usually enough to pull it up again. However, that arbitrary name could easily be another command, which the user may not want to overwrite. (The notable built-in conflict is the example above, where “shield” is both an item and a spell.)

|| Canonical matches || Fuzzy matches || Result || | 0 | 0 | Error: “Unknown command: ‘…’” | | 0 | 1 | The fuzzy match is run. | | 0 | 2+ | Error: “There are several possible interpretations of this command. Did you mean:” | | 1 | 0 | The canonical match is run. | | 1 | 1+ | The canonical match is run, suffixed with the error: “There are other possible interpretations of this command. Did you mean:” |

Since the parsing logic in the code base runs several layers deep across a number of different structs, this struct provides utilities for combining multiple CommandMatches instances of differing types, and for transforming the inner type as needed.

Fields

canonical_match: Option<T>

fuzzy_matches: Vec<T>

Implementations

impl<T: Debug> CommandMatches<T>

pub fn new_canonical(canonical_match: T) -> Self

Create a new instance of CommandMatches with a canonical match.

pub fn new_fuzzy(fuzzy_match: T) -> Self

Create a new instance of CommandMatches with a single fuzzy match.

pub fn push_canonical(&mut self, canonical_match: T)

Push a new canonical match. Panics if a canonical match is already present.

pub fn push_fuzzy(&mut self, fuzzy_match: T)

Add a new fuzzy match to the list of possibilities.

pub fn union<O>(self, other: CommandMatches<O>) -> Self

where O: Debug, T: From<O>,

Combine the current CommandMatches with another object that can be massaged into the same type. The Vecs of fuzzy matches are combined. Panics if both objects lay claim to a canonical match.

pub fn union_with_overwrite<O>(self, other: CommandMatches<O>) -> Self

where O: Debug, T: From<O>,

Variant of union() that resolves canonical conflicts by overwriting self.canonical_match with other.canonical_match instead of panicking.

pub fn into_subtype<O>(self) -> CommandMatches<O>

where O: From<T> + Debug,

Convert a CommandMatches<T>' into a CommandMatches, massaging the inner type using its From` trait.

This could be an impl of From<CommandMatches<T>> for CommandMatches<O>, but that produces a trait conflict due to limitations of Rust’s type system.

pub fn take_best_match(self) -> Option<T>

Consumes the struct, returning the following in priority order:

1. The canonical match, if present.
2. The first fuzzy match, if any are present.
3. None

Trait Implementations

impl<T: Clone> Clone for CommandMatches<T>

fn clone(&self) -> CommandMatches<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for CommandMatches<T>

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

Formats the value using the given formatter.

impl<T> Default for CommandMatches<T>

fn default() -> Self

Returns the “default value” for a type.

impl From<CommandMatches<CommandType>> for Command

fn from(input: CommandMatches<CommandType>) -> Self

Converts to this type from the input type.

impl<T> From<T> for CommandMatches<T>

fn from(input: T) -> Self

Converts to this type from the input type.

impl<T: PartialEq> PartialEq for CommandMatches<T>

fn eq(&self, other: &CommandMatches<T>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl<T: Eq> Eq for CommandMatches<T>

impl<T> StructuralPartialEq for CommandMatches<T>