luci: go.chromium.org/luci/common/flag/multiflag Index | Examples | Files

package multiflag

import "go.chromium.org/luci/common/flag/multiflag"

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

Examples

Package Files

multiflag.go

type FlagOption Uses

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 Uses

func (o *FlagOption) Descriptor() *OptionDescriptor

Descriptor implements Option.

func (*FlagOption) Flags Uses

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

Flags returns this Option's nested FlagSet for configuration.

func (*FlagOption) IsPinned Uses

func (o *FlagOption) IsPinned() bool

IsPinned implements Option.

func (*FlagOption) PrintHelp Uses

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

PrintHelp implements Option.

func (*FlagOption) Run Uses

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

Run implements Option.

type MultiFlag Uses

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

Code:

// 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 Uses

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 Uses

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

GetOutput returns the output Writer used for help output.

func (MultiFlag) OptionNames Uses

func (mf MultiFlag) OptionNames() []string

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

func (*MultiFlag) Parse Uses

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 Uses

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 Uses

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

Set implements flag.Value

func (*MultiFlag) String Uses

func (mf *MultiFlag) String() string

String implements flag.Value

type Option Uses

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 Uses

func HelpOption(mf *MultiFlag) Option

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

type OptionDescriptor Uses

type OptionDescriptor struct {
    Name        string
    Description string

    Pinned bool
}

OptionDescriptor is a collection of common Option properties.

Package multiflag imports 9 packages (graph) and is imported by 1 packages. Updated 2018-10-21. Refresh now. Tools for package owners.