Skip to main content

alux_cli/
program.rs

1use crate::{
2    CliCommandsAlg, CliContextAlg, CliNamedSources, CliNestAlg, CliOperationAlg, CliProgramAlg, CliSources,
3    Conventions, Fallible, NamedSource, PositionalSource, ProductSource, SumSource, Total,
4};
5use alux_ext::OperationAlg;
6
7/// Compiles a first-order CLI program with a concrete interpreter.
8pub trait CompileCliProgram<Compiler> {
9    /// The command collection produced by `Compiler`.
10    type Commands;
11
12    /// Folds the complete first-order program through `compiler`.
13    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands;
14}
15
16/// Represents the empty CLI program.
17#[derive(Debug, Default)]
18pub struct Empty;
19
20/// Represents the composition of two CLI programs, `left` first.
21#[derive(Debug)]
22pub struct Merge<Left, Right> {
23    left: Left,
24    right: Right,
25}
26
27/// Includes a separately named CLI program.
28#[derive(Debug)]
29pub struct Named<Program>(Program);
30
31/// Places a CLI program beneath one subcommand name.
32#[derive(Debug)]
33pub struct Nest<Program> {
34    name: &'static str,
35    program: Program,
36}
37
38/// Applies every command of a program to the context an operation answers.
39///
40/// The operation's arguments are the subtree's global arguments: every command of `program` takes
41/// them besides its own.
42#[derive(Debug)]
43pub struct Within<Handler, Inputs, Mode, Program> {
44    handler: Handler,
45    inputs: Inputs,
46    mode: Mode,
47    program: Program,
48}
49
50/// Represents one named command without choosing an interpreter.
51#[derive(Debug)]
52pub struct Command<Handler, Inputs, Mode = Total> {
53    name: &'static str,
54    handler: Handler,
55    inputs: Inputs,
56    mode: Mode,
57    conventions: Conventions,
58}
59
60/// Carries a typed operation, the sources of its arguments (one per argument, in order), and how
61/// its output is read as the command's outcome.
62#[derive(Debug)]
63pub struct Operation<Handler, Inputs = (), Mode = Total> {
64    handler: Handler,
65    inputs: Inputs,
66    mode: Mode,
67    conventions: Conventions,
68}
69
70/// Carries a typed CLI program during fluent composition.
71#[derive(Debug)]
72pub struct CliProgram<Program>(Program);
73
74/// Constructs neutral CLI programs.
75#[derive(Debug, Default)]
76pub struct CliProgramBuilder;
77
78impl CliProgramBuilder {
79    /// Starts an empty, uninterpreted CLI program.
80    pub fn commands(&self) -> CliProgram<Empty> {
81        CliProgram(Empty)
82    }
83
84    /// Wraps a first-order handler operation in a neutral declaration with no arguments.
85    pub fn op<Handler>(&self, handler: Handler) -> Operation<Handler> {
86        Operation { handler, inputs: (), mode: Total, conventions: Conventions::default() }
87    }
88
89    /// Includes a named CLI program in another program.
90    pub fn program<Program>(&self, program: Program) -> CliProgram<Named<Program>> {
91        CliProgram(Named(program))
92    }
93
94    /// Declares a source taking an argument's words by position.
95    pub fn positional(&self, doc: &'static str) -> PositionalSource {
96        PositionalSource::new(doc)
97    }
98
99    /// Declares a product: an argument made of fields given together, one named source each.
100    pub fn product(&self) -> ProductSource<()> {
101        ProductSource::new()
102    }
103
104    /// Declares a sum: an argument given as exactly one of its alternatives, one named source each.
105    pub fn sum(&self) -> SumSource<()> {
106        SumSource::new()
107    }
108
109    /// Declares a source taking an argument's words after its spelling, `--argument-name`.
110    pub fn named(&self, doc: &'static str) -> NamedSource {
111        NamedSource::new(doc)
112    }
113}
114
115impl<Handler, Inputs, Mode> Operation<Handler, Inputs, Mode> {
116    /// Declares the source of the operation's next argument, the one named `name`, after those
117    /// already declared.
118    ///
119    /// `defunc(via = cli)` checks the name against the operation's own when the program compiles,
120    /// reporting a source written for another argument where it is written.
121    pub fn arg<Source>(self, name: &'static str, source: Source) -> Operation<Handler, (Inputs, Source), Mode> {
122        let _: &'static str = name;
123        Operation {
124            handler: self.handler,
125            inputs: (self.inputs, source),
126            mode: self.mode,
127            conventions: self.conventions,
128        }
129    }
130
131    /// Declares this operation under one command name, with no program around it.
132    ///
133    /// A program that states many commands composes their registrations rather than their types,
134    /// so it needs each command on its own. `CliProgram::cmd` states the same thing inside a
135    /// composition, and is what an author writes.
136    pub fn declare(self, name: &'static str) -> Command<Handler, Inputs, Mode> {
137        Command { name, handler: self.handler, inputs: self.inputs, mode: self.mode, conventions: self.conventions }
138    }
139}
140
141impl<Handler, Inputs, Mode> Operation<Handler, Inputs, Mode> {
142    /// Ends the command's options at its first operand.
143    #[must_use]
144    pub fn options_first(mut self) -> Self {
145        self.conventions.options_first = true;
146        self
147    }
148
149    /// Reads a word naming no option of the command as an operand.
150    #[must_use]
151    pub fn unknown_options_as_operands(mut self) -> Self {
152        self.conventions.unknown_options_are_operands = true;
153        self
154    }
155
156    /// Reads `--` as an operand rather than the end of the options.
157    #[must_use]
158    pub fn no_end_of_options(mut self) -> Self {
159        self.conventions.double_dash_ends_options = false;
160        self
161    }
162
163    /// Reads a word of a dash and digits as the option spelled `--long` given those digits, as
164    /// `head -5` is `head -n 5`.
165    #[must_use]
166    pub fn numeric_option(mut self, long: &'static str) -> Self {
167        self.conventions.numeric_option = Some(long);
168        self
169    }
170
171    /// Reads every word as an operand, ignores operands beyond the command's own, and answers no
172    /// help.
173    #[must_use]
174    pub fn verbatim(mut self) -> Self {
175        self.conventions.verbatim = true;
176        self
177    }
178
179    /// Applies every command of `program` to the context this operation answers, with no program
180    /// around it.
181    pub fn within<Program>(self, program: CliProgram<Program>) -> Within<Handler, Inputs, Mode, Program> {
182        Within { handler: self.handler, inputs: self.inputs, mode: self.mode, program: program.0 }
183    }
184}
185
186impl<Handler, Inputs> Operation<Handler, Inputs, Total> {
187    /// Reads the operation's `Result` output as success or a failure with the error's own status.
188    pub fn fallible(self) -> Operation<Handler, Inputs, Fallible> {
189        Operation { handler: self.handler, inputs: self.inputs, mode: Fallible, conventions: self.conventions }
190    }
191}
192
193impl<Program> CliProgram<Program> {
194    /// Records the composition of two typed CLI programs.
195    pub fn merge<Other>(self, other: CliProgram<Other>) -> CliProgram<Merge<Program, Other>> {
196        CliProgram(Merge { left: self.0, right: other.0 })
197    }
198
199    /// Registers a typed operation under a command name.
200    pub fn cmd<Handler, Inputs, Mode>(
201        self,
202        name: &'static str,
203        operation: Operation<Handler, Inputs, Mode>,
204    ) -> CliProgram<Merge<Program, Command<Handler, Inputs, Mode>>> {
205        self.merge(CliProgram(operation.declare(name)))
206    }
207
208    /// Declares the program's own command: the one a command line naming no command runs.
209    ///
210    /// It sits beside named commands, which a command line naming one selects first.
211    pub fn cmd_root<Handler, Inputs, Mode>(
212        self,
213        operation: Operation<Handler, Inputs, Mode>,
214    ) -> CliProgram<Merge<Program, Command<Handler, Inputs, Mode>>> {
215        self.merge(CliProgram(operation.declare("")))
216    }
217
218    /// Places `other` beneath the subcommand `name`.
219    pub fn nest<Other>(self, name: &'static str, other: CliProgram<Other>) -> CliProgram<Merge<Program, Nest<Other>>> {
220        self.merge(CliProgram(other.under(name)))
221    }
222
223    /// Applies every command of `other` to the context `operation` answers.
224    pub fn within<Handler, Inputs, Mode, Other>(
225        self,
226        operation: Operation<Handler, Inputs, Mode>,
227        other: CliProgram<Other>,
228    ) -> CliProgram<Merge<Program, Within<Handler, Inputs, Mode, Other>>> {
229        self.merge(CliProgram(operation.within(other)))
230    }
231
232    /// Places this program beneath the subcommand `name`, with no program around it.
233    pub fn under(self, name: &'static str) -> Nest<Program> {
234        Nest { name, program: self.0 }
235    }
236
237    /// Removes the fluent wrapper and returns the first-order syntax tree.
238    pub fn into_program(self) -> Program {
239        self.0
240    }
241}
242
243impl<Compiler> CompileCliProgram<Compiler> for Empty
244where
245    Compiler: CliCommandsAlg,
246{
247    type Commands = Compiler::Commands;
248
249    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
250        compiler.cli_empty()
251    }
252}
253
254impl<Compiler, Left, Right, Commands> CompileCliProgram<Compiler> for Merge<Left, Right>
255where
256    Compiler: CliCommandsAlg<Commands = Commands>,
257    Left: CompileCliProgram<Compiler, Commands = Commands>,
258    Right: CompileCliProgram<Compiler, Commands = Commands>,
259{
260    type Commands = Commands;
261
262    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
263        compiler.cli_merge(self.left.compile_cli_program(compiler), self.right.compile_cli_program(compiler))
264    }
265}
266
267impl<Compiler, Program> CompileCliProgram<Compiler> for Named<Program>
268where
269    Program: CliProgramAlg<Compiler>,
270{
271    type Commands = Program::Commands;
272
273    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
274        self.0.compile_cli(compiler)
275    }
276}
277
278impl<Compiler, Program, Commands> CompileCliProgram<Compiler> for Nest<Program>
279where
280    Compiler: CliNestAlg<Commands = Commands>,
281    Program: CompileCliProgram<Compiler, Commands = Commands>,
282{
283    type Commands = Commands;
284
285    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
286        let program = self.program;
287        compiler.cli_nest_with(self.name, |compiler| program.compile_cli_program(compiler))
288    }
289}
290
291impl<Compiler, Handler, Inputs, Mode> CompileCliProgram<Compiler> for Command<Handler, Inputs, Mode>
292where
293    Compiler: CliOperationAlg<Handler, Inputs, Mode>,
294    Handler: OperationAlg,
295    Inputs: CliSources<Handler::Args>,
296{
297    type Commands = Compiler::Commands;
298
299    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
300        compiler.cli_operation(self.name, self.handler, self.inputs, self.mode, self.conventions)
301    }
302}
303
304impl<Compiler, Handler, Inputs, Mode, Program, Inner, InnerCommands> CompileCliProgram<Compiler>
305    for Within<Handler, Inputs, Mode, Program>
306where
307    Compiler: CliContextAlg<Handler, Inputs, Mode, Inner = Inner, InnerCommands = InnerCommands>,
308    Handler: OperationAlg,
309    Inputs: CliSources<Handler::Args> + CliNamedSources,
310    Program: CompileCliProgram<Inner, Commands = InnerCommands>,
311{
312    type Commands = Compiler::Commands;
313
314    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
315        let inner = self.program.compile_cli_program(&compiler.cli_inner());
316        compiler.cli_within(self.handler, self.inputs, self.mode, inner)
317    }
318}