# 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`](https://docs.rs/alux-ext) and [`alux-shape`](https://docs.rs/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.
```rust
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().cmd(
// `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("name", 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_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:
```rust compile_fail
# use alux_cli::{CliCommandsAlg, cli};
# use alux_ext::ext;
# trait Lines { fn first(&self) -> usize; }
# #[ext(name = LinesExt, defunc)]
# impl<This> This where This: Lines { fn head(&self) -> usize { self.first() } fn tail(&self) -> usize { self.first() } }
#[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().cmd("head", self.op(Machine::head)).cmd("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`.
```rust
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()
.cmd(
"add",
self.op(Machine::add_note)
// `store: Store`, once: `--store <store>` or `-s <store>`, else `$NOTES_STORE`, else `notes`.
.arg("store", self.named("Store to write to").short('s').env("NOTES_STORE").default("notes"))
// `text: Text`, once: the first positional word.
.arg("text", self.positional("Text of the note"))
// `tags: Vec<Tag>`, any number of times: `--tag <tag>` or `-t <tag>`.
.arg("tags", self.named("Tag the note carries").many().long("tag").short('t'))
// `pinned: bool`, a switch: true when `--pinned` or `-p` is given.
.arg("pinned", self.named("Pin the note").switch().short('p')),
)
.cmd(
"list",
self.op(Machine::list_notes)
// `store: Store`, the same source as in `add`.
.arg("store", 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("tag", self.positional("Only notes with this tag").optional())
// `limit: usize`, once: `--limit <limit>` or `-n <limit>`, else `10`.
.arg("limit", 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, `--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:
```rust compile_fail,E0080
# use alux_cli::{CliCommandsAlg, CliProgramExt, cli};
# use alux_ext::ext;
# trait Remote { type Text; }
# #[ext(name = RemoteExt, defunc)]
# impl<This, Text: Default> This where This: Remote<Text = Text> {
# /// Connects.
# fn connect(&self, host: Text, user: Text) -> Text { Text::default() }
# }
#[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().cmd(
"connect",
self.op(Machine::connect).arg("user", self.named("User")).arg("host", self.named("Host")),
)
}
}
# struct Count;
# impl alux_cli::CliCommandsAlg for Count { type Commands = usize; fn cli_empty(&self) -> usize { 0 } fn cli_merge(&self, l: usize, r: usize) -> usize { l + r } }
# impl<O: alux_ext::OperationAlg, S, M> alux_cli::CliOperationAlg<O, S, M> for Count { type Commands = usize; fn cli_operation(&self, _: &'static str, _: O, _: S, _: M, _: alux_cli::Conventions) -> usize { O::ARG_NAMES.len() } }
# struct Box;
# impl Remote for Box { type Text = String; }
# Count.compile_cli(alux_cli::CliProgramBuilder.remote_cli::<Box>());
```
## 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`](https://docs.rs/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.
```rust
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().cmd(
"export",
self.op(Machine::export_all)
.arg("target", self.sum().or("at", self.named("Export to a location").short('a')).or("out", self.named("Export to the standard output").switch()))
.arg("credentials", self.product().field("user", self.named("User to export as")).field("secret", self.named("Secret of the user")).optional()),
)
}
}
```
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.
```rust compile_fail,E0080
# use alux_cli::{CliCommandsAlg, CliProgramExt, cli};
# use alux_ext::ext;
# use alux_shape::Shape;
# #[derive(Shape)]
# struct Login { user: String, host: String }
# trait Remote {}
# #[ext(name = RemoteExt, defunc)]
# impl<This> This where This: Remote {
# /// Connects.
# fn connect(&self, login: Login) -> usize { 0 }
# }
#[ext(name = RemoteCliExt, defunc(via = cli))]
impl<This> This where This: CliCommandsAlg {
fn remote_cli<Machine>(&self) {
// error: field 0 of the product is `user`, not `host`
self.commands().cmd(
"connect",
self.op(Machine::connect)
.arg("login", self.product().field("host", self.named("Host")).field("user", self.named("User"))),
)
}
}
# struct Count;
# impl alux_cli::CliCommandsAlg for Count { type Commands = usize; fn cli_empty(&self) -> usize { 0 } fn cli_merge(&self, l: usize, r: usize) -> usize { l + r } }
# impl<O: alux_ext::OperationAlg, S, M> alux_cli::CliOperationAlg<O, S, M> for Count { type Commands = usize; fn cli_operation(&self, _: &'static str, _: O, _: S, _: M, _: alux_cli::Conventions) -> usize { O::ARG_NAMES.len() } }
# struct Box;
# impl Remote for Box {}
# Count.compile_cli(alux_cli::CliProgramBuilder.remote_cli::<Box>());
```
Fields and alternatives are named, because positions belong to the command:
```rust compile_fail
# use alux_cli::{CliCommandsAlg, cli};
# use alux_ext::ext;
# #[derive(alux_shape::Shape)]
# struct Pair<A, B> { a: A, b: B }
# trait Pairing { type A; type B; fn pair(&self, pair: Pair<Self::A, Self::B>); }
# #[ext(name = PairingExt, defunc)]
# impl<This, A, B> This where This: Pairing<A = A, B = B> { fn paired(&self, pair: Pair<A, B>) { self.pair(pair) } }
#[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().cmd("pair", self.op(Machine::paired).arg("pair", self.product().field("a", self.positional("A")).field("b", 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. 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:
```rust compile_fail
# use alux_cli::{CliCommandsAlg, cli};
# use alux_ext::ext;
# trait Shelf { type Store; type Opened; fn open(&self, store: Self::Store) -> Self::Opened; fn count(&self) -> usize; }
# #[ext(name = ShelfExt, defunc)]
# impl<This, Store, Opened> This where This: Shelf<Store = Store, Opened = Opened> {
# fn opened(&self, store: Store) -> Opened { self.open(store) }
# fn counted(&self) -> usize { self.count() }
# }
#[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("store", self.positional("Store")), self.inner_cli::<Machine>())
}
fn inner_cli<Machine>(&self) {
self.commands().cmd("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:
```rust compile_fail
# use alux_cli::{CliCommandsAlg, cli};
# use alux_ext::ext;
# trait Open { type Opened; fn open(&self) -> Self::Opened; }
# #[ext(name = OpenExt, defunc)]
# impl<This, Opened> This where This: Open<Opened = Opened> { fn opened(&self) -> Opened { self.open() } }
#[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().cmd("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 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`](https://docs.rs/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`](https://github.com/alux-network/alux-rust/blob/master/alux-cli/COMING_FROM_CLAP.md) shows each `clap` concept beside its `alux-cli` form, and how an application moves over one command at a time.