flag #

The flag module helps command-line flag parsing. Main features are:

• parses flags like -f or '--flag' or '--stuff=things' or '--things stuff'.
• handles bool, int, float and string args.
• can print usage information listing all the declrared flags.
• handles unknown arguments as error.

Usage example:

module main

import os
import flag

fn main() {
    mut fp := flag.new_flag_parser(os.args)
    fp.application('flag_example_tool')
    fp.version('v0.0.1')
    fp.limit_free_args(0, 0) // comment this, if you expect arbitrary texts after the options
    fp.description('This tool is only designed to show how the flag lib is working')
    fp.skip_executable()
    an_int := fp.int('an_int', 0, 0o123, 'some int to define 0o123 is its default value')
    a_bool := fp.bool('a_bool', 0, false, 'some boolean flag. --a_bool will set it to true.')
    a_float := fp.float('a_float', 0, 1.0, 'some floating point value, by default 1.0 .')
    a_string := fp.string('a_string', `a`, 'no text', 'finally, some text with ' +
        ' `-a` as an abbreviation, so you can pass --a_string abc or just -a abc')
    additional_args := fp.finalize() or {
        eprintln(err)
        println(fp.usage())
        return
    }
    println('an_int: $an_int | a_bool: $a_bool | a_float: $a_float | a_string: "$a_string" ')
    println(additional_args.join_lines())
}

fn new_flag_parser(args []string) &FlagParser

create a new flag set for parsing command line arguments

fn (af []Flag) str() string

struct Flag {
pub:
	name     string
	abbr     byte
	usage    string
	val_desc string
}

data object storing information about a defined flag

fn (f Flag) str() string

struct FlagParser {
pub:
	original_args      []string
	idx_dashdash       int
	all_after_dashdash []string
pub mut:
	usage_examples []string

	default_help_label      string = 'display this help and exit'
	default_version_label   string = 'output version information and exit'
	args                    []string
	max_free_args           int
	flags                   []Flag
	application_name        string
	application_version     string
	application_description string
	min_free_args           int
	args_description        string
	allow_unknown_args      bool
	footers                 []string
}

fn (mut fs FlagParser) usage_example(example string)

usage_example - add an usage example All examples will be listed in the help screen. If you do not give any examples, then a default usage will be shown, based on whether the application takes options and expects additional parameters.

fn (mut fs FlagParser) footer(footer string)

add_footer - add a footnote, that will be shown at the bottom of the help screen.

fn (mut fs FlagParser) application(name string)

change the application name to be used in 'usage' output

fn (mut fs FlagParser) version(vers string)

change the application version to be used in 'usage' output

fn (mut fs FlagParser) description(desc string)

description appends to the application description lines, shown in the help/usage screen

fn (mut fs FlagParser) skip_executable()

in most cases you do not need the first argv for flag parsing

fn (mut fs FlagParser) allow_unknown_args()

allow_unknown_args - if your program has sub commands, that have their own arguments, you can call .allow_unknown_args(), so that the subcommand arguments (which generally are not known to your parent program), will not cause the validation in .finalize() to fail.

fn (mut fs FlagParser) bool_opt(name string, abbr byte, usage string) ?bool

bool_opt returns an optional that returns the value associated with the flag. In the situation that the flag was not provided, it returns null.

fn (mut fs FlagParser) bool(name string, abbr byte, bdefault bool, usage string) bool

defining and parsing a bool flag if defined the value is returned (true/false) else the default value is returned version with abbr TODO error handling for invalid string to bool conversion

fn (mut fs FlagParser) int_multi(name string, abbr byte, usage string) []int

int_multi returns all instances of values associated with the flags provided In the case that none were found, it returns an empty array.

fn (mut fs FlagParser) int_opt(name string, abbr byte, usage string) ?int

int_opt returns an optional that returns the value associated with the flag. In the situation that the flag was not provided, it returns null.

fn (mut fs FlagParser) int(name string, abbr byte, idefault int, usage string) int

defining and parsing an int flag if defined the value is returned (int) else the default value is returned version with abbr TODO error handling for invalid string to int conversion

fn (mut fs FlagParser) float_multi(name string, abbr byte, usage string) []f64

float_multi returns all instances of values associated with the flags provided In the case that none were found, it returns an empty array.

fn (mut fs FlagParser) float_opt(name string, abbr byte, usage string) ?f64

float_opt returns an optional that returns the value associated with the flag. In the situation that the flag was not provided, it returns null.

fn (mut fs FlagParser) float(name string, abbr byte, fdefault f64, usage string) f64

defining and parsing a float flag if defined the value is returned (float) else the default value is returned version with abbr TODO error handling for invalid string to float conversion

fn (mut fs FlagParser) string_multi(name string, abbr byte, usage string) []string

string_multi returns all instances of values associated with the flags provided In the case that none were found, it returns an empty array.

fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?string

string_opt returns an optional that returns the value associated with the flag. In the situation that the flag was not provided, it returns null.

fn (mut fs FlagParser) string(name string, abbr byte, sdefault string, usage string) string

defining and parsing a string flag if defined the value is returned (string) else the default value is returned version with abbr

fn (mut fs FlagParser) limit_free_args_to_at_least(n int)

fn (mut fs FlagParser) limit_free_args_to_exactly(n int)

fn (mut fs FlagParser) limit_free_args(min int, max int)

this will cause an error in finalize() if free args are out of range (min, ..., max)

fn (mut fs FlagParser) arguments_description(description string)

fn (fs FlagParser) usage() string

collect all given information and

fn (mut fs FlagParser) finalize() ?[]string

finalize - return all remaining arguments (non options). Call .finalize() after all arguments are defined. The remaining arguments are returned in the same order they are defined on the command line. If additional flags are found, i.e. (things starting with '--' or '-'), it returns an error.

fn (mut fs FlagParser) remaining_parameters() []string

remaining_parameters will return all remaining parameters. Call .remaining_parameters() AFTER you have defined all options that your program needs. remaining_parameters will also print any parsing errors and stop the program. Use .finalize() instead, if you want more control over the error handling.