fli 1.2.2

The commander.js like CLI Parser 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
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use super::value_types::ValueTypes;
use crate::error::{FliError, Result};
/// Represents the current state during argument parsing.
///
/// This enum implements a state machine that enforces valid transitions
/// during parsing, preventing invalid parse sequences.
///
/// # State Transitions
///
/// ```text
/// Start → InCommand → InOption ⇄ AcceptingValue
///   ↓         ↓           ↓
///   ↓         ↓       Breaking
///   └────→ InArgument ←──┘
///              ↓
///            End
/// ```
///
/// # Examples
///
/// ```rust
/// let mut state = ParseState::Start;
/// state.set_next_mode(ParseState::InCommand)?;
/// state.set_next_mode(ParseState::InOption)?;
/// ```
#[derive(Debug, Clone)]
pub enum ParseState {
    /// Initial state before parsing begins
    Start,
    /// Currently inside a command context (after command name verified)
    InCommand,
    /// Currently processing an option flag
    InOption,
    /// Waiting to consume value(s) for an option
    /// - First field: option name
    /// - Second field: expected value type
    AcceptingValue(String, ValueTypes),
    /// After "--" separator, all remaining args are positional
    Breaking,
    /// Processing a positional argument
    InArgument,
    /// Parsing completed successfully
    End,
}

impl ParseState {
    /// Attempts to transition to the next state.
    ///
    /// Validates the transition is legal before applying it.
    ///
    /// # Arguments
    ///
    /// * `next` - The desired next state
    ///
    /// # Returns
    ///
    /// * `Ok(&mut Self)` - If transition is valid
    /// * `Err(String)` - If transition is invalid with error message
    ///
    /// # Errors
    ///
    /// Returns an error if the transition violates state machine rules.
    ///
    /// # Examples
    ///
    /// ```rust
    /// let mut state = ParseState::Start;
    /// state.set_next_mode(ParseState::InCommand)?;  // OK
    /// state.set_next_mode(ParseState::Start)?;       // Error: can't go back to Start
    /// ```
    pub fn set_next_mode(&mut self, next: ParseState) -> Result<&mut Self> {
        if self.can_go_to_next(&next) {
            *self = next;
            Ok(self)
        } else {
            Err(FliError::InvalidStateTransition {
                from: format!("{:?}", self),
                to: format!("{:?}", next),
            })
        }
    }

    /// Checks if a transition to the given state is valid.
    ///
    /// # Arguments
    ///
    /// * `next` - The state to check transition validity for
    ///
    /// # Returns
    ///
    /// `true` if transition is allowed, `false` otherwise
    ///
    /// # Validation Rules
    ///
    /// - Cannot return to `Start`
    /// - Can only enter `InCommand` from `Start` or another `InCommand` (subcommands)
    /// - Can enter `InOption` from most states except `Start`
    /// - Can only enter `AcceptingValue` from `InOption`
    /// - Can enter `InArgument` from command, breaking, or another argument
    /// - Can enter `Breaking` from option or accepting value states
    /// - Can enter `End` from any state except `Start`

    pub fn can_go_to_next(&self, next: &ParseState) -> bool {
        match next {
            ParseState::Start => false, // cannot go back to start

            // can only go to command from start or another command (subcommands)
            ParseState::InCommand => matches!(self, ParseState::Start | ParseState::InCommand),

            // can go to option from: start, command, after accepting value, or another option
            ParseState::InOption => matches!(
                self,
                ParseState::Start
                    | ParseState::InCommand
                    | ParseState::InArgument
                    | ParseState::InOption
                    | ParseState::AcceptingValue(_, _)
            ),

            // can only go to accepting value from option
            ParseState::AcceptingValue(_, _) => matches!(self, ParseState::InOption),

            // can go to argument from: start, command, breaking, or another argument
            ParseState::InArgument => matches!(
                self,
                ParseState::Start
                    | ParseState::InCommand
                    | ParseState::Breaking
                    | ParseState::InArgument
            ),

            // can go to breaking from: option or accepting value
            ParseState::Breaking => matches!(
                self,
                ParseState::InOption | ParseState::AcceptingValue(_, _)
            ),

            // can go to end from any state except Start
            ParseState::End => !matches!(self, ParseState::Start),
        }
    }
}