argx 0.2.2

Expressive command-line parsing and configuration for Rust.
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

//! Finite command-line value vocabularies.
//!
//! Derive [`trait@ValueEnum`] for enums whose accepted CLI values are known in advance, then mark
//! fields with `#[argx(value_enum)]` to use the same values for parsing, help, completion, and
//! schema discovery.

use crate::error::display_bytes;

/// A finite set of canonical command-line values.
///
/// Derive this trait with `#[derive(argx::ValueEnum)]`, then opt a field into the vocabulary with
/// `#[argx(value_enum)]`. Derived variants use Argx's normal kebab-case spelling and parsing is
/// exact and case-sensitive.
pub trait ValueEnum: Sized {
    /// Canonical values accepted from the command line, in declaration order.
    const VALUES: &'static [&'static str];

    /// Parses one canonical value.
    ///
    /// This method is part of the generated-code contract. Applications normally parse through a
    /// derived [`crate::Parser`] field or through the `FromStr` implementation emitted by the
    /// `ValueEnum` derive.
    #[doc(hidden)]
    fn from_value(value: &str) -> Option<Self>;
}

/// Error returned by the `FromStr` implementation generated for a [`trait@ValueEnum`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("{}", display_value_enum_values(.values))]
pub struct ValueEnumError {
    /// Canonical values expected by the generated parser.
    values: &'static [&'static str],
}

impl ValueEnumError {
    /// Creates an error describing one finite accepted vocabulary.
    #[doc(hidden)]
    #[must_use]
    pub const fn new(values: &'static [&'static str]) -> Self {
        Self { values }
    }
}

/// Renders the finite accepted vocabulary for a value-enum diagnostic.
fn display_value_enum_values(values: &[&str]) -> String {
    if values.is_empty() {
        return String::from("no values are accepted");
    }

    let mut rendered = String::from("expected one of: ");
    for (index, value) in values.iter().enumerate() {
        if index > 0 {
            rendered.push_str(", ");
        }
        rendered.push_str(&display_bytes(value.as_bytes()));
    }
    rendered
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn error_values_do_not_emit_terminal_controls() {
        static VALUES: &[&str] = &["safe", "bad\n\u{1b}[31m"];
        let rendered = ValueEnumError::new(VALUES).to_string();

        assert!(!rendered.contains('\n'));
        assert!(!rendered.contains('\u{1b}'));
        assert!(rendered.contains(r"bad\n"));
    }
}