setting

README

Example Setting

Overview

This example demos the use of the setting function where a variable has a default value that can be overridden by an environment variable which can be overridden by a command line argument.

It demonstrates the following szargs functions:

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

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

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

// NextUint removes and returns the next argument from the argument list,
// parsing it as an unsigned integer.
// 
// If no arguments remain, or if the value has invalid syntax or is out of
// range for a uint, an error is registered.
// 
// Returns the next argument value parsed as a uint.
func (args *Args) NextUint(name, desc string) uint

// 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 message based on the parsed arguments.
func (args *Args) Usage() string

Contents

• Source (main.go)
  • Example: PASS: Use Default
  • Example: PASS: Use Env
  • Example: PASS: Use Flag
  • Example: FAIL: Extra Unknown Argument

Source

The source used for this example. It simply defines a new szargs.Arg object, then defines a setting option. Finally the Done function is called to insure that no more arguments exist in the list.

cat ./main.go

// Package main implements a simple example of using szargs.
//
//nolint:forbidigo // OK to print to os.Stdout.
package main

import (
    "fmt"
    "os"

    "github.com/dancsecs/szargs"
)

func mainSetEnv() {
    _ = os.Setenv("ENV_SZARGS_EXAMPLE_SETTING_TEMP", "f")

    main()
}

func main() {
    args := szargs.New(
        "A simple demo of a setting.",
        os.Args,
    )

    temp := args.SettingOption(
        "[-t | --temp {c,f}]",
        "ENV_SZARGS_EXAMPLE_SETTING_TEMP",
        "c",
        []string{
            "c",
            "f",
        },
        "Temperature measurement to use (celsius or fahrenheit).",
    )

    args.Done() // All arguments should have consumed.

    if args.HasErr() {
        fmt.Fprintf(os.Stderr, "Error: %v\n\n%s\n", args.Err(), args.Usage())
    } else {
        fmt.Printf("Using '%s' for temperatures.", temp)
    }
}

Top of Page -- Szargs Contents

PASS: Use Default

---

go run .

Using 'c' for temperatures.

---

Top of Page -- Szargs Contents

PASS: Use Env

---

go run ./mainSetEnv

Using 'f' for temperatures.

Top of Page -- Szargs Contents

PASS: Use Flag

---

go run . -t f

Using 'f' for temperatures.

---

Top of Page -- Szargs Contents

FAIL: Extra Unknown Argument

The error is generated by the args.Done() statement causing both the error and a usage statement to be returned.

---

go run . extraUnknownArgument

Error: unexpected argument: [extraUnknownArgument]

setting
A simple demo of a setting.

Usage: setting [-t | --temp {c,f}]

[-t | --temp {c,f}]
Temperature measurement to use (celsius or fahrenheit).

---

Top of Page -- Szargs Contents

Documentation

Overview

Package main implements a simple example of using szargs.