From 24ba660367dfda9b283039e5eaef61470b64ea26 Mon Sep 17 00:00:00 2001 From: Delyan Angelov Date: Thu, 18 Nov 2021 20:14:59 +0200 Subject: [PATCH] bitfield,flag: document the remaining functions --- vlib/bitfield/bitfield.v | 1 + vlib/flag/flag.v | 53 +++++++++++++++++++++++++++++++--------- 2 files changed, 43 insertions(+), 11 deletions(-) diff --git a/vlib/bitfield/bitfield.v b/vlib/bitfield/bitfield.v index 35ac552801..fdabdc3e81 100644 --- a/vlib/bitfield/bitfield.v +++ b/vlib/bitfield/bitfield.v @@ -338,6 +338,7 @@ pub fn (instance BitField) clone() BitField { return output } +// == compares 2 bitfields, and returns true when they are equal pub fn (a BitField) == (b BitField) bool { if a.size != b.size { return false diff --git a/vlib/flag/flag.v b/vlib/flag/flag.v index 21f4731d87..3a779ca2a0 100644 --- a/vlib/flag/flag.v +++ b/vlib/flag/flag.v @@ -30,6 +30,11 @@ struct NoArgsExpectedError { 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] fn (mut f Flag) free() { 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 { return '' + ' flag:\n' + ' name: $f.name\n' + ' abbr: `$f.abbr.ascii_str()`\n' + ' usag: $f.usage\n' + ' desc: $f.val_desc' } +// str returns a string representation of the given array of Flags pub fn (af []Flag) str() string { mut res := []string{} res << '\n []Flag = [' @@ -55,7 +62,12 @@ pub fn (af []Flag) str() string { 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: 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. } +// 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] fn (mut f FlagParser) free() { unsafe { @@ -107,7 +124,7 @@ pub const ( 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 { original_args := args.clone() idx_dashdash := args.index('--') @@ -418,17 +435,18 @@ pub fn (mut fs FlagParser) string_opt(name string, abbr byte, usage string) ?str return res } -// defining and parsing a string flag -// if defined -// the value is returned (string) -// else -// the default value is returned -// version with abbr +// string defines and parses a string flag/option. +// If that flag is given as an option, then the parsed +// value is returned as a string. Otherwise, the default +// value is returned. This version supports abbreviations. 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 } 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) ? { 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') @@ -439,6 +457,9 @@ pub fn (mut fs FlagParser) limit_free_args_to_at_least(n int) ? { 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) ? { if n > 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 } -// this will cause an error in finalize() if free args are out of range -// (min, ..., max) +// limit_free_args restricts the list of free arguments (non options) to be between +// `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) ? { if 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 } +// 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) { 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 { positive_min_arg := (fs.min_free_args > 0) 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('- ,', ' ') } +// 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 { for f in fs.flags { if f.name == fname { @@ -555,6 +583,9 @@ fn (mut fs FlagParser) find_existing_flag(fname string) ?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() { mut show_version := false mut show_help := false