Standard library · System and tools

cli

Command line programs with several commands, like git commit, and asking the user questions.

import cli

On this page

Types
Constants and variables
Functions

Many tools have several commands: salam build, salam run. The cli package registers the commands, works out from the first argument which one was asked for, and builds the overall help text. For each command's own flags, use the flag package alongside it.

Prompt and Confirm ask the user something in the terminal; their example is not run here because it would wait for an answer.

Types

`App`

struct App

A command line program and its commands.

Name	Type	Description
`name`	`str = ""`	The program's name.
`desc`	`str = ""`	The program's description.
`version`	`str = ""`	The program's version.
`cmd_names`	`Vector`	The names of the commands.
`cmd_descs`	`Vector`	The descriptions of the commands.

cli-Dispatch.salam

import cli
import str

func run(app &: cli.App, line: str):
    args := str.Split(line, " ")
    command := cli.Dispatch(app, args)
    if command == cli.CmdHelp:
        println "help was asked for"
    else command == cli.CmdVersion:
        println "version:", app.version
    else command == cli.CmdUnknown:
        println "unknown command"
    else:
        println "running:", command, cli.RemainingArgs(args)
    end
    args.free()
end

func main:
    mut app := cli.New("salamctl", "project management", "1.0.0")
    cli.Register(app, "build", "build the project")
    cli.Register(app, "test", "run the tests")
    println cli.HasCommand(app, "build"), cli.CommandDesc(app, "test")
    each line in ["build --fast", "--help", "--version", "deploy"]:
        run(app, line)
    end
    print cli.Usage(app)
end

Outputtrue run the tests running: build ["--fast"] help was asked for version: 1.0.0 unknown command salamctl 1.0.0 project management Usage: salamctl <command> [options] Commands: build build the project test run the tests Run 'salamctl <command> --help' for help on a specific command.

Constants and variables

`CmdHelp`

const CmdHelp: str = "__help__"

What Dispatch returns when help was asked for, or no argument was given.

The example for this item is shown with the ones above: cli-Dispatch.salam

`CmdVersion`

const CmdVersion: str = "__version__"

What Dispatch returns when the version was asked for.

The example for this item is shown with the ones above: cli-Dispatch.salam

`CmdUnknown`

const CmdUnknown: str = "__unknown__"

What Dispatch returns for a command that was never registered.

The example for this item is shown with the ones above: cli-Dispatch.salam

Functions

`New`

func New(name: str, desc: str, version: str): App

Creates a program with a name, a description and a version.

The example for this item is shown with the ones above: cli-Dispatch.salam

`Register`

func Register(app &: App, name: str, desc: str)

Registers one command with its description.

The example for this item is shown with the ones above: cli-Dispatch.salam

`HasCommand`

func HasCommand(app &: App, name: str): bool

True when the command has been registered.

The example for this item is shown with the ones above: cli-Dispatch.salam

`CommandDesc`

func CommandDesc(app &: App, name: str): str

The description of a command.

The example for this item is shown with the ones above: cli-Dispatch.salam

`Dispatch`

func Dispatch(app &: App, argv: Vector<str>): str

Says from the first argument which command was asked for. Pass the arguments without the program's name. --help and --version are recognised automatically.

The example for this item is shown with the ones above: cli-Dispatch.salam

`RemainingArgs`

func RemainingArgs(argv: Vector<str>): Vector<str>

The arguments after the first, which is the command name, for handing to the flag package.

The example for this item is shown with the ones above: cli-Dispatch.salam

`Usage`

func Usage(app &: App): str

The program's overall help text with the list of commands.

The example for this item is shown with the ones above: cli-Dispatch.salam

`RequireFlags`

func RequireFlags(fs &: flag.FlagSet, names: Vector<str>): Vector<str>

Of the names you give, returns the flags that did not appear on the command line; for required flags.

cli-RequireFlags.salam

import cli
import flag

func main:
    mut f := flag.New("deploy", "")
    defer flag.Free(f)
    flag.AddStr(f, "host", "h", "", "the server")
    flag.AddStr(f, "user", "u", "", "the user")
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("--host=example.com")
    flag.Parse(f, args)
    mut required := Vector {} as Vector<str>
    defer required.free()
    required.push("host")
    required.push("user")
    println "missing:", cli.RequireFlags(f, required)
end

Outputmissing: ["user"]

`Confirm`

func Confirm(question: str): bool

Asks a yes or no question; y or yes is true and anything else is false.

cli-Prompt.salam

import cli

func main:
    name := cli.Prompt("project name: ")
    language := cli.PromptOr("language", "english")
    if cli.Confirm("create it?"):
        println "creating", name, "in", language
    end
end

`Prompt`

func Prompt(question: str): str

Asks a question and returns the user's answer.

The example for this item is shown with the ones above: cli-Prompt.salam

`PromptOr`

func PromptOr(question: str, def: str): str

Like Prompt, but returns the default when the user types nothing.

The example for this item is shown with the ones above: cli-Prompt.salam