silk.cli.command.

When to use#

Describe a type with impl CommandLine for T, returning a Command built with Opt, then give the type to silk.cli.parse.Cli.parse or Cli.read.

Details#

Every operation here is static, so a description is a compile-time value. A description names fields by their labels, written as string literals that the compiler checks against the type, so Command<Git>.make(...) |> Command.option("quiet", ...) stops compilation at "quiet" when Git has no field quiet. The field types choose how each value is read; the description only adds names, aliases, help text, defaults, and whether a field is positional, a subcommand, or required. A field that the description does not mention is still an option, named after its label.

A union describes subcommands: each variant is one, named after its label in kebab case, and its fields are that subcommand's options and arguments. A struct or variant field marked with Command.subcommand holds such a union.

Import as Command with import silk.cli.command { Command }.

Public declarations: 6.

OptionSpec#

pub struct OptionSpec

The description of one struct field as an option or a positional argument.

Field field#

pub field: string<'static>

The label of the struct field that receives the value.

Field long#

pub long: string<'static>

The long name without dashes. Empty means the kebab-case form of field.

Field short#

pub short: string<'static>

The one-letter alias without the dash. Empty means no alias.

Field description#

pub description: string<'static>

The help text.

Field required#

pub required: bool

Whether the command line must give this value.

Field positional#

pub positional: bool

Whether the value comes from a positional argument instead of a named option.

Field subcommand#

pub subcommand: bool

Whether the field is a subcommand: a union with CommandLine, whose variants are the subcommands.

Field flatten#

pub flatten: bool

Whether the field is a group of options: a struct with CommandLine whose options the command line gives as this command's own.

Field fallback#

pub fallback: string<'static>

The text read when neither the command line nor the environment gives a value. Empty means none: the field keeps the value that ArgValue.initial returns.

Field choices#

pub choices: Intrinsic.StaticSequence<string<'static>>

The values the option accepts. Empty means any value its field type reads.

Field env#

pub env: string<'static>

The environment variable that supplies the value when the command line does not. Empty means none.

Field check#

pub check: Option<Intrinsic.FunctionRef>

The check a value must pass, a fn(&V) -> bool for the field type V, if any.

VariantSpec#

pub struct VariantSpec

The description of one variant of a subcommand union.

Field label#

pub label: string<'static>

The label of the variant.

Field description#

pub description: string<'static>

The help text.

CommandLine#

pub interface CommandLine

A type that the command line can build: a struct of options and positional arguments, or a union whose variants are subcommands.

Details#

command describes the type. The default describes nothing, so every field is an option named after its label and every variant is a subcommand named after its label, in kebab case. Write impl CommandLine for T {} to take the default, or give command to add names, help text, and positional arguments.

Operation command#

static fn command() -> Command<Self>

Returns the description of the type.

Command#

pub struct Command<T>

The description of a command whose parsed values fill T: a struct, or a union whose variants are subcommands.

Field name#

pub name: string<'static>

The program name shown in the usage line.

Field description#

pub description: string<'static>

The help text shown under the usage line.

Field version#

pub version: string<'static>

The text that --version prints. Empty means the command has no --version.

Field options#

pub options: Intrinsic.StaticSequence<OptionSpec>

The options and positional arguments, in the order they were added. For a union, these describe the fields of its variants.

Field variants#

pub variants: Intrinsic.StaticSequence<VariantSpec>

The help text of the variants of a union.

Implementation Command<T>#

impl<T> Command<T>

Associated function make#

pub static fn make(name: string<'static>, description: string<'static>) -> Command<T>

Returns a command named name with the help text description and no options.

Associated function withVersion#

pub static fn withVersion(command: Command<T>, version: string<'static>) -> Command<T>

Returns command with a --version option that prints version.

Associated function option#

pub static fn option(
    command: Command<T>,
    field: Intrinsic.FieldName<T>,
    option: OptionSpec,
  ) -> Command<T>

Returns command with the field field read as a named option, described by option.

Details#

field is checked against the fields of T where it is written, so a misspelled name is a compile error at the name. For a union, field names a field of any of its variants.

Associated function arg#

pub static fn arg(
    command: Command<T>,
    field: Intrinsic.FieldName<T>,
    argument: OptionSpec,
  ) -> Command<T>

Returns command with the field field read as a positional argument, described by argument. Positional arguments are read in the order they are added. A List field takes every remaining positional argument.

Associated function subcommand#

pub static fn subcommand(command: Command<T>, field: Intrinsic.FieldName<T>) -> Command<T>

Returns command with the field field read as a subcommand. The field's type is a union with CommandLine, and the command line names one of its variants in kebab case, such as remote for the variant Remote.

Associated function flatten#

pub static fn flatten(command: Command<T>, field: Intrinsic.FieldName<T>) -> Command<T>

Returns command with the field field read as a group of options. The field's type is a struct with CommandLine, and its options are written as options of this command, so one group, such as the options every build command shares, is described once and used by many commands.

Details#

A group holds named options only: its own positional arguments or subcommands are a compile error. Help lists the group's options among the command's own.

Associated function variant#

pub static fn variant(
    command: Command<T>,
    variant: Intrinsic.VariantName<T>,
    description: string<'static>,
  ) -> Command<T>

Returns command with the help text description for the variant variant, for a union whose variants are subcommands.

Associated function find#

pub static fn find(command: Command<T>, field: string<'static>) -> OptionSpec

Returns the description of field: the one added to command, or the default option named after the field.

Associated function field#

pub static fn field<V>(command: Command<T>, field: Intrinsic.Field<T, V>) -> OptionSpec

Returns the description of field, as Command.find does, with the first line of the field's /// comment as its help text when the description gives none.

Associated function describeVariant#

pub static fn describeVariant(command: Command<T>, label: string<'static>) -> string<'static>

Returns the help text of the variant labeled label, or empty text.

Associated function position#

pub static fn position(
    command: Command<T>,
    fields: Intrinsic.Fields<T>,
    field: string<'static>,
  ) -> usize

Returns the zero-based position of field among the positional arguments of command that belong to fields.

Associated function count#

pub static fn count(
    command: Command<T>,
    fields: Intrinsic.Fields<T>,
    subcommands: bool,
  ) -> usize

Returns the number of entries of command among fields that are positional arguments, or with subcommands, that are subcommands.

Associated function validate#

pub static fn validate(command: Command<T>, fields: Intrinsic.Fields<T>) -> bool

Checks the entries of command among fields and stops compilation with a message when two clash. Returns true when they do not. Field names are already checked where they are written.

Implementation OptionSpec#

impl OptionSpec

Associated function longFlag#

pub static fn longFlag(option: OptionSpec) -> string<'static>

Returns -- and the long name of option.

Associated function shortFlag#

pub static fn shortFlag(option: OptionSpec) -> string<'static>

Returns - and the alias of option, or empty text when it has none.

Associated function placeholder#

pub static fn placeholder(option: OptionSpec) -> string<'static>

Returns the name of a positional argument in the usage line, such as <files>.

Opt#

pub struct Opt

The static builders of the description of one option or positional argument. Start with Opt.about or Opt.plain and give the result to Command.option or Command.arg.

Implementation Opt#

impl Opt

Associated function about#

pub static fn about(description: string<'static>) -> OptionSpec

Returns a description with the help text description and nothing else.

Associated function plain#

pub static fn plain() -> OptionSpec

Returns a description with no help text. The option is named -- and the kebab-case form of its field.

Associated function short#

pub static fn short(option: OptionSpec, short: string<'static>) -> OptionSpec

Returns option with the one-letter alias short, written without the dash.

Associated function long#

pub static fn long(option: OptionSpec, long: string<'static>) -> OptionSpec

Returns option with the long name long, written without the dashes.

Associated function describe#

pub static fn describe(option: OptionSpec, description: string<'static>) -> OptionSpec

Returns option with the help text description.

Associated function required#

pub static fn required(option: OptionSpec) -> OptionSpec

Returns option as one that the command line must give.

Associated function choice#

pub static fn choice(option: OptionSpec, value: string<'static>) -> OptionSpec

Returns option that also accepts the value value. Once an option has a choice, the command line can give only one of its choices, and the help text lists them.

Associated function default#

pub static fn default(option: OptionSpec, text: string<'static>) -> OptionSpec

Returns option that reads text when neither the command line nor the environment gives a value, such as Opt.default("1") for a count. The help text shows it.

Associated function env#

pub static fn env(option: OptionSpec, name: string<'static>) -> OptionSpec

Returns option that reads the environment variable name when the command line does not give it. Only Cli.fromHost and Cli.parseWith read the environment.

Associated function check#

pub static fn check<V>(option: OptionSpec, check: fn<'static>(&V) -> bool) -> OptionSpec

Returns option whose value must pass check, an ordinary function of the field's value, such as Opt.check<u32>(positive) for a u32 field. A value that fails it is an invalid value; the parser calls check directly.

kebab#

pub static fn kebab(label: string<'static>) -> string<'static>

Category: Command line.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.