Expand description
§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 alux_cli::{CliCommandsAlg, cli};
use alux_ext::ext;
/// A downstream specification owns its primitive domain meaning.
trait Reading {
type Name;
type Value;
fn read(&self, name: &Self::Name) -> Self::Value;
}
/// Derived operations become first-order values that preserve their argument names.
#[ext(name = ReadingExt, defunc)]
impl<This, Name, Value> This
where
This: Reading<Name = Name, Value = Value>,
{
/// Reads the value denoted by the requested name.
fn lookup(&self, name: Name) -> Value {
self.read(&name)
}
}
/// The command program is declared before any parser is chosen.
#[ext(name = ReadingCliExt, defunc(via = cli))]
impl<This> This
where
This: CliCommandsAlg,
{
/// Declares the reading commands.
fn reading_cli<Machine, Name>(&self) {
// An empty program, with one command added.
self.commands().command(
// `lookup` applies the operation `defunc` made from `lookup` above, and its
// documentation is the command's help.
"lookup",
// `name: Name`, once: the first positional word.
self.op(Machine::lookup).arg(self.positional("Requested name")),
)
}
/// Declares the application: the reading commands, and the same beneath `admin`.
fn app_cli<Machine, Name>(&self) {
self.commands()
// `lookup`, from the program above.
.merge(self.reading_cli::<Machine, Name>())
// `admin lookup`: the same program, each path prefixed with `admin`.
.nest("admin", self.reading_cli::<Machine, Name>())
}
}
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(self.op(Machine::run).arg(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:
#[ext(name = LinesCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn lines_cli<Machine>(&self) {
// error: the command `head` is declared more than once
self.commands().command("head", self.op(Machine::head)).command("head", self.op(Machine::tail))
}
}§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 alux_cli::{CliCommandsAlg, cli};
use alux_ext::ext;
trait Notes {
type Text;
type Tag;
type Store;
}
#[ext(name = NotesExt, defunc)]
impl<This, Text, Tag, Store> This
where
This: Notes<Text = Text, Tag = Tag, Store = Store>,
{
/// Adds a note.
fn add_note(&self, store: Store, text: Text, tags: Vec<Tag>, pinned: bool) {
todo!()
}
/// Lists notes, newest first.
fn list_notes(&self, store: Store, tag: Option<Tag>, limit: usize) -> Vec<Text> {
todo!()
}
}
#[ext(name = NotesCliExt, defunc(via = cli))]
impl<This> This
where
This: CliCommandsAlg,
{
/// Declares the notes commands.
fn notes_cli<Machine>(&self) {
self.commands()
.command(
"add",
self.op(Machine::add_note)
// `store: Store`, once: `--store <store>` or `-s <store>`, else `$NOTES_STORE`, else `notes`.
.arg(self.named("Store to write to").short('s').env("NOTES_STORE").default("notes"))
// `text: Text`, once: the first positional word.
.arg(self.positional("Text of the note"))
// `tags: Vec<Tag>`, any number of times: `--tag <tag>` or `-t <tag>`.
.arg(self.named("Tag the note carries").many().long("tag").short('t'))
// `pinned: bool`, a switch: true when `--pinned` or `-p` is given.
.arg(self.named("Pin the note").switch().short('p')),
)
.command(
"list",
self.op(Machine::list_notes)
// `store: Store`, the same source as in `add`.
.arg(self.named("Store to read from").short('s').env("NOTES_STORE").default("notes"))
// `tag: Option<Tag>`, at most once: the first positional word, if there is one.
.arg(self.positional("Only notes with this tag").optional())
// `limit: usize`, once: `--limit <limit>` or `-n <limit>`, else `10`.
.arg(self.named("How many notes").short('n').default("10")),
)
}
}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 and may fall back to .env(..) only.
.arg_for("name", source) declares the same source for the argument it names. 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:
#[ext(name = RemoteCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn remote_cli<Machine>(&self) {
// error: argument 0 of `ConnectOperation<Machine>` is not `user`
self.commands().command(
"connect",
self.op(Machine::connect).arg_for("user", self.named("User")).arg_for("host", self.named("Host")),
)
}
}§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 alux_cli::{CliCommandsAlg, cli};
use alux_ext::ext;
use alux_shape::Shape;
/// Where an export goes: to a location, or to the standard output.
#[derive(Shape)]
enum Target<Location> {
At(Location),
Out,
}
/// Who an export is made as.
#[derive(Shape)]
struct Credentials<User, Secret> {
user: User,
secret: Secret,
}
trait Exporting {
type Location;
type User;
type Secret;
fn export(&self, target: Target<Self::Location>, credentials: Option<Credentials<Self::User, Self::Secret>>);
}
#[ext(name = ExportingExt, defunc)]
impl<This, Location, User, Secret> This
where
This: Exporting<Location = Location, User = User, Secret = Secret>,
{
/// Exports everything to a target, as someone or anonymously.
fn export_all(&self, target: Target<Location>, credentials: Option<Credentials<User, Secret>>) {
self.export(target, credentials)
}
}
#[ext(name = ExportingCliExt, defunc(via = cli))]
impl<This> This
where
This: CliCommandsAlg,
{
fn exporting_cli<Machine, Location, User, Secret>(&self) {
self.commands().command(
"export",
self.op(Machine::export_all)
.arg(self.sum().or(self.named("Export to a location").short('a')).or(self.named("Export to the standard output").switch()))
.arg(self.product().field(self.named("User to export as")).field(self.named("Secret of the user")).optional()),
)
}
}
Fields and alternatives are named, because positions belong to the command:
#[ext(name = PairingCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn pairing_cli<Machine, A, B>(&self) {
// error: a field takes a named source
self.commands().command("pair", self.op(Machine::paired).arg(self.product().field(self.positional("A")).field(self.named("B"))))
}
}§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 with its error’s status. 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:
#[ext(name = ShelfCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn shelf_cli<Machine>(&self) {
// error: a global argument is named
self.commands().within(self.op(Machine::opened).arg(self.positional("Store")), self.inner_cli::<Machine>())
}
fn inner_cli<Machine>(&self) {
self.commands().command("count", self.op(Machine::counted))
}
}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:
#[ext(name = InlineCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn inline_cli<Shelf>(&self) {
// error: `within` applies a named program
self.commands().within(self.op(Shelf::opened), self.commands().command("x", self.op(Shelf::opened)))
}
}§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 the status its error states through CliFailureAlg, nonzero by its type. CliOutcomeOf reads an output under the declared mode, Total or Fallible, 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.
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.
Structs§
- Argument
Info - Describes one argument of a command: the operation’s argument and the source it is read from.
- Assigned
- Marks a named source spelled as an operand assigning its value,
name=value, asdd if=FILE. - CliArg
Message - Holds the message a misnamed argument is reported with, written at compile time.
- CliProgram
- Carries a typed CLI program during fluent composition.
- CliProgram
Builder - Constructs neutral CLI programs.
- Command
- Represents one named command without choosing an interpreter.
- Command
Description - Describes one command as a describing interpretation observes it.
- Conventions
- States how one command’s words are read as its options and operands.
- Delimited
Source - Takes a list’s words after its spelling, each word split on a delimiter:
--peers a,bandPEERS=a,bboth give two values. - Empty
- Represents the empty CLI program.
- Fallback
- Names where an argument’s words come from when the command line gives none.
- Fallible
- Reads a
Resultoutput as success or failure: what.fallible()declares. - Many
- Marks a source supplying
Vecof values: any number, in the order given. - Merge
- Represents the composition of two CLI programs,
leftfirst. - Named
- Includes a separately named CLI program.
- Named
Source - Takes an argument’s words after its spelling,
--longor-s, or from an operandname=valueonce.assigned(name)spells it so. - Nest
- Places a CLI program beneath one subcommand name.
- NoFallback
- Marks a source whose argument comes only from the command line, with no fallback.
- Operation
- Carries a typed operation, the sources of its arguments (one per argument, in order), and how its output is read as the command’s outcome.
- Optional
- Marks a source supplying
Optionof a value: at most one. A product takes all of its fields or none of them, a sum one alternative or none. - Optional
Value - Marks a named source supplying
Option<Option<_>>: whether its spelling is given, and the value written in the same word, assed -i.bakgives one andsed -inone. - Options
- Marks a named source spelled as options:
--longor-s, with the value after it. - Positional
Source - Takes an argument’s words by position, in the order the positional arguments are declared.
- Product
Source - Declares the fields of a product, one named source each, in the order of the product’s fields.
- SumSource
- Declares the alternatives of a sum, one named source each, in the order of the sum’s.
- Switch
- Marks a named source supplying
bool: whether its spelling is given. It takes no value. - Total
- Reads every output as a success: the command’s default.
- Whole
- Marks a source supplying exactly one value, the operation’s argument itself.
- WithEnv
- Marks a source that falls back to an environment variable and nothing else.
- With
Fallback - Marks a source that falls back to a default word, after an environment variable if it has one.
- Within
- Applies every command of a program to the context an operation answers.
Enums§
- Arity
- States how many occurrences an argument takes, as its source’s shape says.
- CliArgument
Error - States why the words given for an argument do not make its value.
- CliOutcome
- States what a command answers: its value, or a failure that ends with a nonzero status.
- Part
- Names the compound argument a described argument is one part of.
- Source
Info - Describes where an argument’s words come from.
Constants§
- USAGE_
STATUS - Names the exit status of a command whose words did not make it: missing, repeated, or undecodable arguments. It follows the convention of POSIX utilities.
Traits§
- CliArg
At - Names the type of the argument at position
INDEXof an operation’s argument product. - CliCommands
Alg - Describes construction and composition of command collections.
- CliCommands
Observed - Observes a command collection as the commands it describes, in order.
- CliComposition
Laws Ext - States that command collections form an ordered monoid under merge.
- CliContext
Alg - Compiles a subtree whose commands are applied to the context an operation answers.
- CliContext
Laws Ext - States that a context adds its global arguments to every command beneath it and changes nothing else.
- CliDeclaration
Laws Ext - States that declaring a command preserves its operation and gives every argument one source.
- CliDecode
Sources - Decodes the operation arguments
Argsthrough declared sources, withDecoder. - CliFailure
Alg - States what a domain failure denotes on the command line: the status the command exits with.
- CliNamed
Source - Marks a source spelled by name, which is what a product’s field or a sum’s alternative takes.
- CliNamed
Sources - States that every source in a product is named.
- CliNest
Alg - Compiles a command collection beneath one subcommand name.
- CliNest
Laws Ext - States that nesting prefixes every path and changes nothing else.
- CliOperation
Alg - Compiles one command: a first-order operation under a name, with a source for each argument.
- CliOutcome
Laws Ext - States that a command’s outcome and its exit status agree.
- CliOutcome
Of - Reads an operation’s output as a command’s outcome under a declared mode.
- CliProgram
Alg - Interprets a named, defunctionalized CLI program with
Compiler. - CliProgram
Ext - Compiles defunctionalized CLI programs with an interpreter.
- CliShape
- States how many occurrences a source of one shape takes.
- CliSource
At - States that a source can supply the argument at position
INDEXof the argument productArgs. - CliSource
Decode - Decodes the argument a source supplies, with
Decoder. - CliSource
For - States that a source can supply an argument of type
Argument. - CliSources
- States that a declared product of sources supplies exactly the operation arguments
Args. - CliSpelling
- States how a named source is spelled on the command line.
- CliStated
For - States that a source can supply an argument as its method states it: a stated type is checked, one the context decides is left to the interpretation.
- CliWord
Alg - Decodes one word as a value; an interpreter answers it for the values it supports.
- CliWords
Alg - Answers the words given for one argument and the environment it falls back to.
- Compile
CliProgram - Compiles a first-order CLI program with a concrete interpreter.
- EnvFallback
- States the fallback mode a source takes once it also reads an environment variable.
Functions§
- cli_
arg_ mismatch - Answers why the argument at
positionofmethodis not namedname, or an empty message when it is, at compile time: “argument 0 ofstart_nodeisname, notfff”. - cli_
arg_ named - Says whether the argument at
positionamongnamesis namedname, at compile time. - cli_
source_ stated - Checks, at compile time, that
Sourcecan supply the argumentstatedstates.
Type Aliases§
- CliLaw
Result - Reports a broken CLI law by the obligation it breaks.
Attribute Macros§
- cli
- Lowers extension methods into named, composable CLI programs.