README
¶
CLI
A minimal package for building CLIs in Go, built around spf13/pflag with inspiration from existing CLI packages.
TODO
- Add validation for redeclared flag names (and shorthand) in subcommands (instead of pflag panic).
- Print global flags in a separate section under usage.
- Generate more flag types :D
- Validate arguments based on Usage? E.g.
command <in> <out>could validate that two positional arguments exist during parse?
Documentation
¶
Overview ¶
Package cli provides the most clean and simple API for building CLI applications (in the authors view).
Example (Basic) ¶
package main
import (
"fmt"
"os"
"github.com/itsdalmo/cli"
)
func main() {
c := cli.Command{
Usage: "printer [flags] [arg...]",
Flags: []cli.Flag{
&cli.BoolFlag{
Name: "debug, d",
Usage: "Enable debug logging",
},
},
Exec: func(c *cli.Context) error {
debug, err := c.GetBool("debug")
if err != nil {
return err
}
if debug {
fmt.Println("debugging is enabled")
}
return nil
},
Opts: cli.Options{
ErrWriter: os.Stdout,
},
}
if err := c.Execute([]string{"--help"}); err != nil {
panic(err)
}
}
Output: Usage: printer [flags] [arg...] Flags: -d, --debug Enable debug logging
Example (Minimal) ¶
package main
import (
"os"
"github.com/itsdalmo/cli"
)
func main() {
c := cli.Command{
Usage: "printer [arg...]",
Exec: func(c *cli.Context) error {
return nil
},
Opts: cli.Options{
ErrWriter: os.Stdout,
},
}
if err := c.Execute([]string{"--help"}); err != nil {
panic(err)
}
}
Output: Usage: printer [arg...]
Example (Subcommands) ¶
package main
import (
"fmt"
"os"
"github.com/itsdalmo/cli"
)
func main() {
c := cli.Command{
Usage: "printer [flags] [command]",
Flags: []cli.Flag{
&cli.BoolFlag{
Name: "debug, d",
Usage: "Enable debug logging",
},
},
Subcommands: []*cli.Command{
{
Usage: "echo [flags] [arg...]",
Help: "Echo the specified args",
Exec: func(c *cli.Context) error {
fmt.Println(c.Args())
return nil
},
},
{
Usage: "repeat <arg>",
Help: "Repeatedly print the given argument",
Flags: []cli.Flag{
&cli.IntFlag{
Name: "times, t",
Usage: "Number of times to print the argument",
Value: 3,
EnvVar: []string{"PRINTER_REPEAT_TIMES"},
},
&cli.StringFlag{
Name: "delimiter",
Usage: "Delimiter to use when printing",
Value: "\n",
},
},
Exec: func(c *cli.Context) error {
times, err := c.GetInt("times")
if err != nil {
return err
}
delimiter, err := c.GetString("delimiter")
for i := 0; i < times; i++ {
fmt.Print(c.Arg(0), delimiter)
}
return nil
},
},
},
Opts: cli.Options{
ErrWriter: os.Stdout,
},
}
if err := c.Execute([]string{"repeat", "--help"}); err != nil {
panic(err)
}
}
Output: Repeatedly print the given argument Usage: printer repeat <arg> Flags: --delimiter string Delimiter to use when printing (default "\n") -t, --times int Number of times to print the argument [$PRINTER_REPEAT_TIMES] (default 3) Global Flags: -d, --debug Enable debug logging
Index ¶
- func ResolveMissingFlags(fs *pflag.FlagSet, flags []Flag, resolvers ...FlagResolver) error
- type BoolFlag
- type BoolSliceFlag
- type Command
- type Context
- type DurationFlag
- type DurationSliceFlag
- type EnvVarResolver
- type ErrMisconfigured
- type Flag
- type FlagResolver
- type IntFlag
- type IntSliceFlag
- type Options
- type StringFlag
- type StringSliceFlag
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ResolveMissingFlags ¶ added in v0.0.2
func ResolveMissingFlags(fs *pflag.FlagSet, flags []Flag, resolvers ...FlagResolver) error
ResolveMissingFlags iterates over all missing flags in the given pflag.FlagSet and applies each FlagResolver in turn until the the flag is resolved. An error is returned if we are unable to set the flag to the resolved value, or if a required Flag has missing values after applying all resolvers.
Types ¶
type BoolFlag ¶
BoolFlag is used to define a pflag.FlagSet.BoolP flag.
func (*BoolFlag) GetShorthand ¶
GetShorthand implements Flag.
type BoolSliceFlag ¶
BoolSliceFlag is used to define a pflag.FlagSet.BoolSliceP flag.
func (*BoolSliceFlag) Apply ¶
func (f *BoolSliceFlag) Apply(fs *pflag.FlagSet)
Apply implements Flag.
func (*BoolSliceFlag) GetEnvVar ¶
func (f *BoolSliceFlag) GetEnvVar() []string
GetEnvVar implements Flag.
func (*BoolSliceFlag) GetShorthand ¶
func (f *BoolSliceFlag) GetShorthand() string
GetShorthand implements Flag.
func (*BoolSliceFlag) GetUsage ¶
func (f *BoolSliceFlag) GetUsage() string
GetUsage implements Flag.
func (*BoolSliceFlag) IsRequired ¶
func (f *BoolSliceFlag) IsRequired() bool
IsRequired implements Flag.
type Command ¶
type Command struct {
Usage string
Help string
Flags []Flag
Exec func(*Context) error
Subcommands []*Command
Opts Options
// contains filtered or unexported fields
}
Command ...
func (*Command) CombinedFlags ¶ added in v0.0.2
func (*Command) GlobalFlags ¶ added in v0.0.2
func (*Command) LocalFlags ¶ added in v0.0.2
type DurationFlag ¶
type DurationFlag struct {
Name string
Usage string
EnvVar []string
Value time.Duration
Required bool
}
DurationFlag is used to define a pflag.FlagSet.DurationP flag.
func (*DurationFlag) GetEnvVar ¶
func (f *DurationFlag) GetEnvVar() []string
GetEnvVar implements Flag.
func (*DurationFlag) GetShorthand ¶
func (f *DurationFlag) GetShorthand() string
GetShorthand implements Flag.
func (*DurationFlag) IsRequired ¶
func (f *DurationFlag) IsRequired() bool
IsRequired implements Flag.
type DurationSliceFlag ¶
type DurationSliceFlag struct {
Name string
Usage string
EnvVar []string
Value []time.Duration
Required bool
}
DurationSliceFlag is used to define a pflag.FlagSet.DurationSliceP flag.
func (*DurationSliceFlag) Apply ¶
func (f *DurationSliceFlag) Apply(fs *pflag.FlagSet)
Apply implements Flag.
func (*DurationSliceFlag) GetEnvVar ¶
func (f *DurationSliceFlag) GetEnvVar() []string
GetEnvVar implements Flag.
func (*DurationSliceFlag) GetName ¶
func (f *DurationSliceFlag) GetName() string
GetName implements Flag.
func (*DurationSliceFlag) GetShorthand ¶
func (f *DurationSliceFlag) GetShorthand() string
GetShorthand implements Flag.
func (*DurationSliceFlag) GetUsage ¶
func (f *DurationSliceFlag) GetUsage() string
GetUsage implements Flag.
func (*DurationSliceFlag) IsRequired ¶
func (f *DurationSliceFlag) IsRequired() bool
IsRequired implements Flag.
type EnvVarResolver ¶ added in v0.0.2
type EnvVarResolver struct{}
EnvVarResolver implements FlagResolver by resolving variables from the environment.
type ErrMisconfigured ¶
type ErrMisconfigured struct {
// contains filtered or unexported fields
}
ErrMisconfigured is returned when a Command is misconfigured.
func (*ErrMisconfigured) Error ¶
func (e *ErrMisconfigured) Error() string
Error implements errors.Error.
type Flag ¶
type Flag interface {
// Apply the flag to the given flagset.
Apply(fs *pflag.FlagSet)
// GetName returns the name of the flag.
GetName() string
// GetShorthand returns the shorthand of the flag (if it is defined).
GetShorthand() string
// GetUsage returns the usage for the flag.
GetUsage() string
// GetEnvVar returns the env variables used to set this flag.
GetEnvVar() []string
// IsRequired returns true if the flag is marked as required.
IsRequired() bool
}
Flag is the interface implemented by all flag types.
type FlagResolver ¶ added in v0.0.2
FlagResolver is the interface implemented by custom flag resolvers.
type IntFlag ¶
IntFlag is used to define a pflag.FlagSet.IntP flag.
func (*IntFlag) GetShorthand ¶
GetShorthand implements Flag.
type IntSliceFlag ¶
IntSliceFlag is used to define a pflag.FlagSet.IntSliceP flag.
func (*IntSliceFlag) GetEnvVar ¶
func (f *IntSliceFlag) GetEnvVar() []string
GetEnvVar implements Flag.
func (*IntSliceFlag) GetShorthand ¶
func (f *IntSliceFlag) GetShorthand() string
GetShorthand implements Flag.
func (*IntSliceFlag) IsRequired ¶
func (f *IntSliceFlag) IsRequired() bool
IsRequired implements Flag.
type Options ¶
type Options struct {
Reader io.Reader
Writer io.Writer
ErrWriter io.Writer
UsageFunc func(*Command) string
Resolvers []FlagResolver
}
Options ...
type StringFlag ¶
StringFlag is used to define a pflag.FlagSet.StringP flag.
func (*StringFlag) GetShorthand ¶
func (f *StringFlag) GetShorthand() string
GetShorthand implements Flag.
type StringSliceFlag ¶
type StringSliceFlag struct {
Name string
Usage string
EnvVar []string
Value []string
Required bool
}
StringSliceFlag is used to define a pflag.FlagSet.StringSliceP flag.
func (*StringSliceFlag) Apply ¶
func (f *StringSliceFlag) Apply(fs *pflag.FlagSet)
Apply implements Flag.
func (*StringSliceFlag) GetEnvVar ¶
func (f *StringSliceFlag) GetEnvVar() []string
GetEnvVar implements Flag.
func (*StringSliceFlag) GetName ¶
func (f *StringSliceFlag) GetName() string
GetName implements Flag.
func (*StringSliceFlag) GetShorthand ¶
func (f *StringSliceFlag) GetShorthand() string
GetShorthand implements Flag.
func (*StringSliceFlag) GetUsage ¶
func (f *StringSliceFlag) GetUsage() string
GetUsage implements Flag.
func (*StringSliceFlag) IsRequired ¶
func (f *StringSliceFlag) IsRequired() bool
IsRequired implements Flag.
Source Files
Directories