module flag // module flag for command-line flag parsing // // - parsing flags like '--flag' or '--stuff=things' or '--things stuff' // - handles bool, int, float and string args // - is able to print usage // - handled unknown arguments as error // // Usage example: // // ```v // 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.0') // fp.description('This tool is only designed to show how the flag lib is working') // // fp.skip_executable() // // an_int := fp.int('an_int', 666, 'some int to define 666 is default') // a_bool := fp.bool('a_bool', false, 'some \'real\' flag') // a_float := fp.float('a_float', 1.0, 'also floats') // a_string := fp.string('a_string', 'no text', 'finally, some text') // // 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()) // } // ``` // data object storing information about a defined flag struct Flag { pub: name string // name as it appears on command line abbr byte // shortcut usage string // help message val_desc string // something like '' that appears in usage, // and also the default value, when the flag is not given } // struct FlagParser { pub mut: args []string // the arguments to be parsed flags []Flag // registered flags application_name string application_version string application_description string min_free_args int max_free_args int args_description string } const ( // used for formating usage message SPACE = ' ' UNDERLINE = '-----------------------------------------------' MAX_ARGS_NUMBER = 4048 ) // create a new flag set for parsing command line arguments // TODO use INT_MAX some how pub fn new_flag_parser(args []string) &FlagParser { return &FlagParser{args:args, max_free_args: MAX_ARGS_NUMBER} } // change the application name to be used in 'usage' output pub fn (fs mut FlagParser) application(n string) { fs.application_name = n } // change the application version to be used in 'usage' output pub fn (fs mut FlagParser) version(n string) { fs.application_version = n } // change the application version to be used in 'usage' output pub fn (fs mut FlagParser) description(n string) { fs.application_description = n } // in most cases you do not need the first argv for flag parsing pub fn (fs mut FlagParser) skip_executable() { fs.args.delete(0) } // private helper to register a flag fn (fs mut FlagParser) add_flag(n string, a byte, u, vd string) { fs.flags << Flag{ name: n, abbr: a, usage: u, val_desc: vd } } // private: general parsing a single argument // - search args for existence // if true // extract the defined value as string // else // return an (dummy) error -> argument is not defined // // - the name, usage are registered // - found arguments and corresponding values are removed from args list fn (fs mut FlagParser) parse_value(n string, ab byte) ?string { c := '--$n' for i, a in fs.args { if a == c || (a.len == 2 && a[1] == ab) { if fs.args.len > i+1 && fs.args[i+1].left(2) != '--' { val := fs.args[i+1] fs.args.delete(i+1) fs.args.delete(i) return val } else { panic('Missing argument for \'$n\'') } } else if a.len > c.len && c == a[..c.len] && a[c.len..c.len+1] == '=' { val := a[c.len+1..] fs.args.delete(i) return val } } return error('parameter \'$n\' not found') } // special parsing for bool values // see also: parse_value // // special: it is allowed to define bool flags without value // -> '--flag' is parsed as true // -> '--flag' is equal to '--flag=true' fn (fs mut FlagParser) parse_bool_value(n string, ab byte) ?string { c := '--$n' for i, a in fs.args { if a == c || (a.len == 2 && a[1] == ab) { if fs.args.len > i+1 && (fs.args[i+1] in ['true', 'false']) { val := fs.args[i+1] fs.args.delete(i+1) fs.args.delete(i) return val } else { val := 'true' fs.args.delete(i) return val } } else if a.len > c.len && c == a[..c.len] && a[c.len..c.len+1] == '=' { val := a[c.len+1..] fs.args.delete(i) return val } } return error('parameter \'$n\' not found') } // defining and parsing a bool flag // if defined // the value is returned (true/false) // else // the default value is returned // version with abbreviation //TODO error handling for invalid string to bool conversion pub fn (fs mut FlagParser) bool_(n string, a byte, v bool, u string) bool { fs.add_flag(n, a, u, ':'+v.str()) parsed := fs.parse_bool_value(n, a) or { return v } return parsed == 'true' } // defining and parsing a bool flag // if defined // the value is returned (true/false) // else // the default value is returned //TODO error handling for invalid string to bool conversion pub fn (fs mut FlagParser) bool(n string, v bool, u string) bool { return fs.bool_(n, `\0`, v, u) } // defining and parsing an int flag // if defined // the value is returned (int) // else // the default value is returned // version with abbreviation //TODO error handling for invalid string to int conversion pub fn (fs mut FlagParser) int_(n string, a byte, i int, u string) int { fs.add_flag(n, a, u, ':$i') parsed := fs.parse_value(n, a) or { return i } return parsed.int() } // defining and parsing an int flag // if defined // the value is returned (int) // else // the default value is returned //TODO error handling for invalid string to int conversion pub fn (fs mut FlagParser) int(n string, i int, u string) int { return fs.int_(n, `\0`, i, u) } // defining and parsing a float flag // if defined // the value is returned (float) // else // the default value is returned // version with abbreviation //TODO error handling for invalid string to float conversion pub fn (fs mut FlagParser) float_(n string, a byte, f f32, u string) f32 { fs.add_flag(n, a, u, ':$f') parsed := fs.parse_value(n, a) or { return f } return parsed.f32() } // defining and parsing a float flag // if defined // the value is returned (float) // else // the default value is returned //TODO error handling for invalid string to float conversion pub fn (fs mut FlagParser) float(n string, f f32, u string) f32 { return fs.float_(n, `\0`, f, u) } // defining and parsing a string flag // if defined // the value is returned (string) // else // the default value is returned // version with abbreviation pub fn (fs mut FlagParser) string_(n string, a byte, v, u string) string { fs.add_flag(n, a, u, ':$v') parsed := fs.parse_value(n, a) or { return v } return parsed } // defining and parsing a string flag // if defined // the value is returned (string) // else // the default value is returned pub fn (fs mut FlagParser) string(n, v, u string) string { return fs.string_(n, `\0`, v, u) } pub fn (fs mut FlagParser) limit_free_args_to_at_least(n int) { if n > MAX_ARGS_NUMBER { panic('flag.limit_free_args_to_at_least expect n to be smaller than $MAX_ARGS_NUMBER') } if n <= 0 { panic('flag.limit_free_args_to_at_least expect n to be a positive number') } fs.min_free_args = n } pub fn (fs mut FlagParser) limit_free_args_to_exactly(n int) { if n > MAX_ARGS_NUMBER { panic('flag.limit_free_args_to_exactly expect n to be smaller than $MAX_ARGS_NUMBER') } if n < 0 { panic('flag.limit_free_args_to_exactly expect n to be a non negative number') } fs.min_free_args = n fs.max_free_args = n } // this will cause an error in finalize() if free args are out of range // (min, ..., max) pub fn (fs mut FlagParser) limit_free_args(min, max int) { if min > max { panic('flag.limit_free_args expect min < max, got $min >= $max') } fs.min_free_args = min fs.max_free_args = max } pub fn (fs mut FlagParser) arguments_description(description string){ fs.args_description = description } // collect all given information and pub fn (fs FlagParser) usage() string { positive_min_arg := ( fs.min_free_args > 0 ) positive_max_arg := ( fs.max_free_args > 0 && fs.max_free_args != MAX_ARGS_NUMBER ) no_arguments := ( fs.min_free_args == 0 && fs.max_free_args == 0 ) mut adesc := if fs.args_description.len > 0 { fs.args_description } else { '[ARGS]' } if no_arguments { adesc = '' } mut use := '' use += '$fs.application_name $fs.application_version\n' use += '$UNDERLINE\n' use += 'Usage: ${fs.application_name} [options] $adesc\n' use += '\n' if fs.application_description != '' { use += 'Description:\n' use += '$fs.application_description' use += '\n\n' } // show a message about the [ARGS]: if positive_min_arg || positive_max_arg || no_arguments { if no_arguments { use += 'This application does not expect any arguments\n\n' goto end_of_arguments_handling } mut s:= []string if positive_min_arg { s << 'at least $fs.min_free_args' } if positive_max_arg { s << 'at most $fs.max_free_args' } if positive_min_arg && positive_max_arg && fs.min_free_args == fs.max_free_args { s = ['exactly $fs.min_free_args'] } sargs := s.join(' and ') use += 'The arguments should be $sargs in number.\n\n' } end_of_arguments_handling: if fs.flags.len > 0 { use += 'Options:\n' for f in fs.flags { flag_desc := ' --$f.name $f.val_desc' space := if flag_desc.len > SPACE.len-2 { '\n$SPACE' } else { SPACE[flag_desc.len..] } abbr_desc := if f.abbr == `\0` { '' } else { ' -${tos(f.abbr, 1)}\n' } use += '${abbr_desc}${flag_desc}${space}${f.usage}\n' } } return use } // 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 pub fn (fs FlagParser) finalize() ?[]string { for a in fs.args { if a.len >= 2 && a[..2] == '--' { return error('Unknown argument \'${a[2..]}\'') } } if fs.args.len < fs.min_free_args && fs.min_free_args > 0 { return error('Expected at least ${fs.min_free_args} arguments, but given $fs.args.len') } if fs.args.len > fs.max_free_args && fs.max_free_args > 0 { return error('Expected at most ${fs.max_free_args} arguments, but given $fs.args.len') } if fs.args.len > 0 && fs.max_free_args == 0 && fs.min_free_args == 0 { return error('Expected no arguments, but given $fs.args.len') } return fs.args }