cli

package
v0.0.0-...-1d9d0fb Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 24, 2017 License: Apache-2.0 Imports: 7 Imported by: 0

README

Cli - Mamba

The CLI pkg is also named Mamba.

About the project

Mamba provides a higher level and more friendly interfaces to build modern command line interfaces and manage configurations for Go applications.

It is based on

Status

Working in process

Concepts

A cli is composed of commands, arguments and flags.

Commands represent actions, Args are things and Flags are modifiers for those actions.

The pattern to follow is appname commands args --flag

The flag is compatible with the GNU extensions to the POSIX recommendations for command-line options.

Getting Started

Commands

You can migrate your cobra commands to mamba easily.

the cli.NewCommand receives a *cobra.Command to build the whole CLI.

import (
	mamba "github.com/caicloud/nirvana/cli"
	"github.com/spf13/cobra"
)

func main() {
	cmd := mamba.NewCommand(&cobra.Command{
		Use:  "example",
		Long: "this is an cli example",
		Run: func(cmd *cobra.Command, args []string) {
			// you code
		},
	})
}

More about cobra command

Flags

Flag, different from pflag.Flag, is an interface containing the following methods in Mamba.

And it is declarative in Mamba, unlike in Cobra where it is imperative which makes the flags more readable.

Mamba will bind viper and flags automatically. That means you can get all your flag values from viper.

// Flag describes a flag interface
type Flag interface {
	// IsPersistent specify whether the flag is persistent
	IsPersistent() bool
	// GetName returns the flag's name
	GetName() string
	// ApplyTo adds the flag to a given FlagSet
	ApplyTo(*pflag.FlagSet) error
}

A most widely used string flag is defined like

type StringFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue string
	// points to a variable in which to store the value of the flag
	Destination *string
}
Binding flag with ENV

Mamba supports the ability to bind your flags with ENV variables.

Mamba uses the following precedence order. Each item takes precedence over the item below it.

  • explicit calls to set
  • flag
  • env
  • default value
f := cli.StringFlag{
	Name: "log",
	EnvKey: "LOG",
  	DefValue: "test",
}
Automatic ENV and Prefix

Mamba supports the ability to bind you flags with ENV and add prefix automatically

The following methods exist to aid working with ENV

  • AutomaticEnv()
  • SetEnvPrefix(string)
  • SetEnvKeyReplacer(*strings.Replacer)

When working with ENV variables, it’s important to recognize that Mamba treats ENV variables case insensitively. All ENV variables are treated as UPPER case

By using AutomaticEnv, you tell mamba to bind all flags with ENV automatically.

SetEnvPrefix is always working with AutomaticEnv . It makes mamba add a prefix while reading from env variables.

By using SetEnvKeyReplacer, you make mamba change the ENV by key replacer. For example, you can set a UnderlineReplacer to replace all - with _ .

Note: If EnvKey is set, it will override the automatic env and does not automatically add the prefix.

Example

AutomaticEnv()
SetEnvPrefix("nirvana")

log = new(string)

f := cli.StringFlag{
	Name: "log",
	Destination: log,
}

os.Setenv("NIRVANA_LOG", "TEST")

cmd.AddFlag(f)

// *log is TEST
Hidden, Deprecated, ShorthandDeprecated
  • Hidden and Deprecated hide the whole flag in help information.
  • ShorthandDeprecated hides the shorhand flag.

You can set the flag as usual.

  • Hidden just hide the flag
  • Deprecated and ShorthandDeprecated will print a deprecated message to you if you use the flag
[WIP] Viper

You can get a flag value from viper easily.

cli.Viper.GetString("log")

Need further integration

Thanks

spf13 creates awesome tools to make it easier to build a beautiful modern CLI apps.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// UnderlineReplacer replace dash of underline
	UnderlineReplacer = strings.NewReplacer("-", "_")
)
View Source 
var (
	// Viper global viper
	Viper = viper.New()
)

Functions

func AutomaticEnv 

func AutomaticEnv()

AutomaticEnv has Mamba check ENV variables for all. keys set in config, default & flags

func SetEnvKeyReplacer 

func SetEnvKeyReplacer(r *strings.Replacer)

SetEnvKeyReplacer sets the strings.Replacer on the viper object Useful for mapping an environmental variable to a key that does not match it.

func SetEnvPrefix 

func SetEnvPrefix(in string)

SetEnvPrefix defines a prefix that ENVIRONMENT variables will use. E.g. if your prefix is "spf", the env registry will look for env variables that start with "SPF_". Only work for automatic env

Types

type BoolFlag 

type BoolFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue bool
	// points to a variable in which to store the value of the flag
	Destination *bool
}

BoolFlag is a flag of type bool

func (BoolFlag) ApplyTo 

func (f BoolFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (BoolFlag) GetName 

func (f BoolFlag) GetName() string

GetName returns the flag's name

func (BoolFlag) IsPersistent 

func (f BoolFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Command 

type Command struct {
	*cobra.Command
}

Command contains a cobra.Command

func NewCommand 

func NewCommand(cmd *cobra.Command) *Command

NewCommand returns a a Command

func (*Command) AddCobraCommand 

func (c *Command) AddCobraCommand(cmds ...*cobra.Command)

AddCobraCommand adds one or more cobra commands to this parent command.

func (*Command) AddCommand 

func (c *Command) AddCommand(cmds ...*Command)

AddCommand adds one or more commands to this parent command.

func (*Command) AddFlag 

func (c *Command) AddFlag(fs ...Flag) error

AddFlag adds one or more commands to this command

func (*Command) CobraCommands 

func (c *Command) CobraCommands() []*cobra.Command

CobraCommands returns a sorted slice of child cobra commands.

func (*Command) Commands 

func (c *Command) Commands() []*Command

Commands returns a sorted slice of child commands.

func (*Command) RemoveCobraCommand 

func (c *Command) RemoveCobraCommand(cmds ...*cobra.Command)

RemoveCobraCommand removes one or more cobra commands from a parent command.

func (*Command) RemoveCommand 

func (c *Command) RemoveCommand(cmds ...*Command)

RemoveCommand removes one or more commands from a parent command.

type DurationFlag 

type DurationFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue time.Duration
	// points to a variable in which to store the value of the flag
	Destination *time.Duration
}

DurationFlag is a flag of type time.Duration

func (DurationFlag) ApplyTo 

func (f DurationFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (DurationFlag) GetName 

func (f DurationFlag) GetName() string

GetName returns the flag's name

func (DurationFlag) IsPersistent 

func (f DurationFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Flag 

type Flag interface {
	// IsPersistent specify whether the flag is persistent
	IsPersistent() bool
	// GetName returns the flag's name
	GetName() string
	// ApplyTo adds the flag to a given FlagSet
	ApplyTo(*pflag.FlagSet) error
}

Flag describes a flag interface

type Float32Flag 

type Float32Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue float32
	// points to a variable in which to store the value of the flag
	Destination *float32
}

Float32Flag is a flag of type float32

func (Float32Flag) ApplyTo 

func (f Float32Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Float32Flag) GetName 

func (f Float32Flag) GetName() string

GetName returns the flag's name

func (Float32Flag) IsPersistent 

func (f Float32Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Float64Flag 

type Float64Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue float64
	// points to a variable in which to store the value of the flag
	Destination *float64
}

Float64Flag is a flag of type float64

func (Float64Flag) ApplyTo 

func (f Float64Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Float64Flag) GetName 

func (f Float64Flag) GetName() string

GetName returns the flag's name

func (Float64Flag) IsPersistent 

func (f Float64Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Int32Flag 

type Int32Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue int32
	// points to a variable in which to store the value of the flag
	Destination *int32
}

Int32Flag is a flag of type int32

func (Int32Flag) ApplyTo 

func (f Int32Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Int32Flag) GetName 

func (f Int32Flag) GetName() string

GetName returns the flag's name

func (Int32Flag) IsPersistent 

func (f Int32Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Int64Flag 

type Int64Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue int64
	// points to a variable in which to store the value of the flag
	Destination *int64
}

Int64Flag is a flag of type int64

func (Int64Flag) ApplyTo 

func (f Int64Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Int64Flag) GetName 

func (f Int64Flag) GetName() string

GetName returns the flag's name

func (Int64Flag) IsPersistent 

func (f Int64Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type IntFlag 

type IntFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue int
	// points to a variable in which to store the value of the flag
	Destination *int
}

IntFlag is a flag of type int

func (IntFlag) ApplyTo 

func (f IntFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (IntFlag) GetName 

func (f IntFlag) GetName() string

GetName returns the flag's name

func (IntFlag) IsPersistent 

func (f IntFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type StringFlag 

type StringFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue string
	// points to a variable in which to store the value of the flag
	Destination *string
}

StringFlag is a flag of type string

func (StringFlag) ApplyTo 

func (f StringFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (StringFlag) GetName 

func (f StringFlag) GetName() string

GetName returns the flag's name

func (StringFlag) IsPersistent 

func (f StringFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type StringSliceFlag 

type StringSliceFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue []string
	// points to a variable in which to store the value of the flag
	Destination *[]string
}

StringSliceFlag is a flag of type []string

func (StringSliceFlag) ApplyTo 

func (f StringSliceFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (StringSliceFlag) GetName 

func (f StringSliceFlag) GetName() string

GetName returns the flag's name

func (StringSliceFlag) IsPersistent 

func (f StringSliceFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Uint32Flag 

type Uint32Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue uint32
	// points to a variable in which to store the value of the flag
	Destination *uint32
}

Uint32Flag is a flag of type uint32

func (Uint32Flag) ApplyTo 

func (f Uint32Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Uint32Flag) GetName 

func (f Uint32Flag) GetName() string

GetName returns the flag's name

func (Uint32Flag) IsPersistent 

func (f Uint32Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type Uint64Flag 

type Uint64Flag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue uint64
	// points to a variable in which to store the value of the flag
	Destination *uint64
}

Uint64Flag is a flag of type uint64

func (Uint64Flag) ApplyTo 

func (f Uint64Flag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (Uint64Flag) GetName 

func (f Uint64Flag) GetName() string

GetName returns the flag's name

func (Uint64Flag) IsPersistent 

func (f Uint64Flag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

type UintFlag 

type UintFlag struct {
	// Name as it appears on command line
	Name string
	// one-letter abbreviated flag
	Shorthand string
	// help message
	Usage string
	// specify whether the flag is persistent
	Persistent bool
	// used by cobra.Command bash autocomple code
	Annotations map[string][]string
	// If this flag is deprecated, this string is the new or now thing to use
	Deprecated string
	// If the shorthand of this flag is deprecated, this string is the new or now thing to use
	ShorthandDeprecated string
	// used by cobra.Command to allow flags to be hidden from help/usage text
	Hidden bool
	// bind the flag to env key, you can use AutomaticEnv to bind all flags to env automatically
	// if EnvKey is set, it will override the automatic generated env key
	EnvKey string
	// the default value
	DefValue uint
	// points to a variable in which to store the value of the flag
	Destination *uint
}

UintFlag is a flag of type uint

func (UintFlag) ApplyTo 

func (f UintFlag) ApplyTo(fs *pflag.FlagSet) error

ApplyTo adds the flag to given FlagSet

func (UintFlag) GetName 

func (f UintFlag) GetName() string

GetName returns the flag's name

func (UintFlag) IsPersistent 

func (f UintFlag) IsPersistent() bool

IsPersistent specify whether the flag is persistent

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.