bitfield,flag: document the remaining functions

pull/12511/head
Delyan Angelov 2021-11-18 20:14:59 +02:00
parent 96554fad71
commit 24ba660367
No known key found for this signature in database
GPG Key ID: 66886C0F12D595ED
2 changed files with 43 additions and 11 deletions

View File

@ -338,6 +338,7 @@ pub fn (instance BitField) clone() BitField {
return output return output
} }
// == compares 2 bitfields, and returns true when they are equal
pub fn (a BitField) == (b BitField) bool { pub fn (a BitField) == (b BitField) bool {
if a.size != b.size { if a.size != b.size {
return false return false

View File

@ -30,6 +30,11 @@ struct NoArgsExpectedError {
code int code int
} }
// free frees the resources associated with a given Flag
// It is called automatically when -autofree is used.
// It should be called manually in functions that use Flags,
// and are marked with [manualfree]. After you call .free() on
// a Flag instance, you should NOT use that instance any more.
[unsafe] [unsafe]
fn (mut f Flag) free() { fn (mut f Flag) free() {
unsafe { unsafe {
@ -39,12 +44,14 @@ fn (mut f Flag) free() {
} }
} }
// str returns a string representation of the given Flag
pub fn (f Flag) str() string { pub fn (f Flag) str() string {
return '' + ' flag:\n' + ' name: $f.name\n' + return '' + ' flag:\n' + ' name: $f.name\n' +
' abbr: `$f.abbr.ascii_str()`\n' + ' usag: $f.usage\n' + ' abbr: `$f.abbr.ascii_str()`\n' + ' usag: $f.usage\n' +
' desc: $f.val_desc' ' desc: $f.val_desc'
} }
// str returns a string representation of the given array of Flags
pub fn (af []Flag) str() string { pub fn (af []Flag) str() string {
mut res := []string{} mut res := []string{}
res << '\n []Flag = [' res << '\n []Flag = ['
@ -55,7 +62,12 @@ pub fn (af []Flag) str() string {
return res.join('\n') return res.join('\n')
} }
// // FlagParser is the heart of the `flag` module.
// That structure is created with `mut parser := flag.new_flag_parser(os.args)`,
// The returned instance can be further customised by calling various methods,
// for specifying the accepted options and their values. The user should finally
// call `rest := parser.finalize() ?` to get the rest of the non optional arguments
// (if there are any left).
pub struct FlagParser { pub struct FlagParser {
pub: pub:
original_args []string // the original arguments to be parsed original_args []string // the original arguments to be parsed
@ -80,6 +92,11 @@ pub mut:
footers []string // when set, --help will display all the collected footers at the bottom. footers []string // when set, --help will display all the collected footers at the bottom.
} }
// free frees the resources allocated for the given FlagParser instance.
// It should be called manually in functions that use it, and that are
// marked with `[manualfree]`, otherwise, it is called automatically
// in programs, compiled with `-autofree`. NB: you should NOT use the
// instance over which you have called .free() for anything after the call.
[unsafe] [unsafe]
fn (mut f FlagParser) free() { fn (mut f FlagParser) free() {
unsafe { unsafe {
@ -107,7 +124,7 @@ pub const (
max_args_number = 4048 max_args_number = 4048
) )
// create a new flag set for parsing command line arguments // new_flag_parser - create a new flag parser for the given args
pub fn new_flag_parser(args []string) &FlagParser { pub fn new_flag_parser(args []string) &FlagParser {
original_args := args.clone() original_args := args.clone()
idx_dashdash := args.index('--') idx_dashdash := args.index('--')
@ -418,17 +435,18 @@ pub fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?str
return res return res
} }
// defining and parsing a string flag // string defines and parses a string flag/option.
// if defined // If that flag is given as an option, then the parsed
// the value is returned (string) // value is returned as a string. Otherwise, the default
// else // value is returned. This version supports abbreviations.
// the default value is returned
// version with abbr
pub fn (mut fs FlagParser) string(name string, abbr byte, sdefault string, usage string) string { pub fn (mut fs FlagParser) string(name string, abbr byte, sdefault string, usage string) string {
value := fs.string_opt(name, abbr, usage) or { return sdefault } value := fs.string_opt(name, abbr, usage) or { return sdefault }
return value return value
} }
// limit_free_args_to_at_least restricts the list of free arguments (non options) to be
// at least `n` in length. If the user gives less free arguments to the program,
// the parser will return an error.
pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ? { pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ? {
if n > flag.max_args_number { if n > flag.max_args_number {
return error('flag.limit_free_args_to_at_least expect n to be smaller than $flag.max_args_number') return error('flag.limit_free_args_to_at_least expect n to be smaller than $flag.max_args_number')
@ -439,6 +457,9 @@ pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ? {
fs.min_free_args = n fs.min_free_args = n
} }
// limit_free_args_to_exactly restricts the list of free arguments (non options) to be
// at exactly `n` in length. If the user gives more or less free arguments to the program,
// the parser will return an error.
pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int) ? { pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int) ? {
if n > flag.max_args_number { if n > flag.max_args_number {
return error('flag.limit_free_args_to_exactly expect n to be smaller than $flag.max_args_number') return error('flag.limit_free_args_to_exactly expect n to be smaller than $flag.max_args_number')
@ -450,8 +471,9 @@ pub fn (mut fs FlagParser) limit_free_args_to_exactly(n int) ? {
fs.max_free_args = n fs.max_free_args = n
} }
// this will cause an error in finalize() if free args are out of range // limit_free_args restricts the list of free arguments (non options) to be between
// (min, ..., max) // `min` and `max` in length. If the user gives more or less free arguments to the program,
// the parser will return an error.
pub fn (mut fs FlagParser) limit_free_args(min int, max int) ? { pub fn (mut fs FlagParser) limit_free_args(min int, max int) ? {
if min > max { if min > max {
return error('flag.limit_free_args expect min < max, got $min >= $max') return error('flag.limit_free_args expect min < max, got $min >= $max')
@ -460,11 +482,15 @@ pub fn (mut fs FlagParser) limit_free_args(min int, max int) ? {
fs.max_free_args = max fs.max_free_args = max
} }
// arguments_description sets the description field of the parser.
// This field is usually shown when the `--help` option is given to the program.
pub fn (mut fs FlagParser) arguments_description(description string) { pub fn (mut fs FlagParser) arguments_description(description string) {
fs.args_description = description fs.args_description = description
} }
// collect all given information and // usage returns a nicely formatted usage screen, containing all the
// possible options, as well as the description for the program.
// That screen is usually shown when the `--help` option is given to the program.
pub fn (fs FlagParser) usage() string { pub fn (fs FlagParser) usage() string {
positive_min_arg := (fs.min_free_args > 0) positive_min_arg := (fs.min_free_args > 0)
positive_max_arg := (fs.max_free_args > 0 && fs.max_free_args != flag.max_args_number) positive_max_arg := (fs.max_free_args > 0 && fs.max_free_args != flag.max_args_number)
@ -546,6 +572,8 @@ pub fn (fs FlagParser) usage() string {
return use.join('\n').replace('- ,', ' ') return use.join('\n').replace('- ,', ' ')
} }
// find_existing_flag looks up the given flag by name, and returns
// it, if it was found in the FlagParser. If it was not, it returns an error.
fn (mut fs FlagParser) find_existing_flag(fname string) ?Flag { fn (mut fs FlagParser) find_existing_flag(fname string) ?Flag {
for f in fs.flags { for f in fs.flags {
if f.name == fname { if f.name == fname {
@ -555,6 +583,9 @@ fn (mut fs FlagParser) find_existing_flag(fname string) ?Flag {
return error('no such flag') return error('no such flag')
} }
// handle_builtin_options handles the default behaviour of the very frequently
// given options: `--help` and `--version`.
// You can change/customise that, by defining your own options with these names.
fn (mut fs FlagParser) handle_builtin_options() { fn (mut fs FlagParser) handle_builtin_options() {
mut show_version := false mut show_version := false
mut show_help := false mut show_help := false