The flag
module helps command-line flag parsing.
Main features are:
-f
or '--flag' or '--stuff=things' or '--things stuff'.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())
}
const (
space = ' '
underline = '-----------------------------------------------'
max_args_number = 4048
)
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