Documentation ¶
Overview ¶
Package cliapp is a simple to use command line application, written using golang
Source code and other details for the project are available at GitHub:
https://github.com/gookit/cliapp
usage please ref examples and README
Index ¶
- Constants
- Variables
- func AllCommands() map[string]*Command
- func Exit(code int)
- func Logf(level uint, format string, v ...interface{})
- func Print(args ...interface{})
- func Printf(format string, args ...interface{})
- func Println(args ...interface{})
- func Verbose() uint
- type Application
- func (app *Application) Add(c *Command, more ...*Command)
- func (app *Application) AddAliases(command string, names []string)
- func (app *Application) AddError(err error)
- func (app *Application) AddVar(name string, value string)
- func (app *Application) AddVars(vars map[string]string)
- func (app *Application) CommandName() string
- func (app *Application) CommandNames() []string
- func (app *Application) Commands() map[string]*Command
- func (app *Application) DebugMode()
- func (app *Application) DefaultCommand(name string)
- func (app *Application) GetVar(name string) string
- func (app *Application) GetVars(name string, value string) map[string]string
- func (app *Application) Initialize()
- func (app *Application) IsCommand(name string) bool
- func (app *Application) On(name string, handler func(a *Application, data interface{}))
- func (app *Application) QuietMode()
- func (app *Application) RealCommandName(alias string) string
- func (app *Application) Run()
- func (app *Application) SetLogo(logo string, style ...string)
- func (app *Application) SetVerbose(verbose uint)
- func (app *Application) SubRun(name string, args []string) int
- type Argument
- type Booleans
- type CmdFunc
- type CmdLine
- type Command
- func (c *Command) AddArg(name, description string, requiredAndIsArray ...bool) *Argument
- func (c *Command) AddVars(vars map[string]string)
- func (c *Command) AliasesString(sep ...string) string
- func (c *Command) AloneRun() int
- func (c *Command) App() *Application
- func (c *Command) Arg(name string) *Argument
- func (c *Command) ArgByIndex(i int) *Argument
- func (c *Command) Args() []*Argument
- func (c *Command) BoolOpt(p *bool, name string, short string, defValue bool, description string) *Command
- func (c *Command) Copy() *Command
- func (c *Command) Disable()
- func (c *Command) Error() error
- func (c *Command) Errorf(format string, v ...interface{}) int
- func (c *Command) Execute(args []string) int
- func (c *Command) GetVar(name string) string
- func (c *Command) IntOpt(p *int, name string, short string, defValue int, description string) *Command
- func (c *Command) IsAlone() bool
- func (c *Command) IsDisabled() bool
- func (c *Command) Logf(level uint, format string, v ...interface{})
- func (c *Command) NotAlone() bool
- func (c *Command) On(name string, handler func(c *Command, data interface{}))
- func (c *Command) OptDes(name string) string
- func (c *Command) OptFlag(name string) *flag.Flag
- func (c *Command) OptNames() map[string]string
- func (c *Command) ParseDefaults() string
- func (c *Command) RawArg(i int) string
- func (c *Command) RawArgs() []string
- func (c *Command) Runnable() bool
- func (c *Command) ShortName(name string) string
- func (c *Command) ShowHelp(quit ...bool)
- func (c *Command) StrOpt(p *string, name string, short string, defValue string, description string) *Command
- func (c *Command) UintOpt(p *uint, name string, short string, defValue uint, description string) *Command
- func (c *Command) VarOpt(p flag.Value, name string, short string, description string) *Command
- func (c *Command) WithError(err error) int
- type GlobalOpts
- type HookFunc
- type Ints
- type Logo
- type Runner
- type Strings
Constants ¶
const ( VerbQuiet uint = iota // don't report anything VerbError // reporting on error VerbWarn VerbInfo VerbDebug VerbCrazy )
constants for error level 0 - 4
const ( EvtInit = "init" EvtBefore = "before" EvtAfter = "after" EvtError = "error" )
constants for hooks event, there are default allowed hook names
const ( // OK success exit code OK = 0 // ERR error exit code ERR = 2 )
const HelpVar = "{$%s}"
HelpVar allow var replace in help info. default support:
"{$binName}" "{$cmd}" "{$fullCmd}" "{$workDir}"
Variables ¶
var CLI = &CmdLine{ pid: os.Getpid(), osName: runtime.GOOS, binName: os.Args[0], argsStr: strings.Join(os.Args[1:], " "), }
create a default instance
Functions ¶
Types ¶
type Application ¶
type Application struct { // internal use *CmdLine // Name app name Name string // Version app version. like "1.0.1" Version string // Description app description Description string // Logo ASCII logo setting Logo Logo // Hooks can setting some hooks func on running. // allow hooks: "init", "before", "after", "error" Hooks map[string]appHookFunc // Strict use strict mode. short opt must be begin '-', long opt must be begin '--' Strict bool // contains filtered or unexported fields }
Application the cli app definition
func New ¶
func New(fn ...func(a *Application)) *Application
NewApp create new app eg:
cliapp.NewApp() cliapp.NewApp(func(a *Application) { // do something before init .... a.Hooks[cliapp.EvtInit] = func () {} })
func NewApp ¶
func NewApp(fn ...func(a *Application)) *Application
New create new app instance eg:
cliapp.New() cliapp.New(func(a *Application) { // do something before init .... a.Hooks[cliapp.EvtInit] = func () {} })
func (*Application) Add ¶
func (app *Application) Add(c *Command, more ...*Command)
Add add a command
func (*Application) AddAliases ¶
func (app *Application) AddAliases(command string, names []string)
AddAliases add alias names for a command
func (*Application) AddError ¶
func (app *Application) AddError(err error)
AddError to the application
func (*Application) AddVar ¶
func (app *Application) AddVar(name string, value string)
AddVar get command name
func (*Application) AddVars ¶
func (app *Application) AddVars(vars map[string]string)
AddVars add multi tpl vars
func (*Application) CommandName ¶
func (app *Application) CommandName() string
CommandName get current command name
func (*Application) CommandNames ¶
func (app *Application) CommandNames() []string
CommandNames get all command names
func (*Application) Commands ¶
func (app *Application) Commands() map[string]*Command
Commands get all commands
func (*Application) DefaultCommand ¶
func (app *Application) DefaultCommand(name string)
DefaultCommand set default command name
func (*Application) GetVar ¶
func (app *Application) GetVar(name string) string
GetVar get a help var by name
func (*Application) GetVars ¶
func (app *Application) GetVars(name string, value string) map[string]string
GetVars get all tpl vars
func (*Application) IsCommand ¶
func (app *Application) IsCommand(name string) bool
IsCommand name check
func (*Application) On ¶
func (app *Application) On(name string, handler func(a *Application, data interface{}))
On add hook handler for a hook event
func (*Application) RealCommandName ¶
func (app *Application) RealCommandName(alias string) string
RealCommandName get real command name by alias
func (*Application) SetLogo ¶
func (app *Application) SetLogo(logo string, style ...string)
SetLogo text and color style
type Argument ¶
type Argument struct { // Name argument name Name string // ShowName is a name for display help. default is equals to Name. ShowName string // Description argument description message Description string // IsArray if is array, can allow accept multi values, and must in last. IsArray bool // Required arg is required Required bool // value store parsed argument data. (type: string, []string) Value interface{} // contains filtered or unexported fields }
Argument a command argument definition
type CmdLine ¶
type CmdLine struct {
// contains filtered or unexported fields
}
CmdLine store common data for CLI
func (*CmdLine) ArgsString ¶
ArgsString os.Args to string, but no binName.
type Command ¶
type Command struct { // is internal use *CmdLine // Name is the command name. Name string // Func is the command handler func. // Func Runner Func CmdFunc // Config func, will call on `initialize`. you can config options and other works Config func(c *Command) // Hooks can setting some hooks func on running. // allow hooks: "init", "before", "after", "error" Hooks map[string]HookFunc // Aliases is the command name's alias names Aliases []string // UseFor is the command description message. UseFor string // Flags(command options) is a set of flags specific to this command. Flags flag.FlagSet // CustomFlags indicates that the command will do its own flag parsing. CustomFlags bool // Vars you can add some vars map for render help info Vars map[string]string // Help is the long help message text Help string // Examples some usage example display Examples string // contains filtered or unexported fields }
Command a CLI command structure
func (*Command) AddArg ¶
AddArg binding a named argument for the command. Notice:
- Required argument cannot be defined after optional argument
- Only one array parameter is allowed
- The (array) argument of multiple values can only be defined at the end
usage:
cmd.AddArg("name", "description") cmd.AddArg("name", "description", true) // required cmd.AddArg("names", "description", true, true) // required and is array
func (*Command) AliasesString ¶
AliasesString returns aliases string
func (*Command) Arg ¶
Arg get arg by defined name. usage:
intVal := c.Arg("name").Int() strVal := c.Arg("name").String() arrVal := c.Arg("names").Array()
func (*Command) ArgByIndex ¶
ArgByIndex get named arg by index
func (*Command) BoolOpt ¶
func (c *Command) BoolOpt(p *bool, name string, short string, defValue bool, description string) *Command
BoolOpt binding a bool option
func (*Command) IntOpt ¶
func (c *Command) IntOpt(p *int, name string, short string, defValue int, description string) *Command
IntOpt binding a int option
func (*Command) ParseDefaults ¶
ParseDefaults prints, to standard error unless configured otherwise, the default values of all defined command-line flags in the set. See the documentation for the global function PrintDefaults for more information.
NOTICE: the func is copied from package 'flag', func 'PrintDefaults'
func (*Command) Runnable ¶
Runnable reports whether the command can be run; otherwise it is a documentation pseudo-command such as import path.
func (*Command) StrOpt ¶
func (c *Command) StrOpt(p *string, name string, short string, defValue string, description string) *Command
StrOpt binding a string option
func (*Command) UintOpt ¶
func (c *Command) UintOpt(p *uint, name string, short string, defValue uint, description string) *Command
UintOpt binding a uint option
type GlobalOpts ¶
type GlobalOpts struct {
// contains filtered or unexported fields
}
GlobalOpts global flags