cli #

Description

cli is a command line option parser, that supports declarative subcommands, each having 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'
                execute: fn (cmd cli.Command) ! {
                    println('hello subcommand')
                    return
                }
            },
        ]
    }
    app.setup()
    app.parse(os.args)
}

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 (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
	usage           string
	description     string
	man_description string
	version         string
	pre_execute     FnCommandCallback = unsafe { nil }
	execute         FnCommandCallback = unsafe { nil }
	post_execute    FnCommandCallback = unsafe { nil }
	disable_help    bool @[deprecated: 'use defaults.help instead'; deprecated_after: '2024-06-31']
	disable_man     bool @[deprecated: 'use defaults.man instead'; deprecated_after: '2024-06-31']
	disable_version bool @[deprecated: 'use defaults.version instead'; deprecated_after: '2024-06-31']
	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_help 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.

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.