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(help_cmd Command) !

print_help_for_command outputs the help message of help_cmd.

fn print_manpage_for_command(man_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.

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.