This larger example demos several aspects of using the szargs library. It performs one of two operations (specified in an optional positional argument) on a list of float64 values passed as flagged arguments. Further it uses a boolean count to set a verbose level to increase the chattiness of the program.
It demonstrates the following szargs functions:
// New creates a new Args object based in the arguments passed. The first
// element of the arguments must be the program name.
func New(programDesc string, args []string) *Args
// Count returns the number of times the flag appears.
func (args *Args) Count(flag, desc string) int
// ValuesFloat64 scans for repeated instances of the specified flag and parses
// the following values as 64 bit floating point numbers. The flags and values
// are removed from the argument list.
//
// If any flag lacks a following value, or if a value has invalid syntax or is
// out of range for a float64, an error is registered.
//
// Returns a slice of the parsed float64 values.
func (args *Args) ValuesFloat64(flag, desc string) []float64
// HasNext returns true if any arguments remain unabsorbed.
func (args *Args) HasNext() bool
// PushArg places the supplied argument to the end of the internal args list.
func (args *Args) PushArg(arg string)
// NextOption removes and returns the next argument from the argument list.
// The value must match one of the entries in validOptions.
//
// If no arguments remain, or if the value is not found in validOptions,
// an error is registered.
//
// Returns the next argument value.
func (args *Args) NextOption(name string, validOptions []string, desc string) string
// Done registers an error if there are any remaining arguments.
func (args *Args) Done()
// HasErr returns true if any errors have been encountered or registered.
func (args *Args) HasErr() bool
// Err returns any errors encountered or registered while parsing the
// arguments.
func (args *Args) Err() error
// Usage returns a usage messages representing the Args object. It is
// formatted to the lineWidth provided. A zero uses the defaultLineWidth
// while a negative value caused an effort to determine if writing to a
// terminal and if so using its width otherwise defaulting.
func (args *Args) Usage(lineWidth int) string- Source (main.go)
- Example: PASS: No Arguments
- Example: PASS: Just Operation Add
- Example: PASS: Just operation Average
- Example: PASS: One Number Defaulting To Add
- Example: PASS: Two Numbers Defaulting To Add
- Example: PASS: One Number Average
- Example: PASS: Two Number Average
- Example: PASS: Three Number Add
- Example: PASS: Three Number Average
- Example: FAIL: Extra Unknown Argument
- Example: FAIL: Invalid Operation
- Example: FAIL: Invalid Number
The sources used for this example are broken into three files as follows:
This defines the verbose processing.
cat ./verbose.gopackage main
import (
"fmt"
)
// Supported verbose levels.
const (
vAll = iota
vLv1
vLv2
vLv3
)
var verbose int //nolint:goCheckNoGlobals // Ok.
func sayPrintf(minLevel int, msgFormat string, msgArgs ...any) {
if verbose >= minLevel {
fmt.Printf(msgFormat, msgArgs...) //nolint:forbidigo // Ok.
}
}and this defines all of the processing to be performed if and only if the arguments are parsed without any errors.
cat ./process.gopackage main
func process(numbers []float64, operation string) {
sayPrintf(vLv1, "Verbose set to %d\n", verbose)
sayPrintf(vLv2, "Read in %d numbers\n", len(numbers))
sayPrintf(vLv2, "Operation: %s\n", operation)
sum := float64(0)
for i, n := range numbers {
sayPrintf(vLv3, "Number (%d): %f\n", i, n)
sum += n
}
if operation == "average" {
avg := float64(0)
if len(numbers) > 0 {
avg = sum / float64(len(numbers))
}
sayPrintf(vAll, "Avg: %f\n", avg)
} else {
sayPrintf(vAll, "Sum: %f\n", sum)
}
}finally the mainline where the arguments are parsed is defined as follows:
cat ./main.go// Package main implements a simple example of using a flag to provide a list
// of floating point numbers and returning the sum or average of the list.
package main
import (
"fmt"
"os"
"github.com/dancsecs/szargs"
)
const (
verboseFlag = "[-v | --verbose ...]"
verboseDesc = "The verbose level."
numberFlag = "[-n | --number float64 ...]"
numberDesc = "The numbers to act on."
operationName = "[operation]"
operationDesc = "The operation (add or average) defaulting to add."
)
// Example function being tested.
func main() {
args := szargs.New(
"A simple utility to add or average a number list.",
os.Args,
)
// How chatty should I be. Set the global value.
verbose = args.Count(verboseFlag, verboseDesc)
// Gather all of the number to operate on.
numbers := args.ValuesFloat64(numberFlag, numberDesc)
// Set to default if not present.
if !args.HasNext() {
args.PushArg("add")
}
operation := args.NextOption(
operationName,
[]string{
"add",
"average",
},
operationDesc,
)
args.Done()
// Report parsing errors or process the arguments.
if args.HasErr() {
fmt.Fprintf(os.Stderr, "Error: %v\n\n%s\n", args.Err(), args.Usage(0))
} else {
process(numbers, operation)
}
}Top of Page -- Szargs Contents
An empty list sums and averages to zero for simplicity. No error is reported.
go run .Sum: 0.000000
Top of Page -- Szargs Contents
go run . addSum: 0.000000
Top of Page -- Szargs Contents
go run . averageAvg: 0.000000
Top of Page -- Szargs Contents
go run . -n 1000Sum: 1000.000000
Top of Page -- Szargs Contents
go run . --number 1 -n 2Sum: 3.000000
Top of Page -- Szargs Contents
go run . --number 512 averageAvg: 512.000000
Top of Page -- Szargs Contents
go run . -n 100 -n 200 averageAvg: 150.000000
Top of Page -- Szargs Contents
go run . --number 23 --number 56 -n 22 addSum: 101.000000
Top of Page -- Szargs Contents
go run . -n 23 -n 56 -n 22 averageAvg: 33.666667
Top of Page -- Szargs Contents
go run . add extraUnknownArgumentError: unexpected argument: [extraUnknownArgument]
usage: average [-v | --verbose ...] [-n | --number float64 ...] [operation]
A simple utility to add or average a number list.
[-v | --verbose ...]
The verbose level.
[-n | --number float64 ...]
The numbers to act on.
[operation]
The operation (add or average) defaulting to add.
Top of Page -- Szargs Contents
go run . invalidOperationError: invalid option: 'invalidOperation' ([operation] must be one of [add average])
usage: average [-v | --verbose ...] [-n | --number float64 ...] [operation]
A simple utility to add or average a number list.
[-v | --verbose ...]
The verbose level.
[-n | --number float64 ...]
The numbers to act on.
[operation]
The operation (add or average) defaulting to add.
Top of Page -- Szargs Contents
go run . -n invalidNumberError: invalid float64: syntax: [-n | --number float64 ...]: 'invalidNumber'
usage: average [-v | --verbose ...] [-n | --number float64 ...] [operation]
A simple utility to add or average a number list.
[-v | --verbose ...]
The verbose level.
[-n | --number float64 ...]
The numbers to act on.
[operation]
The operation (add or average) defaulting to add.