Skip to main content

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}