alux_cli/algebra.rs
1use crate::Conventions;
2use alux_ext::ext;
3
4/// Describes construction and composition of command collections.
5///
6/// Merge keeps declaration order and repetitions; which repetition wins is the interpreter's policy.
7pub trait CliCommandsAlg {
8 /// The interpreter's homogeneous command collection.
9 type Commands;
10
11 /// Returns the empty command collection.
12 fn cli_empty(&self) -> Self::Commands;
13
14 /// Combines two command collections, `left` first.
15 fn cli_merge(&self, left: Self::Commands, right: Self::Commands) -> Self::Commands;
16}
17
18/// Compiles one command: a first-order operation under a name, with a source for each argument.
19///
20/// `Operation` is the reified extension method, so an interpreter reads its documentation and
21/// argument names from `alux_ext::OperationAlg` and applies it through `alux_ext::ApplyAlg`.
22/// `Inputs` is the ordered product of argument sources the declaration states, one per argument.
23/// `Mode` is `Total` or `Fallible`, and reads the operation's output as the command's outcome
24/// through `CliOutcomeOf`.
25pub trait CliOperationAlg<Operation, Inputs, Mode> {
26 /// The command collection one command compiles to.
27 type Commands;
28
29 /// Registers `operation` under `name`, decoded through `inputs` from words read under
30 /// `conventions`, its output read under `mode`.
31 fn cli_operation(
32 &self,
33 name: &'static str,
34 operation: Operation,
35 inputs: Inputs,
36 mode: Mode,
37 conventions: Conventions,
38 ) -> Self::Commands;
39}
40
41/// Compiles a command collection beneath one subcommand name.
42pub trait CliNestAlg {
43 /// The command collection being nested.
44 type Commands;
45
46 /// Places `commands` beneath `name`.
47 fn cli_nest(&self, name: &'static str, commands: Self::Commands) -> Self::Commands;
48
49 /// Compiles a subtree with `compile` and places it beneath `name`.
50 ///
51 /// An interpreter that needs only the commands beneath some names compiles no other subtree.
52 fn cli_nest_with(&self, name: &'static str, compile: impl FnOnce(&Self) -> Self::Commands) -> Self::Commands
53 where
54 Self: Sized,
55 {
56 self.cli_nest(name, compile(self))
57 }
58}
59
60/// Compiles a subtree whose commands are applied to the context an operation answers.
61///
62/// `Operation` answers the context under `Mode`, from the arguments `Inputs` reads; those are the
63/// subtree's global arguments. The subtree compiles with `Inner`, the interpreter for commands
64/// applied to that context, so a context can be another type than the one around it.
65pub trait CliContextAlg<Operation, Inputs, Mode> {
66 /// The interpreter compiling the subtree.
67 type Inner;
68 /// The command collection the subtree compiles to.
69 type InnerCommands;
70 /// The command collection this compiles the subtree into.
71 type Commands;
72
73 /// Returns the interpreter compiling the subtree.
74 fn cli_inner(&self) -> Self::Inner;
75
76 /// Applies the subtree's `commands` to the context `operation` answers from `inputs`.
77 fn cli_within(
78 &self,
79 operation: Operation,
80 inputs: Inputs,
81 mode: Mode,
82 commands: Self::InnerCommands,
83 ) -> Self::Commands;
84}
85
86/// Interprets a named, defunctionalized CLI program with `Compiler`.
87pub trait CliProgramAlg<Compiler> {
88 /// The command collection produced by `Compiler`.
89 type Commands;
90
91 /// Compiles the program through the supplied interpreter.
92 fn compile_cli(self, compiler: &Compiler) -> Self::Commands;
93}
94
95/// Compiles defunctionalized CLI programs with an interpreter.
96#[ext(name = CliProgramExt)]
97pub impl<This> This {
98 /// Compiles a named CLI program with this interpreter.
99 fn compile_cli<Program>(&self, program: Program) -> Program::Commands
100 where
101 Program: CliProgramAlg<This>,
102 {
103 program.compile_cli(self)
104 }
105}