alux-cli
alux-cli describes typed command-line programs independently of an argument parser.
The crate is a specification. It carries no interpreter and depends only on alux-ext and alux-shape, whose products and sums its arguments share with HTTP and JSON-RPC: a command surface is described here as first-order syntax plus the capability algebras an interpreter must witness. It names no parser, process, or OS string type. Domain specifications provide their own capability traits and compose defunctionalized operations.
A CLI program is the same projection as an alux-jsonrpc method program. Commands form an ordered collection under merge, each command names a reified alux_ext operation, and named programs nest. The CLI adds two things of its own: a source for each argument of the operation, and nesting a program beneath a subcommand name.
use ;
use ext;
/// A downstream specification owns its primitive domain meaning.
/// Derived operations become first-order values that preserve their argument names.
/// The command program is declared before any parser is chosen.
A program declared in another extension block, or another crate, composes the same way. Whatever merge, nest, or within takes as its program is one, so self.cat_commands::<Machine>() there names the program cat_commands declares.
A declaration can bind its parts with let first and name them in the chain, let dev = self.named("Dev mode").switch(); self.commands().cmd_root(self.op(Machine::run).arg("dev", dev)), which reads as if each were written where it is named and keeps every line short enough for rustfmt.
Each command path must be unique. Repeat one in the same declaration and the program does not compile; repeat one across programs you combine with merge, nest, or within, and running the program reports it:
# use ;
# use ext;
#
#
#
Arguments
A command's arguments are its operation's arguments, and the declaration gives each one a source, in order. positional(doc) takes its words by position. named(doc) takes the words after --argument-name, respelled with .long(..) and .short(..). A source supplies one value; .optional() makes it supply Option of one, .many() a Vec of any number, and .switch() a bool given by its spelling alone. The declared shape must be the argument's type, or the program does not compile, and the value inside is any type: reading it from a word is the interpreter's. When the command line gives an argument no words, .env("VAR") reads the environment variable next and .default("word") uses a word last. .short_aliases(&['R']) adds short spellings that mean the same, .optional_value() supplies Option<Option<_>> for a value written only in the option's own word (-i or -i.bak), .many().delimiter(',') splits each word into values, and .assigned("if") spells the argument as the operand if=VALUE instead of an option, taking no positional place. A command states how its words are read with .options_first(), .unknown_options_as_operands(), .no_end_of_options(), .verbatim(), and .numeric_option("lines"), which reads -5 as --lines 5.
use ;
use ext;
A source that cannot supply its argument does not compile once the program is: a missing or extra source, a source of the wrong shape for its argument (.many() for a String), and a switch with a .default(..). A switch is turned on by its spelling, --pinned, and its long spelling may state a truth either way, --pinned=false or --pinned=OFF, so the command line can turn off what the environment turned on. It may fall back to .env(..) only, and a variable set to nothing leaves it off. A truth is true/false, t/f, yes/no, y/n, on/off, or 1/0, in any case. An alternative of a sum is chosen by its spelling alone and takes no value.
Each .arg("name", source) names the argument it declares. The names are checked against the operation's own, in order, when the program compiles, so two arguments of one type cannot be swapped unnoticed:
# use ;
# use ext;
#
#
#
# ;
#
#
# ;
#
# Count.compile_cli;
Products and sums
An argument can be made of several named sources. A product supplies a value whose fields are given together: the type states its fields once as an alux-shape Product, which #[derive(Shape)] states with its shape, and the declaration gives each field a named source with .field(..). With .optional() it supplies Option of the product instead: all of its fields or none of them, so a field given without the others is missing. A sum supplies a value given as exactly one of its alternatives: the type states them as an alux-shape Sum of two to sixteen alternatives, which #[derive(Shape)] states with its shape, the declaration gives each a named source with .or(..), an alternative carrying no value is () and given by its spelling alone, and two alternatives given together conflict. With .optional() it supplies Option of the sum instead: one alternative or none.
use ;
use ext;
use Shape;
/// Where an export goes: to a location, or to the standard output.
/// Who an export is made as.
Each .field("name", source) and .or("name", source) names the field or alternative it declares, and the names are checked against the type's own, in order, when the program compiles: a product's fields as written, a sum's variants in snake case.
# use ;
# use ext;
# use Shape;
#
#
#
#
#
# ;
#
#
# ;
#
# Count.compile_cli;
Fields and alternatives are named, because positions belong to the command:
# use ;
# use ext;
#
#
#
#
#
Contexts
within(operation, program) applies every command of program to the value operation answers: a store it opens, a configuration it reads. The operation's arguments are the subtree's global arguments, which every command beneath it takes besides its own, and .fallible() lets opening the context fail. The subtree compiles with the interpreter CliContextAlg hands over for that value, so a context can be another type than the one around it. Global arguments are named, because positions belong to each command:
# use ;
# use ext;
#
#
#
The subtree is a program declared by a method of its own, because the context's interpreter compiles it and its bound names its type. An inline subtree is rejected where it is written:
# use ;
# use ext;
#
#
#
Syntax
CliProgramBuilder constructs the same first-order program directly: Empty, Merge, Named, Nest, and Command, whose Operation carries its handler and the product of its argument sources. defunc(via = cli) lowers the fluent declaration to that syntax. A handler written as op(Machine::method) becomes the operation ext(defunc) generated for the method, and the command becomes one CliOperationAlg bound on the interpreter.
Interpretation
CliCommandsAlg interprets the empty collection and ordered merge. CliOperationAlg<Operation, Sources, Mode> interprets one command. A describing interpreter reads OperationAlg and CliSources::cli_arguments. An executing interpreter answers two things: CliWordsAlg, the words the command line gives for an argument and the environment, and CliWordAlg<Value>, how one word decodes as a value. CliDecodeSources then takes each argument's words from the command line, its environment variable, or its default, and assembles the operation's arguments by their arities, and the interpreter applies the operation through ApplyAlg. CliNestAlg interprets nesting, and only a program that nests asks for it. An interpreter missing a binding cannot compile the program.
Outcome
A command succeeds with its operation's output and exits with status zero. .fallible() reads an output that is a Result instead: Ok succeeds, and Err fails with status 1. The error can be any error that displays, anyhow::Error among them, so an operation can use ?, bail!, and ensure! directly. .fallible_as(status) fails with another status. .fallible_by_error() fails with the status its error states through CliFailureAlg, nonzero by its type, which can differ from one error to another and can say the failure was already reported, as cat reports each missing file as it reads on. CliOutcomeOf reads an output under the declared mode, Total, Fallible, or FallibleByError, as a CliOutcome, so an interpreter that applies a fallible command whose operation does not answer a Result fails to compile. Words that do not make the command exit with USAGE_STATUS before anything applies.
From 0.2: .fallible() now fails with status 1 whatever its error states. A command whose error implements CliFailureAlg keeps its own statuses with .fallible_by_error().
How a value or a failure is rendered, and on which stream, belongs to the interpreter, as do splitting words, diagnostics, and help. alux-cli-direct is the interpretation that runs a program as a command line with no parser framework.
Laws
CliCompositionLawsExt states that merge has the empty collection as identity, is associative, and conserves declarations in order. CliDeclarationLawsExt states that a command keeps its operation's documentation, gives each of its arguments one source in order, and reads no two arguments from the same source. CliNestLawsExt states that nesting prefixes every path and changes nothing else. CliContextLawsExt states that a context adds its global arguments to every command beneath it and changes nothing else. CliOutcomeLawsExt states that a command exits with zero exactly when it succeeds. An interpreter states what it observes through CliCommandsObserved.
Coming from clap
Coming from clap shows each clap concept beside its alux-cli form, and how an application moves over one command at a time.