Skip to main content

Crate alux_cli_direct

Crate alux_cli_direct 

Source
Expand description

§alux-cli-direct

Runs an alux-cli program as a command line, with no parser framework.

CliDirect folds a program into its commands, then for each command line it:

  • selects the command by its path, the longest one the words name, skipping global options written before or within the path;
  • parses the rest as the command’s arguments, as POSIX getopt does: --long value, --long=value, -s value, -svalue, clustered switches -abc where the first letter taking a value takes the rest of the word (-sd:), -NUM for a command’s numeric option, name=value operands for assigned arguments, and --, after which every word is positional;
  • decodes each argument through its source, from the command line, then its environment variable, then its default, with the value’s DirectWord;
  • applies the operation to the handle it was given, or, beneath a within, to the context the context operation opens from it, and renders the outcome.

A success writes its value to standard output and exits with zero. A fallible command’s failure writes its error to standard error, in its alternate form so a chain of causes such as anyhow’s shows in full, and exits with the status the declaration states. Words that do not make the command write the problem and the command’s usage, and exit with USAGE_STATUS. --help or -h prints help built from the same program: command lists from the first line of each operation’s documentation, and per-command usage, arguments, options, global options, environment variables, and defaults.

use alux_cli::{CliCommandsAlg, CliProgramBuilder, cli};
use alux_cli_direct::{CliDirect, Exit};
use alux_ext::ext;
use std::sync::Arc;

trait Greeting {
    fn greeting(&self) -> String;
}

#[ext(name = GreetingExt, defunc)]
impl<This> This
where
    This: Greeting,
{
    /// Greets someone, loudly or not.
    fn greet(&self, name: String, loud: bool) -> String {
        let greeting = format!("{}, {name}", self.greeting());
        if loud { greeting.to_uppercase() } else { greeting }
    }
}

#[ext(name = GreetingCliExt, defunc(via = cli))]
impl<This> This
where
    This: CliCommandsAlg,
{
    fn greeting_cli<App>(&self) {
        self.commands().cmd(
            "greet",
            self.op(App::greet).arg("name", self.positional("Who to greet").default("world")).arg("loud", self.named("Shout").switch().short('l')),
        )
    }
}

struct App;

impl Greeting for App {
    fn greeting(&self) -> String {
        "hello".to_owned()
    }
}

let run = |line: &str| CliDirect::new(Arc::new(App)).run_blocking(CliProgramBuilder.greeting_cli::<App>(), line.split(' '));

assert_eq!(run("hi greet ana").stdout, "hello, ana\n");
assert_eq!(run("hi greet -l").stdout, "HELLO, WORLD\n");
assert_eq!(run("hi greet --nope").status, 2);

// In a binary, the process's own arguments: `CliDirect::new(app).run_blocking(program, std::env::args()).exit()`.
let _: fn(Exit) -> ! = Exit::exit;

Words are operating system strings, std::env::args_os() as given, and a value reads its word through DirectWord: OsString and PathBuf take it unchanged, whatever its bytes. Each command reads its words under the conventions it declares, such as .options_first() or .verbatim(). failures_after(FailurePrefix::Command) writes a failure as cat: reason instead of error: reason, a failure stating cli_reported exits with its status alone, and unknown_command(127, ..) ends a command line naming no command with that status and message. usage_status(1) ends words that do not make a command with that status instead of USAGE_STATUS, and selecting(Some("cat")) compiles only the commands beneath that first-layer name. In a debug build, a program declaring one command path more than once runs nothing and names the duplicates, exiting with DUPLICATE_STATUS; a release build skips the check, as clap does. alux-cli-multicall reads a command line for a multicall executable.

run_once takes the handle and applies the selected command to the handle itself, for a handle that owns what it reads and cannot be cloned; run_once_blocking waits for it, and run_main runs the process’s own command line that way, writes what it shows, and exits with its status. run answers a future instead, Send and 'static, for an application that awaits it on its own runtime or runs several command lines at once on many threads; run_blocking waits on the calling thread. A successful value renders through DirectRender, which the standard scalars, String, paths, Option, and Vec (one value per line) implement and a domain type implements for itself.

Structs§

CliDirect
Interprets a CLI program as a command line, applying its operations to Handle.
DirectCompiler
Compiles a CLI program into the commands run on a Handle, their words read by a Decoder.
Entry
One command of a compiled program: what it is, and how to run it on a handle once its words, read by a Decoder, are decoded.
Exit
What one run of a command line shows: its exit status and what it writes to each stream.
ParseError
States why words do not read as a command’s arguments, and where.
Parsed
The words after a command’s path, assigned to the command’s arguments.
Span
Places something read in the words: the word, by index, and the byte within it.

Enums§

FailurePrefix
Names what a failure is written after: error: reason, cat: reason.
ParseErrorKind
States what is wrong where words stop reading as a command’s arguments.

Constants§

DUPLICATE_STATUS
The status a program declaring a command path more than once exits with, in a debug build: EX_SOFTWARE, as it is the program’s fault, not the command line’s.

Traits§

DirectRender
Renders a command’s successful value as the text it writes to standard output.
DirectWord
States how one word on the command line denotes a value.

Type Aliases§

Ready
A command whose arguments are decoded, waiting for the handle it is applied to.
Running
A command running on its handle, ending in the exit it renders.