Skip to main content

## Module typed_derive

Source
Available on crate feature `unstable-doc` only.
Expand description

## §Example: Custom Types (Derive API)

This requires enabling the `derive` feature flag.

### §Implicit `Arg::value_parser`

    use clap::Args;
    use clap::ValueEnum;

    #[derive(Args, Debug)]
    pub(crate) struct ImplicitParsers {
        /// Implicitly using `std::str::FromStr`
        #[arg(short = 'O')]
        optimization: Option<usize>,

        /// Allow invalid UTF-8 paths
        #[arg(short = 'I', value_name = "DIR", value_hint = clap::ValueHint::DirPath)]
        include: Option<std::path::PathBuf>,

        /// Handle IP addresses
        #[arg(long)]
        bind: Option<std::net::IpAddr>,

        /// Allow human-readable durations
        #[arg(long)]
        sleep: Option<jiff::SignedDuration>,

        /// Custom enums
        #[arg(long)]
        bump_level: Option<BumpLevel>,
    }

    #[derive(Debug, Clone, Copy, ValueEnum)]
    #[value(rename_all = "kebab-case")]
    pub(crate) enum BumpLevel {
        /// Increase the major version (x.0.0)
        Major,
        /// Increase the minor version (x.y.0)
        Minor,
        /// Increase the patch version (x.y.z)
        Patch,
    }

    impl std::fmt::Display for BumpLevel {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
            use clap::ValueEnum;

            self.to_possible_value()
                .expect("no values are skipped")
                .get_name()
                .fmt(f)
        }
    }

    impl std::str::FromStr for BumpLevel {
        type Err = String;

        fn from_str(s: &str) -> Result<Self, Self::Err> {
            use clap::ValueEnum;

            for variant in Self::value_variants() {
                if variant.to_possible_value().unwrap().matches(s, false) {
                    return Ok(*variant);
                }
            }
            Err(format!("Invalid variant: {s}"))
        }
    }

Help:

    $ typed-derive implicit --help
    Usage: typed-derive implicit [OPTIONS]

    Options:
      -O <OPTIMIZATION>
              Implicitly using `std::str::FromStr`

      -I <DIR>
              Allow invalid UTF-8 paths

          --bind <BIND>
              Handle IP addresses

          --sleep <SLEEP>
              Allow human-readable durations

          --bump-level <BUMP_LEVEL>
              Custom enums

              Possible values:
              - major: Increase the major version (x.0.0)
              - minor: Increase the minor version (x.y.0)
              - patch: Increase the patch version (x.y.z)

      -h, --help
              Print help (see a summary with '-h')

Optimization-level (number)

    $ typed-derive implicit -O 1
    Implicit(ImplicitParsers { optimization: Some(1), include: None, bind: None, sleep: None, bump_level: None })

    $ typed-derive implicit -O plaid
    ? failed
    error: invalid value 'plaid' for '-O <OPTIMIZATION>': invalid digit found in string

    For more information, try '--help'.

Include (path)

    $ typed-derive implicit -I../hello
    Implicit(ImplicitParsers { optimization: None, include: Some("../hello"), bind: None, sleep: None, bump_level: None })

IP Address

    $ typed-derive implicit --bind 192.0.0.1
    Implicit(ImplicitParsers { optimization: None, include: None, bind: Some(192.0.0.1), sleep: None, bump_level: None })

    $ typed-derive implicit --bind localhost
    ? failed
    error: invalid value 'localhost' for '--bind <BIND>': invalid IP address syntax

    For more information, try '--help'.

Time

    $ typed-derive implicit --sleep 10s
    Implicit(ImplicitParsers { optimization: None, include: None, bind: None, sleep: Some(10s), bump_level: None })

    $ typed-derive implicit --sleep forever
    ? failed
    error: invalid value 'forever' for '--sleep <SLEEP>': failed to parse input in the "friendly" duration format: expected duration to start with a unit value (a decimal integer) after an optional sign, but no integer was found

    For more information, try '--help'.

Version field

    $ typed-derive implicit --bump-level minor
    Implicit(ImplicitParsers { optimization: None, include: None, bind: None, sleep: None, bump_level: Some(Minor) })

    $ typed-derive implicit --bump-level 10.0.0
    ? failed
    error: invalid value '10.0.0' for '--bump-level <BUMP_LEVEL>'
      [possible values: major, minor, patch]

    For more information, try '--help'.

    $ typed-derive implicit --bump-level blue
    ? failed
    error: invalid value 'blue' for '--bump-level <BUMP_LEVEL>'
      [possible values: major, minor, patch]

    For more information, try '--help'.

### §Built-in `TypedValueParser`

    use clap::Args;
    use clap::builder::TypedValueParser as _;

    use crate::foreign_crate;

    #[derive(Args, Debug)]
    pub(crate) struct BuiltInParsers {
        /// Support for discrete numbers
        #[arg(
            long,
            default_value_t = 22,
            value_parser = clap::builder::PossibleValuesParser::new(["22", "80"])
                .map(|s| s.parse::<usize>().unwrap()),
        )]
        port: usize,

        /// Support enums from a foreign crate that don't implement `ValueEnum`
        #[arg(
            long,
            default_value_t = foreign_crate::LogLevel::Info,
            value_parser = clap::builder::PossibleValuesParser::new(["trace", "debug", "info", "warn", "error"])
                .map(|s| s.parse::<foreign_crate::LogLevel>().unwrap()),
        )]
        log_level: foreign_crate::LogLevel,
    }

Help:

    $ typed-derive builtin --help
    Usage: typed-derive builtin [OPTIONS]

    Options:
          --port <PORT>            Support for discrete numbers [default: 22] [possible values: 22, 80]
          --log-level <LOG_LEVEL>  Support enums from a foreign crate that don't implement `ValueEnum` [default: info] [possible values: trace, debug, info, warn, error]
      -h, --help                   Print help

Discrete numbers

    $ typed-derive builtin --port 22
    Builtin(BuiltInParsers { port: 22, log_level: Info })

    $ typed-derive builtin --port 80
    Builtin(BuiltInParsers { port: 80, log_level: Info })

    $ typed-derive builtin --port
    ? failed
    error: a value is required for '--port <PORT>' but none was supplied
      [possible values: 22, 80]

    For more information, try '--help'.

    $ typed-derive builtin --port 3000
    ? failed
    error: invalid value '3000' for '--port <PORT>'
      [possible values: 22, 80]

    For more information, try '--help'.

Enums from crates that can’t implement `ValueEnum`

    $ typed-derive builtin --log-level debug
    Builtin(BuiltInParsers { port: 22, log_level: Debug })

    $ typed-derive builtin --log-level error
    Builtin(BuiltInParsers { port: 22, log_level: Error })

    $ typed-derive builtin --log-level
    ? failed
    error: a value is required for '--log-level <LOG_LEVEL>' but none was supplied
      [possible values: trace, debug, info, warn, error]

    For more information, try '--help'.

    $ typed-derive builtin --log-level critical
    ? failed
    error: invalid value 'critical' for '--log-level <LOG_LEVEL>'
      [possible values: trace, debug, info, warn, error]

    For more information, try '--help'.

### §Custom parser function

    use std::error::Error;

    use clap::Args;

    #[derive(Args, Debug)]
    pub(crate) struct FnParser {
        /// Hand-written parser for tuples
        #[arg(short = 'D', value_name = "KEY=VALUE", value_parser = parse_key_val::<String, i32>)]
        defines: Vec<(String, i32)>,
    }

    /// Parse a single key-value pair
    fn parse_key_val<T, U>(s: &str) -> Result<(T, U), Box<dyn Error + Send + Sync + 'static>>
    where
        T: std::str::FromStr,
        T::Err: Error + Send + Sync + 'static,
        U: std::str::FromStr,
        U::Err: Error + Send + Sync + 'static,
    {
        let pos = s
            .find('=')
            .ok_or_else(|| format!("invalid KEY=value: no `=` found in `{s}`"))?;
        Ok((s[..pos].parse()?, s[pos + 1..].parse()?))
    }

Help:

    $ typed-derive fn-parser --help
    Usage: typed-derive fn-parser [OPTIONS]

    Options:
      -D <KEY=VALUE>  Hand-written parser for tuples
      -h, --help      Print help

Defines (key-value pairs)

    $ typed-derive fn-parser -D Foo=10 -D Alice=30
    FnParser(FnParser { defines: [("Foo", 10), ("Alice", 30)] })

    $ typed-derive fn-parser -D Foo
    ? failed
    error: invalid value 'Foo' for '-D <KEY=VALUE>': invalid KEY=value: no `=` found in `Foo`

    For more information, try '--help'.

    $ typed-derive fn-parser -D Foo=Bar
    ? failed
    error: invalid value 'Foo=Bar' for '-D <KEY=VALUE>': invalid digit found in string

    For more information, try '--help'.

### §Custom `TypedValueParser`

    use clap::Args;

    use crate::implicit::BumpLevel;

    #[derive(Args, Debug)]
    pub(crate) struct CustomParser {
        /// Hand-implement `TypedValueParser`
        #[arg(long)]
        target_version: Option<TargetVersion>,
    }

    /// Enum or custom value
    #[derive(Clone, Debug)]
    pub(crate) enum TargetVersion {
        Relative(BumpLevel),
        Absolute(semver::Version),
    }

    impl std::fmt::Display for TargetVersion {
        fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
            match self {
                TargetVersion::Relative(bump_level) => {
                    write!(f, "{bump_level}")
                }
                TargetVersion::Absolute(version) => {
                    write!(f, "{version}")
                }
            }
        }
    }

    impl std::str::FromStr for TargetVersion {
        type Err = String;

        fn from_str(s: &str) -> Result<Self, Self::Err> {
            if let Ok(bump_level) = BumpLevel::from_str(s) {
                Ok(TargetVersion::Relative(bump_level))
            } else {
                Ok(TargetVersion::Absolute(
                    semver::Version::parse(s).map_err(|e| e.to_string())?,
                ))
            }
        }
    }

    /// Default to `TargetVersionParser` for `TargetVersion`, instead of `FromStr`
    impl clap::builder::ValueParserFactory for TargetVersion {
        type Parser = TargetVersionParser;

        fn value_parser() -> Self::Parser {
            TargetVersionParser
        }
    }

    #[derive(Copy, Clone)]
    pub(crate) struct TargetVersionParser;

    impl clap::builder::TypedValueParser for TargetVersionParser {
        type Value = TargetVersion;

        fn parse_ref(
            &self,
            cmd: &clap::Command,
            arg: Option<&clap::Arg>,
            value: &std::ffi::OsStr,
        ) -> Result<Self::Value, clap::Error> {
            let inner_parser = <TargetVersion as std::str::FromStr>::from_str;
            inner_parser.parse_ref(cmd, arg, value)
        }

        fn possible_values(
            &self,
        ) -> Option<Box<dyn Iterator<Item = clap::builder::PossibleValue> + '_>> {
            let inner_parser = clap::builder::EnumValueParser::<BumpLevel>::new();
            #[allow(clippy::needless_collect)] // Erasing a lifetime
            inner_parser.possible_values().map(|ps| {
                let ps = ps.collect::<Vec<_>>();
                let ps: Box<dyn Iterator<Item = clap::builder::PossibleValue> + '_> =
                    Box::new(ps.into_iter());
                ps
            })
        }
    }

Help:

    $ typed-derive custom --help
    Usage: typed-derive custom [OPTIONS]

    Options:
          --target-version <TARGET_VERSION>
              Hand-implement `TypedValueParser`

              Possible values:
              - major: Increase the major version (x.0.0)
              - minor: Increase the minor version (x.y.0)
              - patch: Increase the patch version (x.y.z)

      -h, --help
              Print help (see a summary with '-h')

Defines (key-value pairs)

    $ typed-derive custom --target-version major
    Custom(CustomParser { target_version: Some(Relative(Major)) })

    $ typed-derive custom --target-version 10.0.0
    Custom(CustomParser { target_version: Some(Absolute(Version { major: 10, minor: 0, patch: 0 })) })

    $ typed-derive custom --target-version 10
    ? failed
    error: invalid value '10' for '--target-version <TARGET_VERSION>': unexpected end of input while parsing major version number

    For more information, try '--help'.

    $ typed-derive custom --target-version blue
    ? failed
    error: invalid value 'blue' for '--target-version <TARGET_VERSION>': unexpected character 'b' while parsing major version number

    For more information, try '--help'.