README
¶
flax
Package flax implements a helper for attaching flags to the fields of struct values.
Documentation
¶
Overview ¶
Package flax implements a helper for attaching flags to the fields of struct values.
Example ¶
package main
import (
"flag"
"fmt"
)
var flags struct {
Debug bool `flag:"debug,default=true,Enable debugging output"`
Text string `flag:"text,default=OK,Text to display"`
Rate float64 `flag:"rate,default=0.1,Rate of increase"`
Ignored int
}
func main() {
flag.Parse()
if flags.Debug {
fmt.Println(flags.Text, flags.Rate)
}
fmt.Println(flags.Ignored)
}
Output: OK 0.1 0
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MustBind ¶
MustBind binds the flaggable fields of v to fs, or panics. The concrete type of v must be a pointer to a value of struct type. This function is intended for use in program initialization; callers who need to check errors should call Check and Fields.Bind.
func MustBindAll ¶
MustBindAll is shorthand for calling MustBind(fs, v) for each v in vs.
Types ¶
type Field ¶
type Field struct {
Name, Usage string // name and usage text (required)
// contains filtered or unexported fields
}
A Field records information about a single flaggable field in a struct type. The caller can modify the Name and Usage fields if desired before binding the flag to a flag.FlagSet.
type Fields ¶
type Fields []*Field
Fields records information about the flaggable fields of a struct type. Use the Bind method to attach flags to the corresponding fields.
func Check ¶
Check constructs information about the flaggable fields of v, whose concrete type must be a pointer to a value of struct type.
Check reports an error if v has the wrong type, or if it does not define any flaggable fields. An exported field of v is flaggable if it is of a compatible type and has a struct tag with the following form:
flag:"name[,default=V],Usage string"
The name and usage string are required. Unexported fields and fields without a flag tag are ignored. If V contains commas, enclose it in 'single quotes', for example:
flag:"name,default='a, b',Usage string"
To escape a quote, double it ("”"). If the default value begins with "$", it is interpreted as the name of an environment variable to read for the default. Double the "$" to escape this interpretation.
If the default value is "*", it means to use the existing value of the target field as the default, rather than a zero. Use "**" to escape this meaning to get a literal star.
As an alternative, a default may be specified separately via:
flag-default:"a, b"
The two forms are mutually exclusive, even if the values are identical.
Compatible types include bool, float64, int, int64, string, time.Duration, uint, and uint64, as well as any type implementing the flag.Value interface or the encoding.TextMarshaler and encoding.TextUnmarshaler interfaces.
Example ¶
package main
import (
"flag"
"fmt"
"log"
"github.com/creachadair/flax"
)
func main() {
fields, err := flax.Check(&struct {
A int `flag:"apple,default=*,Apples"` // use field value as default
P int `flag:"pear,Pears" flag-default:"12"` // set explicit default, tag
U string `flag:"plum,default=$X,Plums"` // read default from environment
C float64 `flag:"cherry,default=0.1,Cherries"` // set explicit default, inline
}{A: 3})
if err != nil {
log.Fatal(err)
}
fs := flag.NewFlagSet("test", flag.PanicOnError)
fields.Bind(fs)
fmt.Println("-- fields --")
for _, f := range fields { // Fields in declaration order
fmt.Println(f.Name, f.Usage)
}
fmt.Println("\n-- flags --")
fs.VisitAll(func(f *flag.Flag) { // Flags in name order
fmt.Printf("%s %q %v\n", f.Name, f.DefValue, f.Usage)
})
}
Output: -- fields -- apple Apples pear Pears plum Plums cherry Cherries -- flags -- apple "3" Apples cherry "0.1" Cherries pear "12" Pears plum "" Plums [env: X]
func MustCheck ¶
MustCheck constructs a Fields value from the flaggable fields of v, or panics. This function is intended for use in program initialization; callers who need to check errors should call Check directly.
Source Files