flagstruct

README

flagstruct 🏁

flagstruct is another library for parsing command line flags into structs. Although packages named flagstruct already exist, this pattern emerged coincidentally in some of our projects, and we decided to simply merge the best parts into one library. We noticed the name was already taken too late. "Any resemblance to actual persons, living or dead, or actual events is purely coincidental."

flagstruct has a few neat advantages:

• Uses values as defaults; no need to encode these as struct tags.
• Supports generating usage data with groups and specified ordering. To use grouping, simply use an unnamed struct{}-typed member as a separator.
• Supports custom flag.Value types in structures, along with the built-in flag.Value types.
• Implements FlagSets akin to Go's flag.FlagSet.
• Implements environment variables through env flag.
• Boolean special case is handled identically to Go's flag package.

Getting Started

flagstruct is a library. To make use of it, you need to write software that imports it. An example is included below that you can use to play around with flagstruct.

Prerequisites

flagstruct is built in the Go programming language. If you are new to Go, you will need to install Go.

There are no other dependencies, but you may want to configure your text editor for Go if you have not done so.

Acquiring

Next, you'll want to go get flagstruct, like so:

go get github.com/Benzinga/flagstruct

If your $GOPATH is configured, and git is setup to know your credentials, in a few moments the command should complete with no output. The repository will exist under $GOPATH/src/github.com/Benzinga/flagstruct. It cannot be moved from this location.

Hint: If you've never used Go before, your $GOPATH will be under the go folder of your user directory.

Example

A quick example follows:

package main

import (
    "flag"
    "fmt"

    "github.com/Benzinga/flagstruct"
)

var conf = struct {
    Compress bool   `flag:"z" usage:"whether or not to use compression" env:"COMPRESS"`
    OutputFn string `flag:"out" usage:"output ~filename~"`
}{
    Compress: true,
}

func main() {
    // Parse flags and environment based off of flagstruct.
    flagstruct.Configure(&conf)

    // Print out the flags.
    fmt.Printf("Flags: %+v\n", conf)
}

To use this example: Save to a file with a .go extension, like test.go, then use go run test.go [args] to play with the argument parsing. Do not put the example file into the flagstruct directory as it will get confused with the flagstruct source code.

Documentation

Overview

Package flagstruct is a simple package that allows you to express flag and environment variable based configuration using structs and struct tagging.

Structures

flagstruct works on arbitrary structures with struct tagging. The following struct tags are supported:

• "flag": Maps the struct member to a command line flag.
• "env": Maps the struct member to an environment variable.
• "usage": Specifies the usage string to use for the flag.

Default values are derived from the value of the member in the struct. To see exactly how this works, check out the package example.

Example (Advanced)

This snippet shows how to use flag and environment parsing without using the Configure helper that couples configuration with parsing.

package main

import (
	"github.com/Benzinga/flagstruct"
)

func main() {
	conf := struct {
		Compress bool   `flag:"z" usage:"whether or not to use compression" env:"COMPRESS"`
		OutputFn string `flag:"out" usage:"output ~filename~"`
	}{
		Compress: true,
	}

	// Set up flags.
	flagstruct.Struct(&conf)

	// Parse environment.
	flagstruct.ParseEnv()

	// Parse flags.
	flagstruct.Parse()
}

Example (Simple)

This snippet shows how to use flag and environment variable parsing with flagstruct.

package main

import (
	"github.com/Benzinga/flagstruct"
)

func main() {
	conf := struct {
		Compress bool   `flag:"z" usage:"whether or not to use compression" env:"COMPRESS"`
		OutputFn string `flag:"out" usage:"output ~filename~"`
	}{
		Compress: true,
	}

	// Parse flags based on structure.
	flagstruct.Configure(&conf)
}

Index

• Variables
• func Configure(conf interface{}) error
• func Parse() error
• func ParseEnv() error
• func PrintStruct(conf interface{})
• func Struct(conf interface{}) error
• type FlagSet
  • func NewFlagSet(name string, errorHandling flag.ErrorHandling) *FlagSet
  • func (s *FlagSet) Configure(conf interface{}, arguments []string) error
  • func (s *FlagSet) MakeStructUsage(conf interface{}) func()
  • func (s *FlagSet) MakeUsage() func()
  • func (s *FlagSet) ParseEnv() error
  • func (s *FlagSet) PrintDefaults()
  • func (s *FlagSet) PrintStruct(conf interface{})
  • func (s *FlagSet) SetOutput(output io.Writer)
  • func (s *FlagSet) Struct(conf interface{}) error
• type Value

Examples

• Package (Advanced)
• Package (Simple)

Variables

var CommandLine = &FlagSet{flag.CommandLine, os.Args[0], flag.ExitOnError, nil, map[string]Value{}}

CommandLine is the default set of command-line flags, parsed from os.Args.

Functions

func Configure

func Configure(conf interface{}) error

Configure sets up enhanced usage help, loads a structure, parses environment and parses flags.

func Parse

func Parse() error

Parse parses the command line parameters from argv.

func ParseEnv

func ParseEnv() error

ParseEnv parses the environment flags in the structure.

func PrintStruct

func PrintStruct(conf interface{})

PrintStruct prints configuration flags based on the struct passed to `conf`.

func Struct

func Struct(conf interface{}) error

Struct loads parameters based off of a struct object.

Types

type FlagSet

type FlagSet struct {
	*flag.FlagSet
	// contains filtered or unexported fields
}

A FlagSet represents a set of defined flags.

func NewFlagSet

func NewFlagSet(name string, errorHandling flag.ErrorHandling) *FlagSet

NewFlagSet returns a new, empty flag set with the specified name and error handling property.

func (*FlagSet) Configure

func (s *FlagSet) Configure(conf interface{}, arguments []string) error

Configure sets up enhanced usage help, loads a structure, parses environment and parses flags.

func (*FlagSet) MakeStructUsage

func (s *FlagSet) MakeStructUsage(conf interface{}) func()

MakeStructUsage creates a usage function from a struct.

func (*FlagSet) MakeUsage

func (s *FlagSet) MakeUsage() func()

MakeUsage creates a usage function that prints the flags.

func (*FlagSet) ParseEnv

func (s *FlagSet) ParseEnv() error

ParseEnv parses environment variables.

func (*FlagSet) PrintDefaults

func (s *FlagSet) PrintDefaults()

PrintDefaults prints to standard error the default values of all defined command-line flags in the set. This is copied from flag, adjusted to allow ~ quotes in default values.

func (*FlagSet) PrintStruct

func (s *FlagSet) PrintStruct(conf interface{})

PrintStruct prints flags based on the struct passed to `conf`.

func (*FlagSet) SetOutput

func (s *FlagSet) SetOutput(output io.Writer)

SetOutput sets the destination for usage and error messages. If output is nil, os.Stderr is used.

func (*FlagSet) Struct

func (s *FlagSet) Struct(conf interface{}) error

Struct loads parameters based off of a struct object.

type Value

type Value interface {
	String() string
	Set(string) error
	Get() interface{}
}

Value is an interface used for flag values.