multiflag

Documentation

Overview

Package multiflag is a package providing a flag.Value implementation capable of switching between multiple registered sub-flags, each of which have their own set of parameter flags.

Example

This can be used to construct complex option flags. For example:

-backend mysql,address="192.168.1.1",port="12345"
-backend sqlite3,path="/path/to/database"

In this example, a MultiFlag is defined and bound to the option name, "backend". This MultiFlag has (at least) two registered Options:

1. mysql, whose FlagSet binds "address" and "port" options.
2. sqlite3, whose FlagSet binds "path".

The MultiFlag Option that is selected (e.g., "mysql") has the remainder of its option string parsed into its FlagSet, populating its "address" and "port" parameters. If "sqlite3" is selected, the remainder of the option string would be parsed into its FlagSet, which hosts the "path" parameter.

Index

• type FlagOption
  • func (o *FlagOption) Descriptor() *OptionDescriptor
  • func (o *FlagOption) Flags() *flag.FlagSet
  • func (o *FlagOption) IsPinned() bool
  • func (o *FlagOption) PrintHelp(output io.Writer)
  • func (o *FlagOption) Run(value string) error
• type MultiFlag
  • func (mf *MultiFlag) GetOptionFor(name string) Option
  • func (mf *MultiFlag) GetOutput() io.Writer
  • func (mf MultiFlag) OptionNames() []string
  • func (mf *MultiFlag) Parse(value string) error
  • func (mf *MultiFlag) PrintHelp() error
  • func (mf *MultiFlag) Set(value string) error
  • func (mf *MultiFlag) String() string
• type Option
  • func HelpOption(mf *MultiFlag) Option
• type OptionDescriptor

Examples

• MultiFlag

Types

type FlagOption

type FlagOption struct {
	Name        string
	Description string
	Pinned      bool
	// contains filtered or unexported fields
}

FlagOption is an implementation of Option that is describes a single nestedflagset option. This option has sub-properties that

func (*FlagOption) Descriptor

func (o *FlagOption) Descriptor() *OptionDescriptor

Descriptor implements Option.

func (*FlagOption) Flags

func (o *FlagOption) Flags() *flag.FlagSet

Flags returns this Option's nested FlagSet for configuration.

func (*FlagOption) IsPinned

func (o *FlagOption) IsPinned() bool

IsPinned implements Option.

func (*FlagOption) PrintHelp

func (o *FlagOption) PrintHelp(output io.Writer)

PrintHelp implements Option.

func (*FlagOption) Run

func (o *FlagOption) Run(value string) error

Run implements Option.

type MultiFlag

type MultiFlag struct {
	Description string
	Options     []Option
	Output      io.Writer // Output writer, or nil to use STDERR.

	// The selected Option, populated after Parsing.
	Selected Option
}

MultiFlag is a flag.Value-like object that contains multiple sub-options. Each sub-option presents itself as a flag.FlagSet. The sub-option that gets selected will have its FlagSet be evaluated against the accompanying options.

For example, one can construct flag that, depending on its options, chooses one of two sets of sub-properties:

-myflag foo,foovalue=123
-myflag bar,barvalue=456,barothervalue="hello"

"myflag" is the name of the MultiFlag's top-level flag, as registered with a flag.FlagSet. The first token in the flag's value selects which Option should be configured. If "foo" is configured, the remaining configuration is parsed by the "foo" Option's FlagSet, and the equivalent is true for "bar".

Example

// Setup multiflag.
param := ""
deprecated := FlagOption{
	Name:        "deprecated",
	Description: "The deprecated option.",
}
deprecated.Flags().StringVar(&param, "param", "", "String parameter.")

beta := FlagOption{Name: "beta", Description: "The new option, which is still beta."}
beta.Flags().StringVar(&param, "param", "", "Beta string parameter.")

mf := MultiFlag{
	Description: "My test MultiFlag.",
	Output:      os.Stdout,
}
mf.Options = []Option{
	HelpOption(&mf),
	&deprecated,
	&beta,
}

// Install the multiflag as a flag in "flags".
fs := flag.NewFlagSet("test", flag.ContinueOnError)
fs.Var(&mf, "multiflag", "Multiflag option.")

// Parse flags (help).
cmd := []string{"-multiflag", "help"}
fmt.Println("Selecting help option:", cmd)
if err := fs.Parse(cmd); err != nil {
	panic(err)
}

// Parse flags (param).
cmd = []string{"-multiflag", "beta,param=Sup"}
fmt.Println("Selecting beta option:", cmd)
if err := fs.Parse(cmd); err != nil {
	panic(err)
}
fmt.Printf("Option [%s], parameter: [%s].\n", mf.Selected.Descriptor().Name, param)

Output:

Selecting help option: [-multiflag help]
My test MultiFlag.
help        Displays this help message. Can be run as "help,<option>" to display help for an option.
beta        The new option, which is still beta.
deprecated  The deprecated option.
Selecting beta option: [-multiflag beta,param=Sup]
Option [beta], parameter: [Sup].

func (*MultiFlag) GetOptionFor

func (mf *MultiFlag) GetOptionFor(name string) Option

GetOptionFor returns the Option associated with the specified name, or nil if one isn't defined.

func (*MultiFlag) GetOutput

func (mf *MultiFlag) GetOutput() io.Writer

GetOutput returns the output Writer used for help output.

func (MultiFlag) OptionNames

func (mf MultiFlag) OptionNames() []string

OptionNames returns a list of the option names registered with a MultiFlag.

func (*MultiFlag) Parse

func (mf *MultiFlag) Parse(value string) error

Parse applies a value string to a MultiFlag.

For example, if the value string is: foo,option1=test

Parse will identify the MultiFlag option named "foo" and have it parse the string, "option1=test".

func (*MultiFlag) PrintHelp

func (mf *MultiFlag) PrintHelp() error

PrintHelp prints a formatted help string for a MultiFlag. This help string details the Options registered with the MultiFlag.

func (*MultiFlag) Set

func (mf *MultiFlag) Set(value string) error

Set implements flag.Value

func (*MultiFlag) String

func (mf *MultiFlag) String() string

String implements flag.Value

type Option

type Option interface {
	Descriptor() *OptionDescriptor

	PrintHelp(io.Writer)
	Run(string) error // Parses the Option from a configuration string.
}

Option is a single option entry in a MultiFlag. An Option is responsible for parsing a FlagSet from an option string.

func HelpOption

func HelpOption(mf *MultiFlag) Option

HelpOption instantiates a new Option instance that prints a help string when parsed.

type OptionDescriptor

type OptionDescriptor struct {
	Name        string
	Description string

	Pinned bool
}

OptionDescriptor is a collection of common Option properties.