kli

package module
v0.0.0-...-53a4af4 Latest Latest
Warning

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

Go to latest
Published: Jul 15, 2019 License: MIT Imports: 11 Imported by: 0

README

kli

An Expressive command line interface builder.

features
  • No creation of multiple flag pointers
  • Easy child/parent relashionships (sub-commands)
  • Support for global flags
  • easy to test
  • expressive command declaration
NOTE

still in early development


Usage
//create the root command
root := kli.NewCommand("cow", flag.ExitOnError)
root.Bool("eat", false, "informs the cow to eat")
root.Do(func(cmd kli.Command, _ kli.KFlag) kli.CmdError {
    isEating, _ := cmd.BoolFlag("eat")
    if isEating {
        fmt.Println(strings.Repeat("munch ", 3))
    } else {
        fmt.Println("the cow stands there looking smug")
    }
    return nil
})

//declare the sub command
sub := kli.NewCommand("say", flag.ExitOnError)
sub.String("what", "mooooo", "what the cow will say")
sub.Int("repeat", 1, "how many time it repeats the word")
sub.Do(func(cmd kli.Command, globals kli.KFlag) kli.CmdError {
    if isEating, ok := globals.BoolFlag("eat"); ok {
        if isEating {
            fmt.Println("munch... can't say anything, I'm eating")
            return nil
        }
    }

    what, _ := cmd.StringFlag("what")
    repeat, _ := cmd.IntFlag("repeat")
    for i := 1; i <= repeat; i++ {
        fmt.Println(what)
    }
    return nil
})

//add the subcommand to the root command
err := root.SetChildren(sub)
if err != nil {
    panic(err)
}

//create the app with the root command
app := &kli.App{}
app.SetRoot(root)

//run the app with the context default
// the context default are the os.Args
app.Run(kli.NewContext().Default())

Documentation

Index

Constants

View Source
const (
	OK              = 0   //ok
	GeneralError    = 1   //Catchall for general errors	let "var1 = 1/0"	Miscellaneous errors, such as "divide by zero" and other impermissible operations
	MisuseError     = 2   //Misuse of shell builtins (according to Bash documentation)	empty_function() {}	Missing keyword or command, or permission problem (and diff return code on a failed binary file comparison).
	CannotExecute   = 126 //Command invoked cannot execute	/dev/null	Permission problem or command is not an executable
	NotFount        = 127 //"command not found"	illegal_command	Possible problem with $PATH or a typo
	InvalidArgument = 128 //Invalid argument to exit	exit 3.14159	exit takes only integer args in the range 0 - 255 (see first footnote)
	UserTermination = 130 //Script terminated by Control-C	Ctl-C	Control-C is fatal error signal 2, (130 = 128 + 2, see above)
	OutOfRange      = 255 //*	Exit status out of range	exit -1	exit takes only integer args in the range 0 - 255
)

unix command error code as per https://www.tldp.org/LDP/abs/html/exitcodes.html

Variables

This section is empty.

Functions

This section is empty.

Types

type App

type App struct {
	// contains filtered or unexported fields
}

func (*App) Run

func (a *App) Run(ctx *Context)

Run runs the app with the given argument list usually it's the os.Args[1:]

func (*App) SetRoot

func (a *App) SetRoot(root Command)

type CMD

type CMD struct {
	*flag.FlagSet
	KFlag
	// contains filtered or unexported fields
}

func NewCommand

func NewCommand(name string, handling flag.ErrorHandling) *CMD

func NewSubCommand

func NewSubCommand(parent Command, name string, handling flag.ErrorHandling) *CMD

func (*CMD) Bool

func (c *CMD) Bool(name string, value bool, usage string)

func (*CMD) Children

func (c *CMD) Children() []Command

Children returns the command's children command (it's sub-command)

func (*CMD) Description

func (c *CMD) Description(desc string)

Description sets the command's description

func (*CMD) Detail

func (c *CMD) Detail(detail io.Reader)

func (*CMD) Do

func (c *CMD) Do(fn func(Command, KFlag) Error)

func (*CMD) Duration

func (c *CMD) Duration(name string, value time.Duration, usage string)

func (*CMD) Execute

func (c *CMD) Execute(cmd Command, f KFlag) Error

func (*CMD) Float64

func (c *CMD) Float64(name string, value float64, usage string)

func (*CMD) GetKFlag

func (c *CMD) GetKFlag() KFlag

func (*CMD) Int

func (c *CMD) Int(name string, value int, usage string)

func (*CMD) Int64

func (c *CMD) Int64(name string, value int64, usage string)

func (*CMD) IsExecutable

func (c *CMD) IsExecutable() bool

func (*CMD) Parent

func (c *CMD) Parent() Command

Parent return the command's parent command

func (*CMD) PrintDefaults

func (c *CMD) PrintDefaults()

func (*CMD) SetChildren

func (c *CMD) SetChildren(children ...Command) error

SetChildren sets the children (sub-command) the method also sets the parent of the children command as the current command

func (*CMD) SetParent

func (c *CMD) SetParent(parent Command) error

setParent

func (*CMD) String

func (c *CMD) String(name string, value string, usage string)

func (*CMD) Uint

func (c *CMD) Uint(name string, value uint, usage string)

func (*CMD) Uint64

func (c *CMD) Uint64(name string, value uint64, usage string)

type Command

type Command interface {
	KFlag

	// Description sets the shot description (except) of the Command
	Description(desc string)

	// Detail sets the Command details, it's the long description
	// like example
	Detail(detail io.Reader)

	// Do sets the function to be called on execution
	Do(fn func(Command, KFlag) Error)

	// Parse parses flag definitions from the argument
	// list, which should not include the command name.
	// Must be called after all flags in the
	// FlagSet are defined and before flags are accessed by the program.
	// The return value will be ErrHelp if -help or -h were set but not defined.
	Parse([]string) error

	// Args returns the non-flag arguments.
	Args() []string

	// Name returns the name of the command
	Name() string

	// Execute calls the function that what set by Command::Do
	// returns a Error function not found if the
	// execute function was not set
	Execute(Command, KFlag) Error

	// IsExecutable returns true if the command executing
	// function has been set
	IsExecutable() bool

	// GetKFlag returns the command Kflag
	GetKFlag() KFlag

	// SetChildren sets the Command Children
	SetChildren(children ...Command) error

	Children() []Command

	// returns the Command's parent Command
	Parent() Command

	// SetParent sets the Command's Parent
	SetParent(parent Command) error

	// PrintDefaults prints, to standard error unless configured otherwise,
	PrintDefaults()

	// Bool sets a flag of type Bool
	Bool(name string, value bool, usage string)

	// Duration sets a flag of type time.Duration (int64)
	Duration(name string, value time.Duration, usage string)

	// Float64 sets a flag of type float64
	Float64(name string, value float64, usage string)

	// Int sets a flag of type Int
	Int(name string, value int, usage string)

	// Int64 sets a flag of type Int64
	Int64(name string, value int64, usage string)

	// String sets a flag of type string
	String(name string, value string, usage string)

	// Uint sets a flag of type Uint
	Uint(name string, value uint, usage string)

	// Uint64 sets a flag of type Uint64
	Uint64(name string, value uint64, usage string)
}

todo review the interface ... it's quite big

type Context

type Context struct {
	// contains filtered or unexported fields
}

todo create a proper context with timeout that has similar functionality as the http.context else it's a bit confusing

func NewContext

func NewContext() *Context

func (*Context) Args

func (c *Context) Args() []string

func (*Context) Default

func (c *Context) Default() *Context

func (*Context) SetArgs

func (c *Context) SetArgs(args []string) *Context

type Error

type Error interface {
	error
	Code() int
}

type FlagStore

type FlagStore struct {
	// contains filtered or unexported fields
}

func NewKflag

func NewKflag() *FlagStore

func (*FlagStore) BoolFlag

func (a *FlagStore) BoolFlag(name string) (value, ok bool)

func (*FlagStore) DurationFlag

func (a *FlagStore) DurationFlag(name string) (value time.Duration, ok bool)

func (*FlagStore) Float64Flag

func (a *FlagStore) Float64Flag(name string) (value float64, ok bool)

func (*FlagStore) Int64Flag

func (a *FlagStore) Int64Flag(name string) (value int64, ok bool)

func (*FlagStore) IntFlag

func (a *FlagStore) IntFlag(name string) (value int, ok bool)

func (*FlagStore) SetFlag

func (a *FlagStore) SetFlag(name string, ptr interface{})

func (*FlagStore) Store

func (a *FlagStore) Store() map[string]reflect.Kind

func (*FlagStore) StringFlag

func (a *FlagStore) StringFlag(name string) (value string, ok bool)

func (*FlagStore) Uint64Flag

func (a *FlagStore) Uint64Flag(name string) (value uint64, ok bool)

func (*FlagStore) UintFlag

func (a *FlagStore) UintFlag(name string) (value uint, ok bool)

type KError

type KError struct {
	// contains filtered or unexported fields
}

func ErrorWrap

func ErrorWrap(err error, text string, code int) *KError

func NewError

func NewError(text string, code int) *KError

func NewErrorf

func NewErrorf(code int, format string, a ...interface{}) *KError

func (KError) Code

func (ke KError) Code() int

func (KError) Error

func (ke KError) Error() string

type KFlag

type KFlag interface {
	// Store returns a list of set flags with their reflect.Kind
	Store() map[string]reflect.Kind

	// Set sets a new flag
	SetFlag(name string, ptr interface{})

	// BoolFlag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	BoolFlag(name string) (value, ok bool)

	// DurationFlag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	DurationFlag(name string) (value time.Duration, ok bool)

	// Float64Flag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	Float64Flag(name string) (value float64, ok bool)

	// IntFlag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	IntFlag(name string) (value int, ok bool)

	// Int64Flag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	Int64Flag(name string) (value int64, ok bool)

	// StringFlag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	StringFlag(name string) (value string, ok bool)

	// UintFlag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	UintFlag(name string) (value uint, ok bool)

	// Uint64Flag return the value of the flag "name"
	// ok is false if the flag does not exist or of wrong type
	Uint64Flag(name string) (value uint64, ok bool)
}

Directories

Path Synopsis
examples

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL