Package szargs

Overview

package szargs

Package szargs provides a minimal and consistent interface for retrieving settings from command-line arguments ([]string) and environment variables.

It supports three types of arguments:

• Flagged: Identified by a single dash (e.g., "-v") for short flags, or a double dash (e.g., "--dir") for long-form flags. Flags may be standalone booleans or followed by a value.
• Positional: Identified by their order in the argument list after all flagged arguments have been processed.
• Settings: A composite configuration mechanism that combines a default value, an environment variable, and a flagged argument—allowing each to override the previous in precedence: default < env < flag.

The package includes built-in parsers for standard Go data types.

Usage centers around the Args type, created using:

szargs.New(programDesc string, programArgs []string)

The programArgs slice must include the program name as the first element; this is ignored during argument parsing.

After retrieving all relevant arguments, the Args.Done() method must be called to report an error if any unprocessed arguments remain.

This utility reflects a preference for simplicity and clarity in tooling. If it helps your project flow a little more smoothly, it's done its job.

Dedication

This project is dedicated to Reem. Your brilliance, courage, and quiet strength continue to inspire me. Every line is written in gratitude for the light and hope you brought into my life.

NOTE: Documentation reviewed and polished with the assistance of ChatGPT from OpenAI.

---

Contents

• Usage

  • Example: Average
    • Description: Calculates the average of input values.

• Boolean Flags

  • Example: Boolean Is
    • Description: Demonstrates use of single boolean flag.
  • Example: Boolean Count
    • Description: Demonstrates use of counting multiple boolean flags.

• Value Flagged Arguments

  • Example: Flagged Value
    • Description: Demonstrates use of typed flagged arguments.

• Value Flagged Slices

  • Example: Flagged Values
    • Description: Demonstrates use of multiple typed flagged arguments.

• Positional Arguments

  • Example: Next
    • Description: Demonstrates use of positional arguments.

• Settings

  • Example: Settings
    • Description: Demonstrates use of settings with environment overrides.

Usage

Generally the flow of argument extraction proceeds as follows:

func main() {
  // Create the args object with a program description (that will be used in
  // the Usage message) and the system arguments.  These will be copied
  // leaving the original os.Args untouched.
  args := szargs.New(
        "A simple demo of values flag.",
        os.Args,
    )

  // Flagged arguments are then extracted using various methods defined on the
  // args object.

  verbose := args.Count("[-v | --verbose ...]","The verbose level.")
  lines := args.Value("[-n | --num numOfLines]","Number of lines to display.")

  // Positional arguments are then extracted.
  file := args.Next("filename","The file to display the lines.")

  // All expected arguments have now been extracted.
  args.Done()

  if args.HasErr() {
    //Report any errors and optionally providing a Usage message.
    fmt.Fprintf(os.Stderr, "Error: %v\n\n%s\n", args.Err(), args.Usage())
  } else {
    // Process with the arguments.
  }
}

General functions operating on the state of the szargs object can be divided into three categories as follows:

Relating to errors:

// HasErr returns true if any errors have been encountered or registered.
func (args *Args) HasErr() bool

// PushErr registers the provided error if not nil to the Args error stack.
func (args *Args) PushErr(err error)

// Err returns any errors encountered or registered while parsing the
// arguments.
func (args *Args) Err() error

Relating to the raw argument list:

// 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)

// Args returns a copy of the current argument list.
func (args *Args) Args() []string

And general reporting and processing:

// Usage returns a usage message based on the parsed arguments.
//        /*
//        # Usage
// 
//        Golang to 'github' markdown.
// 
//            gotomd [options] [path ...]
// 
//            [-v | --verbose ...]
//                Provide more information when processing.
// 
//        */
func (args *Args) Usage() string

// Done registers an error if there are any remaining arguments.
func (args *Args) Done()

A working example can be found in the example directory as described here:

• Example: Average

Contents

Boolean Flags

Boolean flags are defined by their presence only. If they are present then they are true and/or counted. If not present then they are considered false. There are two methods that operate with boolean flags as follows:

// Is returns true if the flag is present one and only one time.
func (args *Args) Is(flag, desc string) bool

// Count returns the number of times the flag appears.
func (args *Args) Count(flag, desc string) int

• Example: Boolean Is
• Example: Boolean Count

Contents

Value Flagged Arguments

A flagged argument has two components: the flag followed by the value. It may only appear once in the argument list. The basic string functions are:

// ValueString scans for a specific flagged argument and captures its
// following value as a string. The flag and its value are removed from the
// argument list.
// 
// If the flag appears more than once or lacks a following value, an error is
// registered.
// 
// Returns the string value and a boolean indicating whether the flag was
// found.
func (args *Args) ValueString(flag, desc string) (string, bool)

// ValueOption scans for a specific flagged argument (e.g., "--mode value")
// and captures its associated value. The flag and its value are removed from
// the argument list.
// 
// If the flag appears more than once, or if it lacks a following value, an
// error is registered. If the value is not found in the provided list of
// validOptions, an error is also registered.
// 
// Returns the value and a boolean indicating whether the flag was found.
func (args *Args) ValueOption(flag string, validOptions []string, desc string) (string, bool)

with numeric versions for basic go data types

func (args *Args) ValueFloat64(flag, desc string) (float64, bool)
func (args *Args) ValueFloat32(flag, desc string) (float32, bool)
func (args *Args) ValueInt64(flag, desc string) (int64, bool)
func (args *Args) ValueInt32(flag, desc string) (int32, bool)
func (args *Args) ValueInt16(flag, desc string) (int16, bool)
func (args *Args) ValueInt8(flag, desc string) (int8, bool)
func (args *Args) ValueInt(flag, desc string) (int, bool)
func (args *Args) ValueUint64(flag, desc string) (uint64, bool)
func (args *Args) ValueUint32(flag, desc string) (uint32, bool)
func (args *Args) ValueUint16(flag, desc string) (uint16, bool)
func (args *Args) ValueUint8(flag, desc string) (uint8, bool)
func (args *Args) ValueUint(flag, desc string) (uint, bool)

Contents

Value Flagged Slices

A flagged argument has two components: the flag followed by the value. Multiple instances may be provided with all the values collected and returned in a slice. The basic string functions are:

// ValuesString scans for repeated instances of the specified flag and
// captures the following values as a slice of strings. The flags and values
// are removed from the argument list.
// 
// If any instance of the flag lacks a following value, an error is
// registered.
// 
// Returns a slice of the captured string values.
func (args *Args) ValuesString(flag, desc string) []string

// ValuesOption scans for repeated instances of the specified flag and
// captures the following values. Each value must appear in the provided list
// of validOptions. The flags and values are removed from the argument list.
// 
// If any flag lacks a following value, or if a value is not found in
// validOptions, an error is registered.
// 
// Returns a slice of the captured values.
func (args *Args) ValuesOption(flag string, validOptions []string, desc string) []string

with numeric versions for basic go data types

func (args *Args) ValuesFloat64(flag, desc string) []float64
func (args *Args) ValuesFloat32(flag, desc string) []float32
func (args *Args) ValuesInt64(flag, desc string) []int64
func (args *Args) ValuesInt32(flag, desc string) []int32
func (args *Args) ValuesInt16(flag, desc string) []int16
func (args *Args) ValuesInt8(flag, desc string) []int8
func (args *Args) ValuesInt(flag, desc string) []int
func (args *Args) ValuesUint64(flag, desc string) []uint64
func (args *Args) ValuesUint32(flag, desc string) []uint32
func (args *Args) ValuesUint16(flag, desc string) []uint16
func (args *Args) ValuesUint8(flag, desc string) []uint8
func (args *Args) ValuesUint(flag, desc string) []uint

Contents

Positional Arguments

A positional argument depends on its location in the argument list. Since flagged arguments are not automatically distinguished from positional ones, it is recommended to extract all flagged arguments first—before retrieving positional ones. The basic string functions are:

// NextString removes and returns the next argument from the argument list.
// 
// If no arguments remain, an error is registered.
// 
// Returns the next argument value as a string.
func (args *Args) NextString(name, desc string) 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

with numeric versions for basic go data types

func (args *Args) NextFloat64(name, desc string) float64
func (args *Args) NextFloat32(name, desc string) float32
func (args *Args) NextInt64(name, desc string) int64
func (args *Args) NextInt32(name, desc string) int32
func (args *Args) NextInt16(name, desc string) int16
func (args *Args) NextInt8(name, desc string) int8
func (args *Args) NextInt(name, desc string) int
func (args *Args) NextUint64(name, desc string) uint64
func (args *Args) NextUint32(name, desc string) uint32
func (args *Args) NextUint16(name, desc string) uint16
func (args *Args) NextUint8(name, desc string) uint8
func (args *Args) NextUint(name, desc string) uint

Contents

Settings

A setting implements an argument that has a default that can be overridden by an system environment variable which can be overridden by a flagged value. The basic string functions are:

// SettingString returns a configuration value based on a default,
// optionally overridden by an environment variable, and further overridden
// by a flagged command-line argument.
// 
// Returns the final selected string value.
func (args *Args) SettingString(flag, env, def, desc string) string

// SettingOption returns a configuration value based on a default,
// optionally overridden by an environment variable, and further overridden
// by a flagged command-line argument.
// 
// If the final value is not found in the list of validOptions,
// an error is registered.
// 
// Returns the final selected value.
func (args *Args) SettingOption(flag, env string, def string, validOptions []string, desc string) string

// SettingIs returns true if a specified environment variable is set to a
// truthy value, or if a corresponding boolean command-line flag is present.
// 
// Unlike other Setting methods, there is no default.
// 
// The environment variable is considered true if it is set to one of: "",
// "T", "Y", "TRUE", "YES", "ON" or "1" (case-insensitive). Any other value is
// considered false.
// 
// The command-line flag override takes no value—its presence alone indicates
// true.
// 
// Returns the resulting boolean value.
func (args *Args) SettingIs(flag, env string, desc string) bool

with numeric versions for basic go data types

func (args *Args) SettingFloat64(flag, env string, def float64, desc string) float64
func (args *Args) SettingFloat32(flag, env string, def float32, desc string) float32
func (args *Args) SettingInt64(flag, env string, def int64, desc string) int64
func (args *Args) SettingInt32(flag, env string, def int32, desc string) int32
func (args *Args) SettingInt16(flag, env string, def int16, desc string) int16
func (args *Args) SettingInt8(flag, env string, def int8, desc string) int8
func (args *Args) SettingInt(flag, env string, def int, desc string) int
func (args *Args) SettingUint64(flag, env string, def uint64, desc string) uint64
func (args *Args) SettingUint32(flag, env string, def uint32, desc string) uint32
func (args *Args) SettingUint16(flag, env string, def uint16, desc string) uint16
func (args *Args) SettingUint8(flag, env string, def uint8, desc string) uint8
func (args *Args) SettingUint(flag, env string, def uint, desc string) uint

Contents