Trait Parsable

Source

pub trait Parsable<Ctx> {
    type Parser: Parser<Ctx, Value = Self>;
}

Expand description

Sets the default parser for a given type

This trait allows the users of a type to avoid specifying the parser explicitly.

This trait can be procedurally derived for any struct or enum if all its inner types are Parsable or have explicit parser specified.

§Derive macro

The Parsable derive macro accepts attributes that modify parsing behavior. These attributes are specified in the form #[cmd(...)] attributes can be specifed in the same parenthesis separated by commas or separately: #[cmd(default, attr(field))] and #[cmd(default)] #[cmd(attr(field))] are equivalent.

§Type attribute

The following attributes are applied to the entire struct or enum for which the trait is being derived.

§`ctx = "type-name"`, `ctx_bound = "trait-names"`

Restricts the type of the parsing context in case of ctx attribute or bounds the generic parsing context to the specific trait or collection of traits in case ctx_bound attribute is used. This is needed when one or more inner parser restricts the type of the context it uses.

The following example demonstrates the creation of a custom parser that requires a specific parsing context and restricting the context type in the derived trait implementation.

use kmdparse::{parse, tokens::TokenStream, CompletionResult, Parsable, Parser, ParseResult};

#[derive(Debug, Copy, Clone, PartialEq, Eq)]
enum LengthUnit { Cm, In }

#[derive(Clone)]
struct ParsingContext {
    unit: LengthUnit,
}

#[derive(Debug, PartialEq)]
struct Length(f64, LengthUnit);

#[derive(Default)]
struct LengthParser;

impl Parser<ParsingContext> for LengthParser {
    type Value = Length;

    fn parse<'a>(&self, input: TokenStream<'a>, ctx: ParsingContext) -> ParseResult<'a, Self::Value> {
        let unit = ctx.unit;
        let parser = <f64 as Parsable<ParsingContext>>::Parser::default();
        let (value, remaining) = parser.parse(input, ctx)?;
        Ok((Length(value, unit), remaining))
    }

    fn complete<'a>(&self, input: TokenStream<'a>, ctx: ParsingContext) -> CompletionResult<'a> {
        let parser = <f64 as Parsable<ParsingContext>>::Parser::default();
        parser.complete(input, ctx)
    }
}

impl Parsable<ParsingContext> for Length {
    type Parser = LengthParser;
}

#[derive(Debug, PartialEq, Parsable)]
#[cmd(ctx = "ParsingContext")]
struct Size {
    height: Length,
    width: Length,
}

assert_eq!(
    parse::<_, Size>("10 20", ParsingContext{ unit: LengthUnit::Cm })?,
    Size {
        height: Length(10.0, LengthUnit::Cm),
        width: Length(20.0, LengthUnit::Cm)
    }
);

§Field attributes

The following attributes can be used for the struct’s or enum variant’s fields.

§`parser = "parser-type-name"`

Specifies a custom parser used for a field.

This attribute is useful in situations where the required parser is different from the parser defined by the Parsable trait (which is used by default) or when implementation of Parsable is not possible (e.g. when dealing with types defined in a foreign crate).

The following example demonstrates how to use TransformParser for data validation.

use kmdparse::parsers::{TransformParser, ParsableTransformation};
use kmdparse::error::ParseError;
use kmdparse::Parsable;

struct Number01RangeValidator;

impl ParsableTransformation<f64> for Number01RangeValidator {
    type Input = f64;

    fn transform(input: Self::Input) -> Result<f64, ParseError<'static>> {
        if input < 0.0 || input >= 1.0 {
            Err(ParseError::custom("must be between 0 and 1"))
        } else {
            Ok(input)
        }
    }
}

#[derive(Debug, Parsable)]
struct Point(
    #[cmd(parser = "TransformParser<<f64 as Parsable<kmdparserCtx>>::Parser, Number01RangeValidator, f64>")] f64,
    #[cmd(parser = "TransformParser<<f64 as Parsable<kmdparserCtx>>::Parser, Number01RangeValidator, f64>")] f64,
);

§`default` or `default = "value"` without `attr`

If the default attribute is used on a field, this field will not be parsed. Instead, when constructing the containing instance, the parser uses a default value (if value is not specified) or a specific value (specified after = sign).

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
struct MyStruct(#[cmd(default)] u8, #[cmd(default = "5")] u8, u8);

assert_eq!(parse::<_, MyStruct>("24", ())?, MyStruct(0, 5, 24));

§`attr(attribute = "value")` or `attr(attribute)`

Indicates that the field is optional, it can be specified by the user using a named attribute. This attribute comes in two variants: when “value” is specified, the field’s value is taken from the expression in the attribute, otherwise the attribute token must be followed by the field value’s tokens.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum Color{ Red, Green, Blue }

impl Default for Color {
    fn default() -> Self {
        Color::Green
    }
}

#[derive(Debug, PartialEq, Eq, Parsable)]
struct MyStruct {
    #[cmd(attr(important = "true"))] is_important: bool,
    #[cmd(attr(color))] color: Color,
}

assert_eq!(
    parse::<_, MyStruct>("--important", ())?,
    MyStruct { color: Color::Green, is_important: true },
);
assert_eq!(
    parse::<_, MyStruct>("--color red", ())?,
    MyStruct { color: Color::Red, is_important: false },
);

§In combination with `default = "value"`

If an optional field’s value is not specified, the default value is used instead, as determined by the implementation of Default trait. This can be overridden by specifying a default value using default attribute.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
struct MyStruct(#[cmd(default = "5", attr(value))] u8);

assert_eq!(parse::<_, MyStruct>("--value 10", ())?, MyStruct(10));
assert_eq!(parse::<_, MyStruct>("", ())?, MyStruct(5));

§`alias_value(alias = "alias", value="value")`

Used for enum variant’s fields. Specifies the value for a field if the specific alias is used as enum’s discriminator. An alias can be either a name of a variant (converted into kebab-case), a renamed variant name (via rename attribute), or an alias defined using alias attribute.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum MyEnum {
    #[cmd(alias = "enable", alias = "disable")]
    SetEnabled(
        #[cmd(
            alias_value(alias = "enable", value = "true"),
            alias_value(alias = "disable", value = "false")
        )] bool
    )
}

assert_eq!(parse::<_, MyEnum>("enable", ())?, MyEnum::SetEnabled(true));
assert_eq!(parse::<_, MyEnum>("disable", ())?, MyEnum::SetEnabled(false));

§Enum variant attributes

These attributes are applicable to enum variants. Generally, kmdparse expects a discriminator—the variant’s name in kebab-case followed by tokens for its fields if any exist.

§`rename = "name"`

Changes the name of the variant’s discriminator. The variant cannot be parsed using its original name.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum MyEnum {
    #[cmd(rename = "first")] One,
    #[cmd(rename = "second")] Two,
}

assert_eq!(parse::<_, MyEnum>("first", ())?, MyEnum::One);
assert!(parse::<_, MyEnum>("one", ()).is_err());

§`alias = "alias"`

Adds an alias for the variant. Variant can have an arbitrary number of aliases and the value can be parsed using any of this. Specifying an alias does not prevent the usage of the variant’s original name.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum Color {
    Black,
    White,
    #[cmd(alias = "grey")] Gray,
}

assert_eq!(parse::<_, Color>("grey", ())?, Color::Gray);
assert_eq!(parse::<_, Color>("gray", ())?, Color::Gray);

§`ignore`

Disables the parsing of the variant. Note that this does not prevent assigning aliases to the variant.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum MyEnum {
    Command,
    #[cmd(ignore)] NonInteractive,
}

assert!(parse::<_, MyEnum>("non-interactive", ()).is_err());

§`transparent`

Indicates that a variant can be parsed without a discriminator. This can be used when splitting a large enum into several smaller ones is desirable.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq, Eq, Parsable)]
enum Subcommand { First, Second }

#[derive(Debug, PartialEq, Eq, Parsable)]
enum Command {
    #[cmd(transparent)]
    Subcommand(Subcommand),
    Third,
}

assert_eq!(parse::<_, Command>("first", ())?, Command::Subcommand(Subcommand::First));
assert_eq!(parse::<_, Command>("third", ())?, Command::Third);

§`transparent_no_error`

Functions similarly to transparent but does not terminate parsing on failure. It is useful when the first field of this variant is not an enum.

use kmdparse::{Parsable, parse};

#[derive(Debug, PartialEq,Parsable)]
enum Value {
    #[cmd(transparent_no_error)] Integer(i64),
    #[cmd(transparent_no_error)] Real(f64),
    #[cmd(transparent_no_error)] Boolean(bool),
}

assert_eq!(parse::<_, Value>("0.4", ())?, Value::Real(0.4));
assert_eq!(parse::<_, Value>("12", ())?, Value::Integer(12));
assert_eq!(parse::<_, Value>("true", ())?, Value::Boolean(true));

Note that in the example above, the orders in which the enum variants are declared matters: kmdparse tries to parse transparent variants in order in which they are declared and returns the first successfully parsed result.

Required Associated Types§

Source

type Parser: Parser<Ctx, Value = Self>

The parser type for this type

Parsable

Trait Parsable Copy item path

§Derive macro

§Type attribute

§ctx = "type-name", ctx_bound = "trait-names"

§Field attributes

§parser = "parser-type-name"

§default or default = "value" without attr

§attr(attribute = "value") or attr(attribute)

§In combination with default = "value"

§alias_value(alias = "alias", value="value")

§Enum variant attributes

§rename = "name"

§alias = "alias"

§ignore

§transparent

§transparent_no_error

Required Associated Types§

type Parser: Parser<Ctx, Value = Self>

Implementations on Foreign Types§

impl<Ctx> Parsable<Ctx> for IpAddr

type Parser = FromStrParser<IpAddr>

impl<Ctx> Parsable<Ctx> for SocketAddr

type Parser = FromStrParser<SocketAddr>

impl<Ctx> Parsable<Ctx> for bool

type Parser = BooleanParser

impl<Ctx> Parsable<Ctx> for f32

type Parser = FromStrParser<f32>

impl<Ctx> Parsable<Ctx> for f64

type Parser = FromStrParser<f64>

impl<Ctx> Parsable<Ctx> for i8

type Parser = IntegerParser<i8>

impl<Ctx> Parsable<Ctx> for i16

type Parser = IntegerParser<i16>

impl<Ctx> Parsable<Ctx> for i32

type Parser = IntegerParser<i32>

impl<Ctx> Parsable<Ctx> for i64

type Parser = IntegerParser<i64>

impl<Ctx> Parsable<Ctx> for i128

type Parser = IntegerParser<i128>

impl<Ctx> Parsable<Ctx> for isize

type Parser = IntegerParser<isize>

impl<Ctx> Parsable<Ctx> for u8

type Parser = IntegerParser<u8>

impl<Ctx> Parsable<Ctx> for u16

type Parser = IntegerParser<u16>

impl<Ctx> Parsable<Ctx> for u32

type Parser = IntegerParser<u32>

impl<Ctx> Parsable<Ctx> for u64

type Parser = IntegerParser<u64>

impl<Ctx> Parsable<Ctx> for u128

type Parser = IntegerParser<u128>

impl<Ctx> Parsable<Ctx> for ()

type Parser = DefaultValueParser<()>

impl<Ctx> Parsable<Ctx> for usize

type Parser = IntegerParser<usize>

impl<Ctx> Parsable<Ctx> for String

type Parser = StringParser

impl<Ctx> Parsable<Ctx> for Ipv4Addr

type Parser = FromStrParser<Ipv4Addr>

impl<Ctx> Parsable<Ctx> for Ipv6Addr

type Parser = FromStrParser<Ipv6Addr>

impl<Ctx> Parsable<Ctx> for SocketAddrV4

type Parser = FromStrParser<SocketAddrV4>

impl<Ctx> Parsable<Ctx> for SocketAddrV6

type Parser = FromStrParser<SocketAddrV6>

impl<Ctx> Parsable<Ctx> for PathBuf

type Parser = PathParser

impl<Ctx> Parsable<Ctx> for NonZeroI8

type Parser = IntegerParser<NonZero<i8>>

impl<Ctx> Parsable<Ctx> for NonZeroI16

type Parser = IntegerParser<NonZero<i16>>

impl<Ctx> Parsable<Ctx> for NonZeroI32

type Parser = IntegerParser<NonZero<i32>>

impl<Ctx> Parsable<Ctx> for NonZeroI64

type Parser = IntegerParser<NonZero<i64>>

impl<Ctx> Parsable<Ctx> for NonZeroI128

type Parser = IntegerParser<NonZero<i128>>

impl<Ctx> Parsable<Ctx> for NonZeroIsize

type Parser = IntegerParser<NonZero<isize>>