alux-cli 0.4.0

Composable, interpreter-independent command-line programs for meaning-first Rust design
Documentation
# 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 `Op_connect<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.