Skip to main content

Crate alux_cli

Crate alux_cli 

Source
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§

ArgumentInfo
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, as dd if=FILE.
CliArgMessage
Holds the message a misnamed argument is reported with, written at compile time.
CliProgram
Carries a typed CLI program during fluent composition.
CliProgramBuilder
Constructs neutral CLI programs.
Command
Represents one named command without choosing an interpreter.
CommandDescription
Describes one command as a describing interpretation observes it.
Conventions
States how one command’s words are read as its options and operands.
DelimitedSource
Takes a list’s words after its spelling, each word split on a delimiter: --peers a,b and PEERS=a,b both 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 Result output as success or failure: what .fallible() declares.
Many
Marks a source supplying Vec of values: any number, in the order given.
Merge
Represents the composition of two CLI programs, left first.
Named
Includes a separately named CLI program.
NamedSource
Takes an argument’s words after its spelling, --long or -s, or from an operand name=value once .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 Option of a value: at most one. A product takes all of its fields or none of them, a sum one alternative or none.
OptionalValue
Marks a named source supplying Option<Option<_>>: whether its spelling is given, and the value written in the same word, as sed -i.bak gives one and sed -i none.
Options
Marks a named source spelled as options: --long or -s, with the value after it.
PositionalSource
Takes an argument’s words by position, in the order the positional arguments are declared.
ProductSource
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.
WithFallback
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.
CliArgumentError
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.
SourceInfo
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§

CliArgAt
Names the type of the argument at position INDEX of an operation’s argument product.
CliCommandsAlg
Describes construction and composition of command collections.
CliCommandsObserved
Observes a command collection as the commands it describes, in order.
CliCompositionLawsExt
States that command collections form an ordered monoid under merge.
CliContextAlg
Compiles a subtree whose commands are applied to the context an operation answers.
CliContextLawsExt
States that a context adds its global arguments to every command beneath it and changes nothing else.
CliDeclarationLawsExt
States that declaring a command preserves its operation and gives every argument one source.
CliDecodeSources
Decodes the operation arguments Args through declared sources, with Decoder.
CliFailureAlg
States what a domain failure denotes on the command line: the status the command exits with.
CliNamedSource
Marks a source spelled by name, which is what a product’s field or a sum’s alternative takes.
CliNamedSources
States that every source in a product is named.
CliNestAlg
Compiles a command collection beneath one subcommand name.
CliNestLawsExt
States that nesting prefixes every path and changes nothing else.
CliOperationAlg
Compiles one command: a first-order operation under a name, with a source for each argument.
CliOutcomeLawsExt
States that a command’s outcome and its exit status agree.
CliOutcomeOf
Reads an operation’s output as a command’s outcome under a declared mode.
CliProgramAlg
Interprets a named, defunctionalized CLI program with Compiler.
CliProgramExt
Compiles defunctionalized CLI programs with an interpreter.
CliShape
States how many occurrences a source of one shape takes.
CliSourceAt
States that a source can supply the argument at position INDEX of the argument product Args.
CliSourceDecode
Decodes the argument a source supplies, with Decoder.
CliSourceFor
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.
CliStatedFor
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.
CliWordAlg
Decodes one word as a value; an interpreter answers it for the values it supports.
CliWordsAlg
Answers the words given for one argument and the environment it falls back to.
CompileCliProgram
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 position of method is not named name, or an empty message when it is, at compile time: “argument 0 of start_node is name, not fff”.
cli_arg_named
Says whether the argument at position among names is named name, at compile time.
cli_source_stated
Checks, at compile time, that Source can supply the argument stated states.

Type Aliases§

CliLawResult
Reports a broken CLI law by the obligation it breaks.

Attribute Macros§

cli
Lowers extension methods into named, composable CLI programs.