parkour 0.1.0

A fast, extensible command-line arguments parser
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Several utility types.

use std::fmt;
use std::fmt::Write as _;

use crate::actions::ApplyResult;
use crate::Parse;

/// The parsing context for a flag.
///
/// A flag is either short (i.e. it starts with a single dash) or long (i.e. it
/// starts with two dashes). Note that the dashes should **not** be written in
/// the string, i.e. use `Flag::Long("version")`, not `Flag::Long("--version")`.
///
/// Arguments can often be specified with a long and a short flag (e.g. `--help`
/// and `-h`); Use `Flag::LongShort("help", "h")` in this case. If an argument
/// has more than 2 flags, use `Flag::Many(vec![...])`.
#[derive(Debug, Clone)]
pub enum Flag<'a> {
    /// A short flag, like `-h`
    Short(&'a str),
    /// A long flag, like `--help`
    Long(&'a str),
    /// A flag with a long and a short alias, e.g. `-h,--help`.
    LongShort(&'a str, &'a str),
    /// A flag with multiple aliases
    Many(Box<[Flag<'a>]>),
}

impl Flag<'_> {
    /// Returns the first alias of the flag as a [String].
    pub fn first_to_string(&self) -> String {
        match self {
            &Flag::Short(s) => format!("-{}", s),
            &Flag::Long(l) => format!("--{}", l),
            &Flag::LongShort(l, _) => format!("--{}", l),
            Flag::Many(v) => v[0].first_to_string(),
        }
    }

    /// Parses a flag from a [`Parse`] instance.
    pub fn from_input<'a, P: Parse>(input: &mut P, context: &Flag<'a>) -> ApplyResult {
        Ok(match context {
            Flag::Short(f) => input.parse_short_flag(f),
            Flag::Long(f) => input.parse_long_flag(f),
            Flag::LongShort(l, s) => {
                input.parse_long_flag(l) || input.parse_short_flag(s)
            }
            Flag::Many(flags) => {
                flags.iter().any(|flag| Self::from_input(input, flag).is_ok())
            }
        })
    }
}

impl fmt::Display for Flag<'_> {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Flag::Short(s) => write!(f, "-{}", s),
            Flag::Long(l) => write!(f, "--{}", l),
            Flag::LongShort(l, s) => write!(f, "--{},-{}", l, s),
            Flag::Many(v) => {
                for (i, flag) in v.iter().enumerate() {
                    if i > 0 {
                        f.write_char(',')?;
                    }
                    fmt::Display::fmt(flag, f)?;
                }
                Ok(())
            }
        }
    }
}

/// The parsing context for a named argument, e.g. `--help=config`.
#[derive(Debug, Clone)]
pub struct ArgCtx<'a, C> {
    /// The flag before the argument value(s)
    pub flag: Flag<'a>,
    /// The context for the argument value(s)
    pub inner: C,
}

impl<'a, C> ArgCtx<'a, C> {
    /// Creates a new `ArgCtx` instance
    pub fn new(flag: Flag<'a>, inner: C) -> Self {
        Self { flag, inner }
    }
}

impl<'a, C: Default> From<Flag<'a>> for ArgCtx<'a, C> {
    fn from(flag: Flag<'a>) -> Self {
        ArgCtx { flag, inner: C::default() }
    }
}

/// The parsing context for a positional argument.
#[derive(Debug, Clone)]
pub struct PosCtx<'a, C> {
    /// The name of the positional argument, used in error messages
    pub name: &'a str,
    /// The context for the argument value
    pub inner: C,
}

impl<'a, C> PosCtx<'a, C> {
    /// Creates a new `PosCtx` instance
    pub fn new(name: &'a str, inner: C) -> Self {
        Self { name, inner }
    }
}

impl<'a, C: Default> From<&'a str> for PosCtx<'a, C> {
    fn from(name: &'a str) -> Self {
        PosCtx { name, inner: C::default() }
    }
}