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

• func ArgsFromEnv(flagSet *flag.FlagSet) error
• type Enum
  • func (e Enum) Get() string
  • func (e *Enum) Set(s string) error
  • func (e Enum) String() string
• type FileBytes
  • func (fb FileBytes) Get() interface{}
  • func (fb *FileBytes) Set(s string) error
  • func (fb FileBytes) 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) Get() interface{}
  • func (sa *StringArray) Set(s string) error
  • func (sa StringArray) String() string

Examples

• Package

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.

Types

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

func (StringArray) String

func (sa StringArray) String() string

String reports the StringArray as a Go value.