Specification v0.1.0

Declaring a command: its flags, valued options, positional arguments, subcommands and version.

`OptionSpec`

pub struct OptionSpec {
    pub name: char8[..];
    pub short: char32;
    pub value: char8[..];
    pub help: char8[..];
}

One option a command accepts, such as --output FILE or -v. Copy; the text it holds is borrowed and must outlive the specification.

Source

Fields

Name	Type	Description
`name`	`char8[..]`	The long name without its dashes, such as `output` for `--output`. Never empty.
`short`	`char32`	The short name, such as `o` for `-o`, or `'\0'` for none. An ASCII letter or digit.
`value`	`char8[..]`	What the help text calls the option's value, such as `FILE`, or empty for a flag that takes no value.
`help`	`char8[..]`	One line saying what the option does.

`PositionalKind`

pub enum PositionalKind {
    Required,
    Optional,
    Remaining
}

How a positional argument may be given. Copy, carrying no payload.

Source

Cases

Name	Description
`Required`	Exactly once; parsing fails without it.
`Optional`	At most once.
`Remaining`	Any number of times, taking every remaining positional argument. Only the last positional may be this kind.

`PositionalSpec`

pub struct PositionalSpec {
    pub name: char8[..];
    pub kind: PositionalKind;
    pub help: char8[..];
}

One positional argument a command accepts, such as <input>. Copy; the text it holds is borrowed and must outlive the specification.

Source

Fields

Name	Type	Description
`name`	`char8[..]`	The name queries and the help text use, such as `input`. Never empty.
`kind`	`PositionalKind`	How the argument may be given.
`help`	`char8[..]`	One line saying what the argument is.

`CommandSpec`

pub struct CommandSpec {
    pub name: char8[..];
    pub summary: char8[..];
    pub version: char8[..];
    pub options: OptionSpec[..];
    pub positionals: PositionalSpec[..];
    pub commands: CommandSpec[..];
}

A command: what it is called, what it accepts, and the subcommands under it. Copy; every slice and text it holds is borrowed and must outlive it and every parse made from it. A command with subcommands takes the first positional argument as the subcommand's name, so it should declare no positionals of its own.

Source

Fields

Name	Type	Description
`name`	`char8[..]`	The command's name: the program's name at the top, and the word that selects it below.
`summary`	`char8[..]`	One line saying what the command does.
`version`	`char8[..]`	The version `--version` reports, or empty when the command has none.
`options`	`OptionSpec[..]`	The options, in the order the help text lists them.
`positionals`	`PositionalSpec[..]`	The positional arguments, in the order they are given.
`commands`	`CommandSpec[..]`	The subcommands, in the order the help text lists them.

Methods

`WithVersion`

pub func WithVersion(
    self: &CommandSpec,
    version: char8[..]
) -> CommandSpec

This command with version, which --version then reports.

Name	Type	Description
`version`	`char8[..]`	the version text, such as `1.4.2`

Returns: the changed copy

Source

`WithOptions`

pub func WithOptions(
    self: &CommandSpec,
    options: OptionSpec[..]
) -> CommandSpec

This command with options, which must outlive it.

Name	Type	Description
`options`	`OptionSpec[..]`	the options, in the order the help text lists them

Returns: the changed copy

Source

`WithPositionals`

pub func WithPositionals(
    self: &CommandSpec,
    positionals: PositionalSpec[..]
) -> CommandSpec

This command with positionals, which must outlive it.

Name	Type	Description
`positionals`	`PositionalSpec[..]`	the positional arguments, in the order they are given

Returns: the changed copy

Source

`WithCommands`

pub func WithCommands(
    self: &CommandSpec,
    commands: CommandSpec[..]
) -> CommandSpec

This command with commands, which must outlive it.

Name	Type	Description
`commands`	`CommandSpec[..]`	the subcommands, in the order the help text lists them

Returns: the changed copy

Source

`Flag`

pub func Flag(
    name: char8[..],
    short: char32,
    help: char8[..]
) -> OptionSpec

An option that is present or absent and takes no value, such as --verbose.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the long name without its dashes
`short`	`char32`	the short name, or `'\0'` for none
`help`	`char8[..]`	one line saying what the option does

Returns: the option's specification

`ValueOption`

pub func ValueOption(
    name: char8[..],
    short: char32,
    value: char8[..],
    help: char8[..]
) -> OptionSpec

An option that takes a value, such as --output FILE. The value may follow the option as the next argument, after = in the long form, or directly after the short letter, so --output a.txt, --output=a.txt, -o a.txt and -oa.txt all give a.txt.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the long name without its dashes
`short`	`char32`	the short name, or `'\0'` for none
`value`	`char8[..]`	what the help text calls the value, such as `FILE`; never empty
`help`	`char8[..]`	one line saying what the option does

Returns: the option's specification

`Required`

pub func Required(
    name: char8[..],
    help: char8[..]
) -> PositionalSpec

A positional argument that must be given.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the name queries and the help text use
`help`	`char8[..]`	one line saying what the argument is

Returns: the positional's specification

`Optional`

pub func Optional(
    name: char8[..],
    help: char8[..]
) -> PositionalSpec

A positional argument that may be left out.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the name queries and the help text use
`help`	`char8[..]`	one line saying what the argument is

Returns: the positional's specification

`Remaining`

pub func Remaining(
    name: char8[..],
    help: char8[..]
) -> PositionalSpec

A positional argument that takes every positional argument left, which may be none.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the name queries and the help text use
`help`	`char8[..]`	one line saying what the arguments are

Returns: the positional's specification

`Command`

pub func Command(
    name: char8[..],
    summary: char8[..]
) -> CommandSpec

A command with a name and a summary, and as yet no version, options, positionals or subcommands. The With methods fill in the rest, each returning the changed copy.

Source

Parameters

Name	Type	Description
`name`	`char8[..]`	the program's name, or the word that selects a subcommand
`summary`	`char8[..]`	one line saying what the command does

Returns: the command's specification

Help

Writing the help, usage and version text generated from a specification.

Overview

Structured logging: levels, typed fields, text and JSON-lines records, a process-wide log for every thread, and log files that rotate by size

Edit this page on GitHub