cli #

Description

cli is a command line option parser, that supports declarative subcommands, each having a separate set of options.

See also the flag module, for a simpler command line option parser, that supports only options.

Example

module main

import os
import cli

fn main() {
    mut app := cli.Command{
        name:        'example-app'
        description: 'example-app'
        execute:     fn (cmd cli.Command) ! {
            println('hello app')
            return
        }
        commands:    [
            cli.Command{
                name:    'sub'
                alias:   's'
                execute: fn (cmd cli.Command) ! {
                    println('hello subcommand')
                    return
                }
            },
        ]
    }
    app.setup()
    app.parse(os.args)
}

Subcommands can set alias to accept a shorter invocation token, for example example-app s.

Help layout

--help is generated automatically. Beyond Usage:, Flags: and Commands: the output picks up extra sections when the relevant Command fields are populated:

• Inherited flags: — flags inherited from any ancestor through Flag.global. Renders separately from local flags so a sub-command's own surface stays readable.
• Grouped commands — set group on a sub-command to lift it out of the default Commands: block into a section named after the group. The group string is rendered verbatim followed by :, so capitalisation is the caller's choice. Sub-commands sharing a group keep their declaration order.
• Examples: — set examples []string on a Command; each entry becomes one indented line.
• Learn more: — set learn_more string; newlines split the block into separate lines.

Sections that have nothing to render are simply omitted, so existing apps see no change unless they opt in by setting these fields. See examples/cli_groups.v for a runnable program that exercises all of them.

fn print_help_for_command(cmd Command) !

print_help_for_command outputs the help message of help_cmd.

fn print_manpage_for_command(cmd Command) !

print_manpage_for_command prints the manpage for the command or subcommand in man_cmd to stdout.

fn FlagType.from[W](input W) !FlagType

fn (f FnCommandCallback) str() string

str returns the string representation of the callback.

fn (flags []Flag) get_all_found() []Flag

get_all_found returns an array of all Flags found in the command parameters.

fn (flags []Flag) get_bool(name string) !bool

get_bool returns true if the flag specified in name is set. get_bool returns an error if the FlagType is not boolean.

fn (flags []Flag) get_int(name string) !int

get_int returns the int value argument of the flag specified in name. get_int returns an error if the FlagType is not integer.

fn (flags []Flag) get_ints(name string) ![]int

get_ints returns the array of int value argument of the flag specified in name. get_ints returns an error if the FlagType is not integer.

fn (flags []Flag) get_float(name string) !f64

get_float returns the f64 value argument of the flag specified in name. get_float returns an error if the FlagType is not floating point.

fn (flags []Flag) get_floats(name string) ![]f64

get_floats returns the array of f64 value argument of the flag specified in name. get_floats returns an error if the FlagType is not floating point.

fn (flags []Flag) get_string(name string) !string

get_string returns the string value argument of the flag specified in name. get_string returns an error if the FlagType is not string.

fn (flags []Flag) get_strings(name string) ![]string

get_strings returns the string value argument of the flag specified in name. get_strings returns an error if the FlagType is not string.

enum FlagType {
	bool
	int
	float
	string
	// If flag can set multiple time, use array type
	int_array
	float_array
	string_array
}

struct Command {
pub mut:
	name            string
	alias           string
	usage           string
	description     string
	man_description string
	version         string
	// group is the section title under which `--help` lists this sub-command
	// in its parent's command listing. Empty falls back to the default
	// `Commands:` section. The string is rendered verbatim followed by `:`
	// — capitalisation is the caller's responsibility. Groups appear in the
	// order their first member is declared, which can interact with
	// `sort_commands` (sorting may change which member of each group comes
	// first, hence which group is listed first).
	group string
	// examples lists invocations rendered under `Examples:` by `--help`.
	// Each entry is one line; a leading `$` is conventional but not required.
	examples []string
	// learn_more is rendered under the `Learn more:` section by `--help`.
	// Newlines split the block into separate lines.
	learn_more    string
	pre_execute   FnCommandCallback = unsafe { nil }
	execute       FnCommandCallback = unsafe { nil }
	post_execute  FnCommandCallback = unsafe { nil }
	disable_flags bool
	sort_flags    bool
	sort_commands bool
	parent        &Command = unsafe { nil }
	commands      []Command
	flags         []Flag
	required_args int
	args          []string
	posix_mode    bool
	defaults      struct {
	pub:
		help    Defaults = true
		man     Defaults = true
		version Defaults = true
	mut:
		parsed struct {
		mut:
			help    CommandFlag
			version CommandFlag
			man     CommandFlag
		}
	}
}

Command is a structured representation of a single command or chain of commands.

fn (mut cmd Command) add_command(command Command)

add_command adds command as a sub-command of this Command.

fn (mut cmd Command) add_commands(commands []Command)

add_commands adds the commands array of Commands as sub-commands.

fn (mut cmd Command) add_flag(flag Flag)

add_flag adds flag to this Command.

fn (mut cmd Command) add_flags(flags []Flag)

add_flags adds the array flags to this Command.

fn (cmd &Command) execute_help()

execute_help executes the callback registered for the -h/--help flag option.

fn (cmd &Command) execute_man()

execute_man executes the callback registered for the -man flag option.

fn (cmd &Command) full_name() string

full_name returns the full string representation of all commands int the chain.

fn (cmd &Command) help_message() string

help_message returns a generated help message as a string for the Command.

The output is composed of (each section is omitted when empty):

1. Usage: line
2. The description, if any
3. Flags: — flags defined on this command
4. Inherited flags: — flags propagated from any ancestor via Flag.global
5. One section per sub-command group; the group name is rendered as the user wrote it followed by :. Sub-commands without a group go under the default Commands: section.6. Examples: — Command.examples entries, one per line
6. Learn more: — the multi-line Command.learn_more field

fn (cmd &Command) is_root() bool

is_root returns true if this Command has no parents.

fn (cmd &Command) manpage() string

manpage returns a string containing the mdoc(7) manpage for this Command.

fn (mut cmd Command) parse(args []string)

parse parses the flags and commands from the given args into the Command.

fn (cmd &Command) root() Command

root returns the root Command of the command chain.

fn (mut cmd Command) setup()

setup ensures that all sub-commands of this Command is linked as a chain.

fn (cmd &Command) str() string

str returns the string representation of the Command.

fn (cmd &Command) version() string

version returns a generated version string for the Command.

struct CommandFlag {
pub mut:
	command bool = true
	flag    bool = true
}

struct Flag {
pub mut:
	flag FlagType
	// Name of flag
	name string
	// Like short option
	abbrev string
	// Description of flag
	description string
	// If the flag is added to this command and to all subcommands
	global bool
	// If flag is required
	required bool
	// Default value if no value provide by command line
	default_value []string = []
mut:
	// Set true if flag found.
	found bool
	// Value of flag
	value []string = []
}

Flag holds information for a command line flag. (flags are also commonly referred to as "options" or "switches") These are typically denoted in the shell by a short form -f and/or a long form --flag

fn (flag &Flag) get_bool() !bool

get_bool returns true if the flag is set. get_bool returns an error if the FlagType is not boolean.

fn (flag &Flag) get_int() !int

get_int returns the int value argument of the flag. get_int returns an error if the FlagType is not integer.

fn (flag &Flag) get_ints() ![]int

get_ints returns the array of int value argument of the flag specified in name. get_ints returns an error if the FlagType is not integer.

fn (flag &Flag) get_float() !f64

get_float returns the f64 value argument of the flag. get_float returns an error if the FlagType is not floating point.

fn (flag &Flag) get_floats() ![]f64

get_floats returns the f64 value argument of the flag. get_floats returns an error if the FlagType is not floating point.

fn (flag &Flag) get_string() !string

get_string returns the string value argument of the flag. get_string returns an error if the FlagType is not string.

fn (flag &Flag) get_strings() ![]string

get_strings returns the array of string value argument of the flag. get_strings returns an error if the FlagType is not string.

fn (mut flag Flag) parse(args []string, posix_mode bool) ![]string

parse parses flag values from arguments and return an array of arguments with all consumed elements removed.