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 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().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:

# 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.

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:

# 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 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().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.

# 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:

# 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:

# 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:

# 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 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.