Skip to main content

alux_cli/
description.rs

1use crate::{ArgumentInfo, CliSources};
2use alux_ext::OperationAlg;
3
4/// Describes one command as a describing interpretation observes it.
5///
6/// Its path comes from the program, its documentation and argument names from the reified
7/// operation, and its arguments from the declared sources.
8#[derive(Clone, Debug, PartialEq, Eq)]
9pub struct CommandDescription {
10    /// The subcommand names leading to the command, ending with its own name.
11    pub path: Vec<&'static str>,
12    /// The documentation of the extension method the command applies.
13    pub doc: &'static str,
14    /// The argument names of the extension method, in order.
15    pub argument_names: &'static [&'static str],
16    /// Every argument with the source it is read from, in the operation's order.
17    pub arguments: Vec<ArgumentInfo>,
18    /// The global arguments of every context the command is applied within, outermost first.
19    pub context: Vec<ArgumentInfo>,
20    /// How the command's words are read as its options and operands.
21    pub conventions: Conventions,
22}
23
24/// States how one command's words are read as its options and operands.
25///
26/// The default reads options anywhere among the operands, rejects an option no argument is
27/// spelled as, ends options at `--`, and answers `--help` and `-h` with help. POSIX utilities
28/// differ per command, and a declaration states where one does.
29#[derive(Clone, Copy, Debug, PartialEq, Eq)]
30#[allow(clippy::struct_excessive_bools)]
31pub struct Conventions {
32    /// Options end at the first operand: `echo hello -n` has two operands.
33    pub options_first: bool,
34    /// A word naming an option no argument is spelled as is an operand, as is a cluster with one
35    /// such letter: `echo -x` writes `-x`.
36    pub unknown_options_are_operands: bool,
37    /// `--` ends the options. Where it does not, it is an operand like any other word.
38    pub double_dash_ends_options: bool,
39    /// Every word is an operand, operands beyond the command's own are ignored, and help is not
40    /// answered: `true --help` exits 0.
41    pub verbatim: bool,
42    /// The long spelling of the option a word of a dash and digits gives its digits to: `head -5`
43    /// is `head --lines 5`.
44    pub numeric_option: Option<&'static str>,
45}
46
47impl Default for Conventions {
48    fn default() -> Self {
49        Self {
50            options_first: false,
51            unknown_options_are_operands: false,
52            double_dash_ends_options: true,
53            verbatim: false,
54            numeric_option: None,
55        }
56    }
57}
58
59impl CommandDescription {
60    /// Describes `Operation` declared under `name`, its arguments read from `sources`.
61    pub fn of<Operation, Sources>(name: &'static str, sources: &Sources) -> Self
62    where
63        Operation: OperationAlg,
64        Sources: CliSources<Operation::Args>,
65    {
66        Self {
67            // The program's own command, declared with no name, is reached by no word at all.
68            path: if name.is_empty() { Vec::new() } else { vec![name] },
69            doc: Operation::DOC,
70            argument_names: Operation::ARG_NAMES,
71            arguments: sources.cli_arguments(Operation::ARG_NAMES),
72            context: Vec::new(),
73            conventions: Conventions::default(),
74        }
75    }
76}