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 TODO use INT_MAX some how

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 mut:
	args                    []string
	max_free_args           int
	flags                   []Flag
	application_name        string
	application_version     string
	application_description string
	min_free_args           int
	args_description        string
}

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)

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

fn (mut fs FlagParser) skip_executable()

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

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 (fs FlagParser) finalize() ?[]string

finalize argument parsing -> call after all arguments are defined all remaining arguments are returned in the same order they are defined on command line if additional flag are found (things starting with '--') an error is returned error handling is up to the application developer