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}