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`.
117    ///
118    /// `defunc(via = cli)` checks the name against the operation's own when the program compiles,
119    /// reporting a source written for another argument where it is written.
120    pub fn arg_for<Source>(self, name: &'static str, source: Source) -> Operation<Handler, (Inputs, Source), Mode> {
121        let _: &'static str = name;
122        self.arg(source)
123    }
124
125    /// Declares the source of the operation's next argument, after those already declared.
126    pub fn arg<Source>(self, source: Source) -> Operation<Handler, (Inputs, Source), Mode> {
127        Operation {
128            handler: self.handler,
129            inputs: (self.inputs, source),
130            mode: self.mode,
131            conventions: self.conventions,
132        }
133    }
134
135    /// Declares this operation under one command name, with no program around it.
136    ///
137    /// A program that states many commands composes their registrations rather than their types,
138    /// so it needs each command on its own. `CliProgram::command` states the same thing inside a
139    /// composition, and is what an author writes.
140    pub fn declare(self, name: &'static str) -> Command<Handler, Inputs, Mode> {
141        Command { name, handler: self.handler, inputs: self.inputs, mode: self.mode, conventions: self.conventions }
142    }
143}
144
145impl<Handler, Inputs, Mode> Operation<Handler, Inputs, Mode> {
146    /// Ends the command's options at its first operand.
147    #[must_use]
148    pub fn options_first(mut self) -> Self {
149        self.conventions.options_first = true;
150        self
151    }
152
153    /// Reads a word naming no option of the command as an operand.
154    #[must_use]
155    pub fn unknown_options_as_operands(mut self) -> Self {
156        self.conventions.unknown_options_are_operands = true;
157        self
158    }
159
160    /// Reads `--` as an operand rather than the end of the options.
161    #[must_use]
162    pub fn no_end_of_options(mut self) -> Self {
163        self.conventions.double_dash_ends_options = false;
164        self
165    }
166
167    /// Reads a word of a dash and digits as the option spelled `--long` given those digits, as
168    /// `head -5` is `head -n 5`.
169    #[must_use]
170    pub fn numeric_option(mut self, long: &'static str) -> Self {
171        self.conventions.numeric_option = Some(long);
172        self
173    }
174
175    /// Reads every word as an operand, ignores operands beyond the command's own, and answers no
176    /// help.
177    #[must_use]
178    pub fn verbatim(mut self) -> Self {
179        self.conventions.verbatim = true;
180        self
181    }
182
183    /// Applies every command of `program` to the context this operation answers, with no program
184    /// around it.
185    pub fn within<Program>(self, program: CliProgram<Program>) -> Within<Handler, Inputs, Mode, Program> {
186        Within { handler: self.handler, inputs: self.inputs, mode: self.mode, program: program.0 }
187    }
188}
189
190impl<Handler, Inputs> Operation<Handler, Inputs, Total> {
191    /// Reads the operation's `Result` output as success or a failure with the error's own status.
192    pub fn fallible(self) -> Operation<Handler, Inputs, Fallible> {
193        Operation { handler: self.handler, inputs: self.inputs, mode: Fallible, conventions: self.conventions }
194    }
195}
196
197impl<Program> CliProgram<Program> {
198    /// Records the composition of two typed CLI programs.
199    pub fn merge<Other>(self, other: CliProgram<Other>) -> CliProgram<Merge<Program, Other>> {
200        CliProgram(Merge { left: self.0, right: other.0 })
201    }
202
203    /// Registers a typed operation under a command name.
204    pub fn command<Handler, Inputs, Mode>(
205        self,
206        name: &'static str,
207        operation: Operation<Handler, Inputs, Mode>,
208    ) -> CliProgram<Merge<Program, Command<Handler, Inputs, Mode>>> {
209        self.merge(CliProgram(operation.declare(name)))
210    }
211
212    /// Declares the program's own command: the one a command line naming no command runs.
213    ///
214    /// It sits beside named commands, which a command line naming one selects first.
215    pub fn cmd<Handler, Inputs, Mode>(
216        self,
217        operation: Operation<Handler, Inputs, Mode>,
218    ) -> CliProgram<Merge<Program, Command<Handler, Inputs, Mode>>> {
219        self.merge(CliProgram(operation.declare("")))
220    }
221
222    /// Places `other` beneath the subcommand `name`.
223    pub fn nest<Other>(self, name: &'static str, other: CliProgram<Other>) -> CliProgram<Merge<Program, Nest<Other>>> {
224        self.merge(CliProgram(other.under(name)))
225    }
226
227    /// Applies every command of `other` to the context `operation` answers.
228    pub fn within<Handler, Inputs, Mode, Other>(
229        self,
230        operation: Operation<Handler, Inputs, Mode>,
231        other: CliProgram<Other>,
232    ) -> CliProgram<Merge<Program, Within<Handler, Inputs, Mode, Other>>> {
233        self.merge(CliProgram(operation.within(other)))
234    }
235
236    /// Places this program beneath the subcommand `name`, with no program around it.
237    pub fn under(self, name: &'static str) -> Nest<Program> {
238        Nest { name, program: self.0 }
239    }
240
241    /// Removes the fluent wrapper and returns the first-order syntax tree.
242    pub fn into_program(self) -> Program {
243        self.0
244    }
245}
246
247impl<Compiler> CompileCliProgram<Compiler> for Empty
248where
249    Compiler: CliCommandsAlg,
250{
251    type Commands = Compiler::Commands;
252
253    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
254        compiler.cli_empty()
255    }
256}
257
258impl<Compiler, Left, Right, Commands> CompileCliProgram<Compiler> for Merge<Left, Right>
259where
260    Compiler: CliCommandsAlg<Commands = Commands>,
261    Left: CompileCliProgram<Compiler, Commands = Commands>,
262    Right: CompileCliProgram<Compiler, Commands = Commands>,
263{
264    type Commands = Commands;
265
266    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
267        compiler.cli_merge(self.left.compile_cli_program(compiler), self.right.compile_cli_program(compiler))
268    }
269}
270
271impl<Compiler, Program> CompileCliProgram<Compiler> for Named<Program>
272where
273    Program: CliProgramAlg<Compiler>,
274{
275    type Commands = Program::Commands;
276
277    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
278        self.0.compile_cli(compiler)
279    }
280}
281
282impl<Compiler, Program, Commands> CompileCliProgram<Compiler> for Nest<Program>
283where
284    Compiler: CliNestAlg<Commands = Commands>,
285    Program: CompileCliProgram<Compiler, Commands = Commands>,
286{
287    type Commands = Commands;
288
289    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
290        let program = self.program;
291        compiler.cli_nest_with(self.name, |compiler| program.compile_cli_program(compiler))
292    }
293}
294
295impl<Compiler, Handler, Inputs, Mode> CompileCliProgram<Compiler> for Command<Handler, Inputs, Mode>
296where
297    Compiler: CliOperationAlg<Handler, Inputs, Mode>,
298    Handler: OperationAlg,
299    Inputs: CliSources<Handler::Args>,
300{
301    type Commands = Compiler::Commands;
302
303    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
304        compiler.cli_operation(self.name, self.handler, self.inputs, self.mode, self.conventions)
305    }
306}
307
308impl<Compiler, Handler, Inputs, Mode, Program, Inner, InnerCommands> CompileCliProgram<Compiler>
309    for Within<Handler, Inputs, Mode, Program>
310where
311    Compiler: CliContextAlg<Handler, Inputs, Mode, Inner = Inner, InnerCommands = InnerCommands>,
312    Handler: OperationAlg,
313    Inputs: CliSources<Handler::Args> + CliNamedSources,
314    Program: CompileCliProgram<Inner, Commands = InnerCommands>,
315{
316    type Commands = Compiler::Commands;
317
318    fn compile_cli_program(self, compiler: &Compiler) -> Self::Commands {
319        let inner = self.program.compile_cli_program(&compiler.cli_inner());
320        compiler.cli_within(self.handler, self.inputs, self.mode, inner)
321    }
322}