flagx

README

Functions which extend the capabilities of the flag package.

This package includes:

• flagx.ArgsFromEnv allows flags to be passed from the command-line or as an environment variable.

• flagx.FileBytes is a new flag type. It automatically reads the content of the given file as a []byte, handling any error during flag parsing and simplifying application logic.

• flagx.StringArray is a new flag type that handles appending to []string

Usage of any of the above is like:

package main

import (
	"flag"
	"fmt"

	"github.com/m-lab/go/flagx"
)

var (
	flagArray flagx.StringArray
)

func main() {
	flag.Var(&flagArray, "array", "append to string array")
	flag.Parse()
	fmt.Printf("%+v\n", flagArray)
	// your code here
}

Documentation

Overview

Package flagx extends to capabilities of flags to also be able to read from environment variables. This comes in handy when dockerizing applications.

Example

package main

import (
	"flag"
	"log"

	"github.com/m-lab/go/flagx"
)

func main() {
	metadata := flagx.KeyValue{}
	flag.Var(&metadata, "metadata", "Key-value pairs to be added to the metadata (flag may be repeated)")
	// Commandline flags should look like: -metadata key1=val1 -metadata key2=val2
	flag.Parse()

	log.Println(metadata.Get())
}

Index

• Variables
• func ArgsFromEnv(flagSet *flag.FlagSet) error
• func ArgsFromEnvWithLog(flagSet *flag.FlagSet, logArgs bool) error
• func AssignedFlags(flagSet *flag.FlagSet) map[string]struct{}
• func EnableAdvancedFlags()
• func MakeShellVariableName(flagName string) string
• type DateTime
  • func (t DateTime) Get() string
  • func (t *DateTime) Set(s string) error
  • func (t DateTime) String() string
• type DurationArray
  • func (da DurationArray) Get() interface{}
  • func (da *DurationArray) Set(s string) error
  • func (da DurationArray) String() string
• type Enum
  • func (e Enum) Get() string
  • func (e *Enum) Set(s string) error
  • func (e Enum) String() string
• type File
  • func (fb *File) Content() string
  • func (fb *File) Get() []byte
  • func (fb *File) Set(s string) error
  • func (fb *File) String() string
• type FileBytes
  • func (fb FileBytes) Get() interface{}
  • func (fb *FileBytes) Set(s string) error
  • func (fb FileBytes) String() string
• type FileBytesArray
  • func (fb *FileBytesArray) Get() [][]byte
  • func (fb *FileBytesArray) Set(s string) error
  • func (fb FileBytesArray) String() string
• type KeyValue
  • func (kv *KeyValue) Get() map[string]string
  • func (kv *KeyValue) Set(kvstring string) error
  • func (kv *KeyValue) String() string
• type StringArray
  • func (sa StringArray) Contains(value string) bool
  • func (sa StringArray) Get() interface{}
  • func (sa *StringArray) Set(s string) error
  • func (sa StringArray) String() string
• type Time
  • func (t Time) Get() string
  • func (t *Time) Set(s string) error
  • func (t Time) String() string
• type URL
  • func MustNewURL(s string) URL
  • func (u *URL) Get() *url.URL
  • func (u *URL) Set(s string) error
  • func (u *URL) String() string

Examples

• Package

Variables

var (
	// Advanced is a *flag.FlagSet for advanced flags. Packages should add flags
	// to Advanced when those flags should NOT be included in the default
	// flag.CommandLine flag set. Advanced flags may be enabled by calling
	// EnableAdvancedFlags _before_ calling flag.Parse().
	Advanced = flag.NewFlagSet("advanced", flag.ExitOnError)
)

var ErrBadTimeFormat = fmt.Errorf("ErrBadTimeFormat: unsupported time format")

ErrBadTimeFormat is returned when failing to parse a Time value.

Functions

func ArgsFromEnv

func ArgsFromEnv(flagSet *flag.FlagSet) error

ArgsFromEnv will expand command-line argument parsing to include setting the values of flags from their corresponding environment variables. The environment variable for an argument is the upper-case version of the command-line flag.

If you have two flags that map to the same environment variable string (like "-a" and "-A"), then the behavior of this function is unspecified and should not be relied upon. Also, your flags should have more descriptive names.

func ArgsFromEnvWithLog

func ArgsFromEnvWithLog(flagSet *flag.FlagSet, logArgs bool) error

ArgsFromEnvWithLog operates as ArgsFromEnv with an additional option to disable logging of all flag values. This is helpful for command line applications that wish to disable extra argument logging.

func AssignedFlags

func AssignedFlags(flagSet *flag.FlagSet) map[string]struct{}

AssignedFlags returns a map[string]struct{} where every key in the map is the name of a flag in the passed-in FlagSet that was explicitly set on the command-line.

func EnableAdvancedFlags

func EnableAdvancedFlags()

EnableAdvancedFlags adds all flags registered with the Advanced flag set to the default flag.CommandLine flag set. EnableAdvancedFlags should be called before flag.Parse().

func MakeShellVariableName

func MakeShellVariableName(flagName string) string

MakeShellVariableName makes every passed-in string match the regexp [A-Z_][A-Z0-9_]* Characters in shell variable names should be part of the portable character set (defined to be [A-Z0-9_] in https://pubs.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap08.html) and may not begin with a digit.

Types

type DateTime

type DateTime struct {
	time.Time
}

DateTime is a flag type for accepting date parameters.

func (DateTime) Get

func (t DateTime) Get() string

Get retrieves the current date value as a string.

func (*DateTime) Set

func (t *DateTime) Set(s string) error

Set parses and assigns the DateTime value. DateTime accepts all formats supported by the "github.com/araddon/dateparse" package.

func (DateTime) String

func (t DateTime) String() string

String reports the parsed time as a string using time.Time.String().

type DurationArray

type DurationArray []time.Duration

DurationArray collects time.Durations so a duration flag can be specified multiple times or using "," separated items. The default argument should almost always be the empty array, because there is no way to remove an element, only to add one.

func (DurationArray) Get

func (da DurationArray) Get() interface{}

Get retrieves the value contained in the flag.

func (*DurationArray) Set

func (da *DurationArray) Set(s string) error

Set appends the given time.Duration to the DurationArray. Set accepts multiple durations separated by commas "," and appends each element to the DurationArray.

func (DurationArray) String

func (da DurationArray) String() string

String reports the DurationArray as a Go value.

type Enum

type Enum struct {
	Options []string
	Value   string
}

Enum is a new flag type. An Enum contains an array of Options and a selected Value.

func (Enum) Get

func (e Enum) Get() string

Get retrieves the value contained in the flag.

func (*Enum) Set

func (e *Enum) Set(s string) error

Set selects the Enum.Value if s equals one of the values in Enum.Options.

func (Enum) String

func (e Enum) String() string

String reports the set Enum value.

type File

type File struct {
	Bytes []byte
	Name  string
}

File is a new flag type. For a given filename, File reads and saves the file content to Bytes and the original filename to Name. Errors opening or reading the file are handled during flag parsing.

func (*File) Content

func (fb *File) Content() string

Content retrieves the bytes read from the file as a string.

func (*File) Get

func (fb *File) Get() []byte

Get retrieves the bytes read from the file.

func (*File) Set

func (fb *File) Set(s string) error

Set accepts a file name. On success, the file content is saved to Bytes, and the original file name to Name.

func (*File) String

func (fb *File) String() string

String reports the original file Name. NOTE: String is typically used by the flag help text and to report flag values. To return the file content as a string, see File.Content().

type FileBytes

type FileBytes []byte

FileBytes is a new flag type. It automatically reads the content of the given filename as a `[]byte`, handling errors during flag parsing.

func (FileBytes) Get

func (fb FileBytes) Get() interface{}

Get retrieves the bytes read from the file (or the default bytes).

func (*FileBytes) Set

func (fb *FileBytes) Set(s string) error

Set accepts a filename and reads the bytes associated with that file into the FileBytes storage.

func (FileBytes) String

func (fb FileBytes) String() string

String reports the FileBytes content as a string.

FileBytes are awkward to represent in help text, and such help text is the main use of the Stringer interface for this flag. Help text like:

"Sets the file containing the prefix string. The default file contents are: " + fb.String()

is recommended.

type FileBytesArray

type FileBytesArray struct {
	// contains filtered or unexported fields
}

FileBytesArray is a new flag type that combines the semantics of StringArray for multiple filenames and FileBytes for reading the content of each file. Every filename is read as a `[]byte` and the contents appended to an FileBytesArray of type `[][]byte`.

Like StringArray, the flag parameter may be specified multiple times or using "," separated items. Unlike other Flag types, the default argument should almost always be the empty array, because there is no way to remove an element, only to add one.

func (*FileBytesArray) Get

func (fb *FileBytesArray) Get() [][]byte

Get retrieves the bytes read from the file (or the default bytes).

func (*FileBytesArray) Set

func (fb *FileBytesArray) Set(s string) error

Set accepts a filename (or filenames separated by comma) and reads the bytes associated with the file and appends the bytes the FileBytesArray.

func (FileBytesArray) String

func (fb FileBytesArray) String() string

String reports the original FileBytesArray filenames a string.

type KeyValue

type KeyValue struct {
	// contains filtered or unexported fields
}

KeyValue is a way of setting the elements of a map[string]string individually as key-value pairs on the command-line. It is designed to be used as a repeated argument, where each invocation of the command-line argument will add another key value pair.

One use for this library could be to specify metadata headers.

func (*KeyValue) Get

func (kv *KeyValue) Get() map[string]string

Get returns a copy of the KeyValue object as a map[string]string. This new map may be modified as desired without worrying about modifying the command-line arguments.

func (*KeyValue) Set

func (kv *KeyValue) Set(kvstring string) error

Set breaks the string apart at the first equals sign and puts the result key-value pair into the map.

func (*KeyValue) String

func (kv *KeyValue) String() string

String converts the headers into a text representation. It's not expected to provide useful output here, but it is a function that is required in order to implement flag.Value.

type StringArray

type StringArray []string

StringArray is a new flag type. It appends the flag parameter to an `[]string` allowing the parameter to be specified multiple times or using "," separated items. Unlike other Flag types, the default argument should almost always be the empty array, because there is no way to remove an element, only to add one.

func (StringArray) Contains

func (sa StringArray) Contains(value string) bool

Contains returns true when the given value equals one of the StringArray values.

func (StringArray) Get

func (sa StringArray) Get() interface{}

Get retrieves the value contained in the flag.

func (*StringArray) Set

func (sa *StringArray) Set(s string) error

Set accepts a string parameter and appends it to the associated StringArray. Set attempts to split the given string on commas "," and appends each element to the StringArray.

func (StringArray) String

func (sa StringArray) String() string

String reports the StringArray as a Go value.

type Time

type Time struct {
	Hour   int
	Minute int
	Second int
}

Time is a flag type for accepting time parameters formatted as HH:MM:SS. If you need sub-second resolution, consider using one of the unix timestamp formats (ms, usec, or ns) supported by DateTime.

func (Time) Get

func (t Time) Get() string

Get retrieves the value contained in the flag.

func (*Time) Set

func (t *Time) Set(s string) error

Set parses and assigns the Time Hour, Minute, and Second values.

func (Time) String

func (t Time) String() string

String reports the set Time value.

type URL

type URL struct {
	*url.URL
}

URL is a flag type for parsing URL strings and handling errors during flag parsing. Use MustNewURL() to specify a default value.

func MustNewURL

func MustNewURL(s string) URL

MustNewURL creates a new flagx.URL initialized with the given value. Failure to parse is fatal. For example:

f := flagx.MustNewURL("http://example.com")

func (*URL) Get

func (u *URL) Get() *url.URL

Get returns the inner *url.URL type.

func (*URL) Set

func (u *URL) Set(s string) error

Set parses a URL string and stores the result.

func (*URL) String

func (u *URL) String() string

String formats the underlying URL as a string.