Standard library · System and tools

flag

Reading command line options such as --port 8080 and -v with the right type, and generating the help text.

import flag

On this page

Types
Constants and variables
Functions

The flag package reads command line options. Each flag has a long name (--port), a short name (-p), a default value and a line of help. The value can be given either way: --port=8080 or --port 8080. Any argument that is not a flag is "positional", and after -- everything counts as positional.

--help and -h are always recognised and the Usage text is generated for you. Pass Parse the arguments without the program's own name.

Types

`FlagSet`

struct FlagSet

A program's set of flags and the result of parsing.

Name	Type	Description
`prog`	`str = ""`	The program's name, for the help text.
`desc`	`str = ""`	The program's description, for the help text.
`names`	`Vector`	The long names of the flags.
`shorts`	`Vector`	The short names of the flags.
`kinds`	`Vector`	The kind of each flag.
`vals`	`Vector`	The current value of each flag, as text.
`defs`	`Vector`	The default value of each flag.
`helps`	`Vector`	The help line of each flag.
`was_set`	`Vector`	Whether each flag appeared on the command line.
`pos`	`Vector`	The positional arguments.
`err`	`str = ""`	The message of the last parse error.
`help_wanted`	`bool = false`	True when `--help` was given.

flag-Parse.salam

import flag

func main:
    mut f := flag.New("copy", "copies files")
    defer flag.Free(f)
    flag.AddBool(f, "verbose", "v", false, "report everything")
    flag.AddStr(f, "out", "o", "output", "the destination directory")
    flag.AddInt(f, "jobs", "j", 1, "how many jobs at once")
    flag.AddFloat(f, "ratio", "r", 1.0, "the compression ratio")
    mut args := Vector {} as Vector<str>
    defer args.free()
    each a in ["-v", "--out=backup", "-j", "4", "a.txt", "b.txt"]:
        args.push(a)
    end
    println flag.Parse(f, args), "[" + flag.Error(f) + "]"
    println flag.GetBool(f, "verbose"), flag.GetStr(f, "out"), flag.GetInt(f, "jobs"), flag.GetFloat(f, "ratio")
    println flag.WasSet(f, "jobs"), flag.WasSet(f, "ratio")
    println flag.Positional(f), flag.HelpWanted(f)
    println flag.FlagKindBool, flag.FlagKindStr, flag.FlagKindInt, flag.FlagKindFloat
end

Outputtrue [] true backup 4 1 true false ["a.txt", "b.txt"] false 0 1 2 3

Constants and variables

`FlagKindBool`

const FlagKindBool: i32 = 0

The kind of a boolean flag.

The example for this item is shown with the ones above: flag-Parse.salam

`FlagKindStr`

const FlagKindStr: i32 = 1

The kind of a string flag.

The example for this item is shown with the ones above: flag-Parse.salam

`FlagKindInt`

const FlagKindInt: i32 = 2

The kind of a whole number flag.

The example for this item is shown with the ones above: flag-Parse.salam

`FlagKindFloat`

const FlagKindFloat: i32 = 3

The kind of a decimal flag.

The example for this item is shown with the ones above: flag-Parse.salam

Functions

`New`

func New(prog_name: str, description: str): FlagSet

Creates a new flag set with the program's name and description.

The example for this item is shown with the ones above: flag-Parse.salam

`AddBool`

func AddBool(fs &: FlagSet, name: str, short: str, def: bool, help: str)

Declares a boolean flag; it turns true when present, and --name=false is accepted too.

The example for this item is shown with the ones above: flag-Parse.salam

`AddStr`

func AddStr(fs &: FlagSet, name: str, short: str, def: str, help: str)

Declares a string flag.

The example for this item is shown with the ones above: flag-Parse.salam

`AddInt`

func AddInt(fs &: FlagSet, name: str, short: str, def: i64, help: str)

Declares a whole number flag; Persian digits are accepted.

The example for this item is shown with the ones above: flag-Parse.salam

`AddFloat`

func AddFloat(fs &: FlagSet, name: str, short: str, def: f64, help: str)

Declares a decimal flag.

The example for this item is shown with the ones above: flag-Parse.salam

`Parse`

func Parse(fs &: FlagSet, arglist: Vector<str>): bool

Parses the arguments. On an unknown flag, a missing value or a bad number it returns false and Error says why.

The example for this item is shown with the ones above: flag-Parse.salam

`GetStr`

func GetStr(fs &: FlagSet, name: str): str

The value of a string flag.

The example for this item is shown with the ones above: flag-Parse.salam

`GetInt`

func GetInt(fs &: FlagSet, name: str): i64

The value of a whole number flag.

The example for this item is shown with the ones above: flag-Parse.salam

`GetFloat`

func GetFloat(fs &: FlagSet, name: str): f64

The value of a decimal flag.

The example for this item is shown with the ones above: flag-Parse.salam

`GetBool`

func GetBool(fs &: FlagSet, name: str): bool

The value of a boolean flag.

The example for this item is shown with the ones above: flag-Parse.salam

`WasSet`

func WasSet(fs &: FlagSet, name: str): bool

True when the flag appeared on the command line; for telling "the default" apart from "the user asked for exactly this".

The example for this item is shown with the ones above: flag-Parse.salam

`Positional`

func Positional(fs &: FlagSet): Vector<str>

The positional arguments.

The example for this item is shown with the ones above: flag-Parse.salam

`HelpWanted`

func HelpWanted(fs &: FlagSet): bool

True when the user asked for help.

flag-Usage.salam

import flag

func main:
    mut f := flag.New("tool", "an example tool")
    defer flag.Free(f)
    flag.AddBool(f, "quiet", "q", false, "say nothing")
    flag.AddInt(f, "port", "p", 8080, "the port")
    mut args := Vector {} as Vector<str>
    defer args.free()
    args.push("--help")
    flag.Parse(f, args)
    if flag.HelpWanted(f):
        print flag.Usage(f)
    end
    mut bad := Vector {} as Vector<str>
    defer bad.free()
    bad.push("--port=abc")
    mut f2 := flag.New("tool", "")
    defer flag.Free(f2)
    flag.AddInt(f2, "port", "p", 8080, "the port")
    println flag.Parse(f2, bad), flag.Error(f2)
end

OutputUsage: tool [options] [args] an example tool Options: -q, --quiet say nothing -p, --port <int> the port (default: 8080) -h, --help show this help false invalid int value for --port: abc

`Error`

func Error(fs &: FlagSet): str

The message of the last parse error.

The example for this item is shown with the ones above: flag-Usage.salam

`Usage`

func Usage(fs &: FlagSet): str

The full help text, with every flag and its default.

The example for this item is shown with the ones above: flag-Usage.salam

`Free`

func Free(fs &: FlagSet)

Releases the set's memory.

The example for this item is shown with the ones above: flag-Parse.salam