sflag

README

sflag

Cmdline arg parser using struct syntax

Documentation

Overview

Package sflag is a commandline arguments parser using struct syntax

Usage

var opt = struct {
    Usage       string  "sflags demonstrator"
    SomeFile    string  "contains the something      | /dev/null"
    IQ          int     "do not inflate              | 42"
    GDP         float64 "in Vietnamese Dong          | 42000000000000000000000000.0"
    Age         int64   "in milliseconds since epoch | 42000000000000"
    SomeCommand string  "! is command that might contain pipe char ! 'yes | head'"
    Verbose     bool    "Bool flags require use of an equals sign syntax (i.e. \"var=value\") to be unambiguous		| false"
    OutData     string  " must be writable | /an/output/file"
    Args	[]string
    Foo	        *int			// sflag will ignore both member and tag since it is initialized to non-nil pointer
    Bar	        *int    "bar"	        // sflag will not look for default value in this tag, since it will be a nil pointer
    Baz_        int     "Set by --baz, not --Baz             | 42"
    ignoreMe    string			// sflag will ignore low-case members
}{}

func Example() {
     foo	:= 1;
     opt.Foo	= &foo		// sflag will ignore this variable since it is a non-nil pointer

     sflag.Parse(&opt)
     fmt.Println("SomeFile=", opt.SomeFile)
     fmt.Println("Age=", opt.Age)
     fmt.Println("IQ=", opt.IQ)
     fmt.Println("GDP=", opt.GDP)
     fmt.Println("SomeCommand=", opt.SomeCommand)
     fmt.Println("Verbose=", opt.Verbose)
     if opt.Bar != nil {
     	fmt.Println("Bar=", *opt.Bar)
     } else {
	fmt.Println("Bar was not set")
     }
     fmt.Println("baz=", opt.Baz_)
     for ii, aa := range opt.Args {
     	fmt.Println("arg num", ii, ":", aa)
     }
}

Package sflag is a flag package variant that is 100% DRY, free of fugly pointer syntax and uses clean struct syntax.

Implementation makes use of reflection and struct tags, in manner similar to previously published flag variants.

Index

• func Parse(ss interface{})
• func Parse2(ss interface{})

Functions

func Parse

func Parse(ss interface{})

Parse iterates through the members of the struct. Notes:

Members are set up for std flag package to do the actual parsing, using type obtained via reflection and info from struct tag for usage and default setting.
Normally, the rightmost pipe char in the tag is used to delineate between Description (on left) and Default value (on right).
(You can override delineator to the first char of the tag (after eliminating leading whitespace) if such char is not alphabetic).
Fields with no tag or whitespace-only tags are ignored.
Non-nil pointer fields are ignored.
Nil pointer fields will be left nil if that flag is not set on commandline (and the tag is not parsed for a default value).
Flags starting with lowercase letter require that the coresponding member ends in single underscore.
Provide string member Usage initialized to brief program description.  Parse will append member descriptions to that string.
Provide []string member Args if you want to want to retrieve unconsumed flags.
Initialize []string member Args to the string array you want to parse instead of os.Args[1:].

func Parse2

func Parse2(ss interface{})

Parse2 is identical to Parse, except panics if there is both (1) a boolean flag and (2) a standalone true/false argument. It reminds you to use "--Foo=true" syntax (instead of "--Foo true" which would terminate the stdlib's flag processing for bool flag Foo, which is considered set by its presence alone). The downside of using this func is that unrelated presence of true/false results in progam panic.