README
¶
GCli
A simple-to-use command line application, written using golang.
中文说明
中文说明请看 README.zh-CN
Screenshots
Features
- Simple to use
- Support for adding multiple commands and supporting command aliases
- Support binding command options from structure
- example
flag:"name=int0;shorts=i;required=true;desc=int option message"
- example
- Support for adding multi-level commands, each level of command supports binding its own options
option/flag- support option binding--long, support for adding short options(-s)- POSIX-style short flag combining (
-a -b=-ab) - Support setting
Required, indicating a required option parameter - Support setting
Validator, which can customize the validation input parameters
- POSIX-style short flag combining (
argument- support binding argument to specify name- Support
required, optional,arraysettings - It will be automatically detected and collected when the command is run.
- Support
colorable- supports rich color output. provide by gookit/color- Supports html tab-style color rendering, compatible with Windows
- Built-in
info, error, success, dangerand other styles, can be used directly
interactBuilt-in user interaction methods:ReadLine,Confirm,Select,MultiSelect...progressBuilt-in progress display methods:Txt,Bar,Loading,RoundTrip,DynamicText...- Automatically generate command help information and support color display
- When the command entered is incorrect, a similar command will be prompted(including an alias prompt)
- Supports generation of
zshandbashcommand completion script files - Supports a single command as a stand-alone application
GoDoc
Install
go get github.com/gookit/gcli/v3
Quick start
package main
import (
"runtime"
"github.com/gookit/gcli/v3"
"github.com/gookit/gcli/v3/_examples/cmd"
)
// for test run: go build ./_examples/cliapp.go && ./cliapp
func main() {
app := gcli.NewApp()
app.Version = "1.0.3"
app.Desc = "this is my cli application"
// app.SetVerbose(gcli.VerbDebug)
app.Add(cmd.ExampleCommand())
app.Add(&gcli.Command{
Name: "demo",
// allow color tag and {$cmd} will be replace to 'demo'
Desc: "this is a description <info>message</> for {$cmd}",
Aliases: []string{"dm"},
Func: func (cmd *gcli.Command, args []string) error {
gcli.Print("hello, in the demo command\n")
return 0
},
})
// .... add more ...
app.Run()
}
Usage
- build a demo package
% go build ./_examples/cliapp.go
Display version
% ./cliapp --version
# or use -V
% ./cliapp -V
Display app help
by
./cliappor./cliapp -hor./cliapp --help
Examples:
./cliapp
./cliapp -h # can also
./cliapp --help # can also
Run Command
./cliapp COMMAND [--OPTION VALUE -S VALUE ...] [ARGUMENT0 ARGUMENT1 ...]
% ./cliapp example -c some.txt -d ./dir --id 34 -n tom -n john val0 val1 val2 arrVal0 arrVal1 arrVal2
you can see:
Display Command Help
by
./cliapp example -hor./cliapp example --help
Error Command Tips
Generate Auto Completion Scripts
import "github.com/gookit/gcli/v3/builtin"
// ...
// add gen command(gen successful you can remove it)
app.Add(builtin.GenAutoComplete())
Build and run command(This command can be deleted after success.)：
% go build ./_examples/cliapp.go && ./cliapp genac -h // display help
% go build ./_examples/cliapp.go && ./cliapp genac // run gen command
will see:
INFO:
{shell:zsh binName:cliapp output:auto-completion.zsh}
Now, will write content to file auto-completion.zsh
Continue? [yes|no](default yes): y
OK, auto-complete file generate successful
After running, it will generate an
auto-completion.{zsh|bash}file in the current directory, and the shell environment name is automatically obtained. Of course you can specify it manually at runtime
Generated shell script file ref：
- bash env auto-completion.bash
- zsh env auto-completion.zsh
Preview:
Write a command
Quick add
app.Add(&gcli.Command{
Name: "demo",
// allow color tag and {$cmd} will be replace to 'demo'
Desc: "this is a description <info>message</> for command {$cmd}",
Aliases: []string{"dm"},
Func: func (cmd *gcli.Command, args []string) error {
gcli.Print("hello, in the demo command\n")
return nil
},
})
Write go file
the source file at: example.go
package cmd
import (
"fmt"
"github.com/gookit/color"
"github.com/gookit/gcli/v3"
)
// options for the command
var exampleOpts = struct {
id int
c string
dir string
opt string
names gcli.Strings
}{}
// ExampleCommand command definition
var ExampleCommand = &gcli.Command{
Name: "example",
Desc: "this is a description message",
Aliases: []string{"exp", "ex"}, // 命令别名
// {$binName} {$cmd} is help vars. '{$cmd}' will replace to 'example'
Examples: `{$binName} {$cmd} --id 12 -c val ag0 ag1
<cyan>{$fullCmd} --names tom --names john -n c</> test use special option`,
Config: func(c *gcli.Command) {
// 绑定命令选项信息
c.IntOpt(&exampleOpts.id, "id", "", 2, "the id option")
c.StrOpt(&exampleOpts.c, "config", "c", "value", "the config option")
// notice `DIRECTORY` will replace to option value type
c.StrOpt(&exampleOpts.dir, "dir", "d", "", "the `DIRECTORY` option")
// 支持设置选项短名称
c.StrOpt(&exampleOpts.opt, "opt", "o", "", "the option message")
// 支持绑定自定义变量, 但必须实现 flag.Value 接口
c.VarOpt(&exampleOpts.names, "names", "n", "the option message")
// 绑定命令参数信息，按参数位置绑定
c.AddArg("arg0", "the first argument, is required", true)
c.AddArg("arg1", "the second argument, is required", true)
c.AddArg("arg2", "the optional argument, is optional")
c.AddArg("arrArg", "the array argument, is array", false, true)
},
Func: exampleExecute,
}
// 命令执行主逻辑代码
// example run:
// go run ./_examples/cliapp.go ex -c some.txt -d ./dir --id 34 -n tom -n john val0 val1 val2 arrVal0 arrVal1 arrVal2
func exampleExecute(c *gcli.Command, args []string) error {
fmt.Print("hello, in example command\n")
magentaln := color.Magenta.Println
magentaln("All options:")
fmt.Printf("%+v\n", exampleOpts)
magentaln("Raw args:")
fmt.Printf("%v\n", args)
magentaln("Get arg by name:")
arr := c.Arg("arrArg")
fmt.Printf("named array arg '%s', value: %v\n", arr.Name, arr.Value)
magentaln("All named args:")
for _, arg := range c.Args() {
fmt.Printf("named arg '%s': %+v\n", arg.Name, *arg)
}
return nil
}
- display the command help：
go build ./_examples/cliapp.go && ./cliapp example -h
Bind Option(flag)
Available methods:
BoolOpt(p *bool, name, shorts string, defValue bool, desc string)
BoolVar(p *bool, meta FlagMeta)
Float64Opt(p *float64, name, shorts string, defValue float64, desc string)
Float64Var(p *float64, meta FlagMeta)
Int64Opt(p *int64, name, shorts string, defValue int64, desc string)
Int64Var(p *int64, meta FlagMeta)
IntOpt(p *int, name, shorts string, defValue int, desc string)
IntVar(p *int, meta FlagMeta)
StrOpt(p *string, name, shorts, defValue, desc string)
StrVar(p *string, meta FlagMeta)
Uint64Opt(p *uint64, name, shorts string, defValue uint64, desc string)
Uint64Var(p *uint64, meta FlagMeta)
UintOpt(p *uint, name, shorts string, defValue uint, desc string)
UintVar(p *uint, meta FlagMeta)
Var(p flag.Value, meta FlagMeta)
VarOpt(p flag.Value, name, shorts, desc string)
Usage examples:
var id int
var b bool
var opt, dir string
var f1 float64
var names gcli.Strings
// bind options
cmd.IntOpt(&id, "id", "", 2, "the id option")
cmd.BoolOpt(&b, "bl", "b", false, "the bool option")
// notice `DIRECTORY` will replace to option value type
cmd.StrOpt(&dir, "dir", "d", "", "the `DIRECTORY` option")
// setting option name and short-option name
cmd.StrOpt(&opt, "opt", "o", "", "the option message")
// setting a special option var, it must implement the flag.Value interface
cmd.VarOpt(&names, "names", "n", "the option message")
Bind Argument
About arguments:
- 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
Available methods:
Add(arg Argument) *Argument
AddArg(name, desc string, requiredAndIsArray ...bool) *Argument
AddArgument(arg *Argument) *Argument
BindArg(arg Argument) *Argument
Usage examples:
cmd.AddArg("arg0", "the first argument, is required", true)
cmd.AddArg("arg1", "the second argument, is required", true)
cmd.AddArg("arg2", "the optional argument, is optional")
cmd.AddArg("arrArg", "the array argument, is array", false, true)
can also use Arg()/BindArg():
cmd.Arg("arg0", gcli.Argument{
Name: "ag0",
Desc: "the first argument, is required",
Require: true,
})
cmd.BindArg("arg0", gcli.Argument{
Name: "ag0",
Desc: "the second argument, is required",
Require: true,
})
cmd.Arg("arg2", gcli.Argument{
Name: "ag0",
Desc: "the third argument, is is optional",
})
cmd.BindArg("arrArg", gcli.Argument{
Name: "arrArg",
Desc: "the third argument, is is array",
IsArray: true,
})
Progress display
Package progress provide terminal progress bar display.
Such as: Txt, Bar, Loading, RoundTrip, DynamicText ...
progress.Barprogress bar
Demo: ./cliapp prog bar
progress.Txttext progress bar
Demo: ./cliapp prog txt
progress.LoadBarpending/loading progress bar
progress.Countercounterprogress.RoundTripround trip progress bar
[=== ] -> [ === ] -> [ === ]
progress.DynamicTextdynamic text message
Examples:
package main
import (
"time"
"github.com/gookit/gcli/v3/progress"
)
func main() {
speed := 100
maxSteps := 110
p := progress.Bar(maxSteps)
p.Start()
for i := 0; i < maxSteps; i++ {
time.Sleep(time.Duration(speed) * time.Millisecond)
p.Advance()
}
p.Finish()
}
more demos please see progress_demo.go
run demos:
go run ./_examples/cliapp.go prog txt
go run ./_examples/cliapp.go prog bar
go run ./_examples/cliapp.go prog roundTrip
Interactive methods
console interactive methods
interact.ReadInputinteract.ReadLineinteract.ReadFirstinteract.Confirminteract.Select/Choiceinteract.MultiSelect/Checkboxinteract.Question/Askinteract.ReadPassword
Examples:
package main
import (
"fmt"
"github.com/gookit/gcli/v3/interact"
)
func main() {
username, _ := interact.ReadLine("Your name?")
password := interact.ReadPassword("Your password?")
ok := interact.Confirm("ensure continue?")
if !ok {
// do something...
}
fmt.Printf("username: %s, password: %s\n", username, password)
}
Read Input
read user input message
ans, _ := interact.ReadLine("Your name? ")
if ans != "" {
color.Println("Your input: ", ans)
} else {
color.Cyan.Println("No input!")
}
Select/Choice
ans := interact.SelectOne(
"Your city name(use array)?",
[]string{"chengdu", "beijing", "shanghai"},
"",
)
color.Comment.Println("your select is: ", ans)
Multi Select/Checkbox
ans := interact.MultiSelect(
"Your city name(use array)?",
[]string{"chengdu", "beijing", "shanghai"},
nil,
)
color.Comment.Println("your select is: ", ans)
Confirm Message
if interact.Confirm("Ensure continue") {
fmt.Println(emoji.Render(":smile: Confirmed"))
} else {
color.Warn.Println("Unconfirmed")
}
Read Password
pwd := interact.ReadPassword()
color.Comment.Println("your input password is: ", pwd)
CLI Color
Terminal color use gookit/color Support windows
cmd.exepowerShell
- Color output display
Usage
package main
import (
"github.com/gookit/color"
)
func main() {
// simple usage
color.Cyan.Printf("Simple to use %s\n", "color")
// internal theme/style:
color.Info.Tips("message")
color.Info.Prompt("message")
color.Info.Println("message")
color.Warn.Println("message")
color.Error.Println("message")
// custom color
color.New(color.FgWhite, color.BgBlack).Println("custom color style")
// can also:
color.Style{color.FgCyan, color.OpBold}.Println("custom color style")
// use defined color tag
color.Print("use color tag: <suc>he</><comment>llo</>, <cyan>wel</><red>come</>\n")
// use custom color tag
color.Print("custom color tag: <fg=yellow;bg=black;op=underscore;>hello, welcome</>\n")
// set a style tag
color.Tag("info").Println("info style text")
// prompt message
color.Info.Prompt("prompt style message")
color.Warn.Prompt("prompt style message")
// tips message
color.Info.Tips("tips style message")
color.Warn.Tips("tips style message")
}
More usage
- Basic color
color.Bold.Println("bold message")
color.Yellow.Println("yellow message")
- Extra themes
color.Info.Println("Info message")
color.Danger.Println("Danger message")
color.Error.Println("Error message")
color.Success.Println("Success message")
- Use like html tag
Support working on windows
cmd.exepowerShell
// use style tag
color.Print("<suc>he</><comment>llo</>, <cyan>wel</><red>come</>")
color.Println("<suc>hello</>")
color.Println("<error>hello</>")
color.Println("<warning>hello</>")
// custom color attributes
color.Print("<fg=yellow;bg=black;op=underscore;>hello, welcome</>\n")
For more information on the use of color libraries, please visit gookit/color
Gookit packages
- gookit/ini Go config management, use INI files
- gookit/rux Simple and fast request router for golang HTTP
- gookit/gcli build CLI application, tool library, running CLI commands
- gookit/event Lightweight event manager and dispatcher implements by Go
- gookit/cache Generic cache use and cache manager for golang. support File, Memory, Redis, Memcached.
- gookit/config Go config management. support JSON, YAML, TOML, INI, HCL, ENV and Flags
- gookit/color A command-line color library with true color support, universal API methods and Windows support
- gookit/filter Provide filtering, sanitizing, and conversion of golang data
- gookit/validate Use for data validation and filtering. support Map, Struct, Form data
- gookit/goutil Some utils for the Go: string, array/slice, map, format, cli, env, filesystem, test and more
- More please see https://github.com/gookit
See also
inhere/consolehttps://github/inhere/php-consoleissue9/termhttps://github.com/issue9/termbeego/beehttps://github.com/beego/bee- ANSI escape code
License
MIT
Documentation
¶
Overview ¶
Package gcli is a simple to use command line application and tool library.
Contains: cli app, flags parse, interact, progress, data show tools.
Source code and other details for the project are available at GitHub:
https://github.com/gookit/gcli
Usage please refer examples and see README
Index ¶
- Constants
- Variables
- func CommitID() string
- func Debugf(format string, v ...interface{})
- func IsGteVerbose(verb VerbLevel) bool
- func Logf(level VerbLevel, format string, v ...interface{})
- func NotExitOnEnd() func(*App)
- func Print(args ...interface{})
- func Printf(format string, args ...interface{})
- func Println(args ...interface{})
- func ResetGOpts()
- func ResetVerbose()
- func SetCrazyMode()
- func SetDebugMode()
- func SetQuietMode()
- func SetStrictMode(strict bool)
- func SetVerbose(verbose VerbLevel)
- func StrictMode() bool
- func Version() string
- type App
- func (app *App) Add(c *Command, more ...*Command)
- func (app *App) AddAliases(name string, aliases ...string)
- func (app *App) AddCommand(c *Command)
- func (b *App) AddError(err error)
- func (app *App) AddHandler(h Handler)
- func (b *App) AliasesMapping() map[string]string
- func (b *App) CmdAliases() *structs.Aliases
- func (b *App) CmdNameMap() map[string]int
- func (b *App) CmdNames() []string
- func (b *App) Command(name string) (c *Command, exist bool)
- func (app *App) CommandName() string
- func (b *App) CommandNames() []string
- func (b *App) Commands() map[string]*Command
- func (app *App) Config(fn func(a *App))
- func (app *App) Exec(path string, args []string) error
- func (app *App) Exit(code int)
- func (b *App) FindByPath(path string) *Command
- func (b *App) FindCommand(path string) *Command
- func (app *App) Fire(event string, data interface{}) bool
- func (b *App) GetCommand(name string) *Command
- func (c App) GlobalFlags() *Flags
- func (b *App) HasCommand(name string) bool
- func (b *App) HasCommands() bool
- func (app *App) HasSubcommands() bool
- func (b *App) IsAlias(alias string) bool
- func (b *App) IsCommand(name string) bool
- func (b *App) Match(names []string) *Command
- func (b *App) MatchByPath(path string) *Command
- func (app *App) On(name string, handler HookFunc)
- func (c App) RawOsArgs() []string
- func (b *App) ResolveAlias(alias string) string
- func (app *App) Run(args []string) (code int)
- func (app *App) RunLine(argsLine string) int
- func (app *App) SetDefaultCommand(name string)
- func (b *App) SetLogo(logo string, style ...string)
- type Argument
- func (a *Argument) Array() (ss []string)
- func (a *Argument) GetValue() interface{}
- func (a *Argument) HasValue() bool
- func (a *Argument) HelpName() string
- func (a *Argument) Index() int
- func (a *Argument) Init() *Argument
- func (a *Argument) Int(defVal ...int) int
- func (a *Argument) IsEmpty() bool
- func (a *Argument) SetValue(val interface{}) error
- func (a *Argument) String(defVal ...string) string
- func (a *Argument) StringSplit(sep ...string) (ss []string)
- func (a *Argument) Strings() (ss []string)
- func (a *Argument) With(fn func(arg *Argument)) *Argument
- func (a *Argument) WithValidator(fn func(interface{}) (interface{}, error)) *Argument
- type Arguments
- func (ags *Arguments) AddArg(name, desc string, requiredAndIsArray ...bool) *Argument
- func (ags *Arguments) AddArgument(arg *Argument) *Argument
- func (ags *Arguments) Arg(name string) *Argument
- func (ags *Arguments) ArgByIndex(i int) *Argument
- func (ags *Arguments) Args() []*Argument
- func (ags *Arguments) BindArg(arg *Argument) *Argument
- func (ags *Arguments) HasArg(name string) bool
- func (ags *Arguments) HasArgs() bool
- func (ags *Arguments) HasArguments() bool
- func (ags *Arguments) ParseArgs(args []string) (err error)
- func (ags *Arguments) SetName(name string)
- func (ags *Arguments) SetValidateNum(validateNum bool)
- type Booleans
- type Command
- func (c *Command) Add(sub *Command, more ...*Command)
- func (c *Command) AddCommand(sub *Command)
- func (b *Command) AddError(err error)
- func (c *Command) AddSubs(sub *Command, more ...*Command)
- func (b *Command) AliasesMapping() map[string]string
- func (c *Command) AliasesString(sep ...string) string
- func (c *Command) App() *App
- func (c *Command) AttachTo(app *App)
- func (b *Command) CmdAliases() *structs.Aliases
- func (b *Command) CmdNameMap() map[string]int
- func (b *Command) CmdNames() []string
- func (b *Command) Command(name string) (c *Command, exist bool)
- func (b *Command) CommandNames() []string
- func (b *Command) Commands() map[string]*Command
- func (c *Command) Copy() *Command
- func (c *Command) Disable()
- func (c *Command) Errorf(format string, v ...interface{}) error
- func (b *Command) FindByPath(path string) *Command
- func (b *Command) FindCommand(path string) *Command
- func (c *Command) Fire(event string, data interface{}) (stop bool)
- func (c *Command) GFlags() *Flags
- func (b *Command) GetCommand(name string) *Command
- func (c Command) GlobalFlags() *Flags
- func (b *Command) HasCommand(name string) bool
- func (b *Command) HasCommands() bool
- func (c *Command) HelpDesc() (desc string)
- func (c *Command) ID() string
- func (c *Command) Init()
- func (b *Command) IsAlias(alias string) bool
- func (b *Command) IsCommand(name string) bool
- func (c *Command) IsDisabled() bool
- func (c *Command) IsRoot() bool
- func (c *Command) IsStandalone() bool
- func (c *Command) IsSubCommand(name string) bool
- func (c *Command) Match(names []string) *Command
- func (c *Command) MatchByPath(path string) *Command
- func (c *Command) MustRun(args []string)
- func (c *Command) Next()
- func (c *Command) NotStandalone() bool
- func (c *Command) On(name string, handler HookFunc)
- func (c *Command) Parent() *Command
- func (c *Command) ParentName() string
- func (c *Command) Path() string
- func (c *Command) PathNames() []string
- func (c Command) RawOsArgs() []string
- func (b *Command) ResolveAlias(alias string) string
- func (c *Command) Root() *Command
- func (c *Command) Run(args []string) (err error)
- func (c *Command) Runnable() bool
- func (c *Command) SetFunc(fn RunnerFunc)
- func (b *Command) SetLogo(logo string, style ...string)
- func (c *Command) SetParent(parent *Command)
- func (c *Command) ShowHelp()
- func (c *Command) Sub(name string) *Command
- func (c *Command) SubCommand(name string) *Command
- func (c *Command) WithFunc(fn RunnerFunc) *Command
- type Commander
- type EnumString
- type FlagMeta
- type Flags
- func (fs *Flags) Bool(name, shorts string, defValue bool, desc string) *bool
- func (fs *Flags) BoolOpt(p *bool, name, shorts string, defValue bool, desc string)
- func (fs *Flags) BoolVar(p *bool, meta *FlagMeta)
- func (fs *Flags) FSet() *flag.FlagSet
- func (fs *Flags) FSetArgs() []string
- func (fs *Flags) FlagMeta(name string) *FlagMeta
- func (fs *Flags) FlagNames() map[string]int
- func (fs *Flags) Float64Opt(p *float64, name, shorts string, defValue float64, desc string)
- func (fs *Flags) Float64Var(p *float64, meta *FlagMeta)
- func (fs *Flags) FromStruct(s interface{}) error
- func (fs *Flags) HasFlag(name string) bool
- func (fs *Flags) HasFlagMeta(name string) bool
- func (fs *Flags) HasOption(name string) bool
- func (fs *Flags) InitFlagSet(name string)
- func (fs *Flags) Int(name, shorts string, defValue int, desc string) *int
- func (fs *Flags) Int64(name, shorts string, defValue int64, desc string) *int64
- func (fs *Flags) Int64Opt(p *int64, name, shorts string, defValue int64, desc string)
- func (fs *Flags) Int64Var(p *int64, meta *FlagMeta)
- func (fs *Flags) IntOpt(p *int, name, shorts string, defValue int, desc string)
- func (fs *Flags) IntVar(p *int, meta *FlagMeta)
- func (fs *Flags) IsOption(name string) bool
- func (fs *Flags) IsShortName(short string) bool
- func (fs *Flags) IsShortOpt(short string) bool
- func (fs *Flags) IterAll(fn func(f *flag.Flag, meta *FlagMeta))
- func (fs *Flags) Len() int
- func (fs *Flags) LookupFlag(name string) *flag.Flag
- func (fs *Flags) Metas() map[string]*FlagMeta
- func (fs *Flags) Name() string
- func (fs *Flags) Parse(args []string) (err error)
- func (fs *Flags) PrintHelpPanel()
- func (fs *Flags) RawArg(i int) string
- func (fs *Flags) RawArgs() []string
- func (fs *Flags) Required(names ...string)
- func (fs *Flags) Run(args []string)
- func (fs *Flags) SetFlagSet(fSet *flag.FlagSet)
- func (fs *Flags) SetHelpRender(fn func())
- func (fs *Flags) SetOptions(opt *FlagsOption)
- func (fs *Flags) SetOutput(out io.Writer)
- func (fs *Flags) ShortNames(name string) (ss []string)
- func (fs *Flags) Str(name, shorts string, defValue, desc string) *string
- func (fs *Flags) StrOpt(p *string, name, shorts, defValue, desc string)
- func (fs *Flags) StrVar(p *string, meta *FlagMeta)
- func (fs *Flags) String() string
- func (fs *Flags) Uint(name, shorts string, defValue uint, desc string) *uint
- func (fs *Flags) Uint64(name, shorts string, defValue uint64, desc string) *uint64
- func (fs *Flags) Uint64Opt(p *uint64, name, shorts string, defValue uint64, desc string)
- func (fs *Flags) Uint64Var(p *uint64, meta *FlagMeta)
- func (fs *Flags) UintOpt(p *uint, name, shorts string, defValue uint, desc string)
- func (fs *Flags) UintVar(p *uint, meta *FlagMeta)
- func (fs *Flags) Var(p flag.Value, meta *FlagMeta)
- func (fs *Flags) VarOpt(p flag.Value, name, shorts, desc string)
- func (fs *Flags) WithOptions(fns func(opt *FlagsOption)) *Flags
- type FlagsOption
- type GOptions
- type Handler
- type HandlersChain
- type HelpVars
- type HookCtx
- func (md *HookCtx) ClearData()
- func (md *HookCtx) Data() map[string]interface{}
- func (md *HookCtx) IntValue(key string) int
- func (hc *HookCtx) Name() string
- func (md *HookCtx) SetData(data map[string]interface{})
- func (md *HookCtx) SetValue(key string, val interface{})
- func (md *HookCtx) StrValue(key string) string
- func (md *HookCtx) Value(key string) interface{}
- type HookFunc
- type Hooks
- type Ints
- type Logo
- type Runner
- type RunnerFunc
- type SimplePrinter
- func (s SimplePrinter) Errorln(a ...interface{})
- func (s SimplePrinter) Infoln(a ...interface{})
- func (s SimplePrinter) Print(v ...interface{})
- func (s SimplePrinter) Printf(format string, v ...interface{})
- func (s SimplePrinter) Println(v ...interface{})
- func (s SimplePrinter) Warnln(a ...interface{})
- type Strings
- type VerbLevel
Constants ¶
View Source
const ( // OK success exit code OK = 0 // ERR error exit code ERR = 2 // GOON prepare run successful, goon run command GOON = -1 // CommandSep char CommandSep = ":" // HelpCommand name HelpCommand = "help" )
View Source
const ( EvtAppInit = "app.init" EvtAppPrepareAfter = "app.prepare.after" EvtAppRunBefore = "app.run.before" EvtAppRunAfter = "app.run.after" EvtAppRunError = "app.run.error" EvtCmdInit = "cmd.init" // app or sub command not found EvtCmdNotFound = "cmd.not.found" // app command not found EvtAppCmdNotFound = "app.cmd.not.found" // sub command not found EvtCmdSubNotFound = "cmd.sub.not.found" EvtCmdOptParsed = "cmd.opts.parsed" // cmd run EvtCmdRunBefore = "cmd.run.before" EvtCmdRunAfter = "cmd.run.after" EvtCmdRunError = "cmd.run.error" // cmd exec EvtCmdExecBefore = "cmd.exec.before" EvtCmdExecAfter = "cmd.exec.after" EvtCmdExecError = "cmd.exec.error" EvtGOptionsParsed = "gcli.gopts.parsed" )
constants for hooks event, there are default allowed event names
View Source
const ( AlignLeft = strutil.PosRight AlignRight = strutil.PosLeft )
The options alignment type - Align right, padding left - Align left, padding right
View Source
const HelpVarFormat = "{$%s}"
HelpVarFormat allow var replace on render help info. Default support:
"{$binName}" "{$cmd}" "{$fullCmd}" "{$workDir}"
Variables ¶
View Source
var ( // CLI create an default instance CLI = newCmdLine() // DefaultVerb the default verbose level DefaultVerb = VerbError )
View Source
var AppHelpTemplate = `` /* 628-byte string literal not displayed */
AppHelpTemplate help template for app(all commands) TODO {{if .HasSubcommands }} {$binName} [global options...] <info>COMMAND</> [--options ...] <info>SUBCOMMAND</> [--options ...] [arguments ...] {{end}}
View Source
var CmdHelpTemplate = `` /* 1052-byte string literal not displayed */
CmdHelpTemplate help template for a command
View Source
var (
// FlagTagName default tag name on struct
FlagTagName = "flag"
)
Functions ¶
Types ¶
type App ¶
type App struct {
// Name app name
Name string
// Desc app description
Desc string
// Func on run app, if is empty will display help.
Func func(app *App, args []string) error
// ExitOnEnd call os.Exit on running end
ExitOnEnd bool
// ExitFunc default is os.Exit
ExitFunc func(int)
// contains filtered or unexported fields
}
App the cli app definition
func NewApp ¶
NewApp create new app instance. Usage:
NewApp()
// Or with a config func
NewApp(func(a *App) {
// do something before init ....
a.Hooks[gcli.EvtInit] = func () {}
})
func (*App) AddAliases ¶
AddAliases add alias names for a command
func (*App) AddCommand ¶
AddCommand add a new command to the app
func (*App) AliasesMapping ¶
AliasesMapping get cmd aliases mapping
func (*App) Exec ¶
Exec running other command in current command name can be: - top command name in the app. 'top' - command path in the app. 'top sub'
Usage:
app.Exec("top")
app.Exec("top:sub")
app.Exec("top sub")
app.Exec("top sub", []string{"-a", "val0", "arg0"})
func (*App) FindByPath ¶
FindByPath command by path. eg. "top:sub" or "top sub"
func (*App) FindCommand ¶
FindCommand command by path. eg. "top:sub" or "top sub"
func (*App) GetCommand ¶
GetCommand get an command by name
func (*App) MatchByPath ¶
MatchByPath command by path. eg. "top:sub" or "top sub"
func (*App) ResolveAlias ¶
ResolveAlias get real command name by alias
func (*App) Run ¶
Run running application
Usage:
// run with os.Args
app.Run(nil)
app.Run(os.Args[1:])
// custom args
app.Run([]string{"cmd", ...})
func (*App) RunLine ¶
RunLine manual run an command by command line string.
eg: app.RunLine("top --top-opt val0 sub --sub-opt val1 arg0")
func (*App) SetDefaultCommand ¶
SetDefaultCommand set default command name
type Argument ¶
type Argument struct {
// Name argument name. it's required
Name string
// Desc argument description message
Desc string
// Type name. eg: string, int, array
// Type string
// ShowName is a name for display help. default is equals to Name.
ShowName string
// Required arg is required
Required bool
// IsArray if is array, can allow accept multi values, and must in last.
IsArray bool
// valWrapper Value TODO ...
// value store parsed argument data. (type: string, []string)
Value interface{}
// Handler custom argument value handler on call GetValue()
Handler func(val interface{}) interface{}
// Validator you can add an validator, will call it on binding argument value
Validator func(val interface{}) (interface{}, error)
// contains filtered or unexported fields
}
Argument a command argument definition
func NewArgument ¶
NewArgument quick create an new command argument
func (*Argument) GetValue ¶
func (a *Argument) GetValue() interface{}
GetValue get value by custom handler func
func (*Argument) StringSplit ¶
StringSplit quick split a string argument to string slice
func (*Argument) WithValidator ¶
WithValidator set an value validator of the argument
type Arguments ¶
type Arguments struct {
// contains filtered or unexported fields
}
Arguments definition
func (*Arguments) AddArg ¶
AddArg binding an 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 (*Arguments) AddArgument ¶
AddArgument binding an 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
func (*Arguments) Arg ¶
Arg get arg by defined name. Usage:
intVal := ags.Arg("name").Int()
strVal := ags.Arg("name").String()
arrVal := ags.Arg("names").Array()
func (*Arguments) ArgByIndex ¶
ArgByIndex get named arg by index
func (*Arguments) SetValidateNum ¶
SetValidateNum check
type Command ¶
type Command struct {
// Flags options for the command
Flags
// Arguments for the command
Arguments
// Name is the full command name.
Name string
// Desc is the command description message.
Desc string
// Aliases is the command name's alias names
Aliases []string
// Category for the command
Category string
// Config func, will call on `initialize`.
// - you can config options and other init works
Config func(c *Command)
// Subs sub commands of the Command
// NOTICE: if command has been initialized, adding through this field is invalid
Subs []*Command
// module is the name for grouped commands
// subName is the name for grouped commands
// eg: "sys:info" -> module: "sys", subName: "info"
// module, subName string
// Examples some usage example display
Examples string
// Func is the command handler func. Func Runner
Func RunnerFunc
// Help is the long help message text
Help string
// HelpRender custom render cmd help message
HelpRender func(c *Command)
// contains filtered or unexported fields
}
Command a CLI command structure
func NewCommand ¶
NewCommand create a new command instance. Usage:
cmd := NewCommand("my-cmd", "description")
// OR with an config func
cmd := NewCommand("my-cmd", "description", func(c *Command) { ... })
app.Add(cmd) // OR cmd.AttachTo(app)
func (*Command) AddCommand ¶
AddCommand add a sub command
func (*Command) AliasesMapping ¶
AliasesMapping get cmd aliases mapping
func (*Command) AliasesString ¶
AliasesString returns aliases string
func (*Command) CmdAliases ¶
CmdAliases get cmd aliases
func (*Command) CmdNameMap ¶
CmdNameMap get all command names
func (*Command) CommandNames ¶
func (b *Command) CommandNames() []string
CommandNames get all command names
func (*Command) FindByPath ¶
FindByPath command by path. eg. "top:sub" or "top sub"
func (*Command) FindCommand ¶
FindCommand command by path. eg. "top:sub" or "top sub"
func (*Command) GetCommand ¶
GetCommand get an command by name
func (Command) GlobalFlags ¶
func (c Command) GlobalFlags() *Flags
GlobalFlags get the app GlobalFlags
func (*Command) IsSubCommand ¶
IsSubCommand name check. alias of the HasCommand()
func (*Command) MatchByPath ¶
Match command by path. eg. "top:sub"
func (*Command) MustRun ¶
MustRun Alone the current command, will panic on error
Usage:
// run with os.Args
cmd.MustRun(nil)
cmd.MustRun(os.Args[1:])
// custom args
cmd.MustRun([]string{"-a", ...})
func (*Command) ParentName ¶
Module name of the grouped command
func (*Command) ResolveAlias ¶
ResolveAlias get real command name by alias
func (*Command) Run ¶
Run standalone running the command
Usage:
// run with os.Args
cmd.Run(nil)
cmd.Run(os.Args[1:])
// custom args
cmd.Run([]string{"-a", ...})
func (*Command) Runnable ¶
Runnable reports whether the command can be run; otherwise it is a documentation pseudo-command such as import path.
func (*Command) SetFunc ¶
func (c *Command) SetFunc(fn RunnerFunc)
SetFunc Settings command handler func
func (*Command) SubCommand ¶
SubCommand get sub command by name. eg "sub"
func (*Command) WithFunc ¶
func (c *Command) WithFunc(fn RunnerFunc) *Command
WithFunc Settings command handler func
type Commander ¶
type Commander interface {
// Run([]string) int
Value(string) interface{}
SetValue(string, interface{})
}
Commander interface
type EnumString ¶
type EnumString struct {
// contains filtered or unexported fields
}
EnumString The string flag list, implemented flag.Value interface
func (*EnumString) Set ¶
func (s *EnumString) Set(value string) error
Set new value, will check value is right
type FlagMeta ¶
type FlagMeta struct {
// varPtr interface{}
// name and description
Name, Desc string
// Alias of the name. isn't shorts. eg: name='dry-run' alias='dr' TODO
Alias string
// default value for the flag option
DefVal interface{}
// short names. eg: ["o", "a"]
Shorts []string
// advanced settings
Hidden, Required bool
// Validator support validate the option flag value
Validator func(val string) error
// contains filtered or unexported fields
}
FlagMeta for an flag(option/argument)
func (*FlagMeta) Shorts2String ¶
Shorts2String join shorts to an string
type Flags ¶
type Flags struct {
// Desc message
Desc string
// ExitFunc for handle exit
ExitFunc func(code int)
// contains filtered or unexported fields
}
Flags struct definition
func (*Flags) FSetArgs ¶
FSetArgs get all raw arguments. alias of the RawArgs() if have been called parse, the return is remaining args.
func (*Flags) Float64Opt ¶
Float64Opt binding an float64 option
func (*Flags) Float64Var ¶
Float64Var binding an float64 option flag
func (*Flags) FromStruct ¶
FromStruct from struct tag binding options
func (*Flags) HasFlagMeta ¶
HasFlagMeta check it is has FlagMeta
func (*Flags) IsShortName ¶
IsShortcut check it is a shortcut name
func (*Flags) IsShortOpt ¶
IsShortOpt alias of the IsShortcut()
func (*Flags) LookupFlag ¶
LookupFlag get flag.Flag by name
func (*Flags) Parse ¶
Parse given arguments
Usage:
gf := gcli.NewFlags() gf.BoolOpt(&debug, "debug", "", defDebug, "open debug mode") gf.UintOpt(&port, "port", "p", 18081, "the http server port") err := gf.Parse(os.Args[1:])
func (*Flags) PrintHelpPanel ¶
func (fs *Flags) PrintHelpPanel()
PrintHelpPanel for all options to the gf.out
func (*Flags) RawArgs ¶
RawArgs get all raw arguments. if have been called parse, the return is remaining args.
func (*Flags) Run ¶
Run flags parse and handle help render Usage:
gf := gcli.NewFlags() ... gf.Run(os.Args)
func (*Flags) SetFlagSet ¶
SetFlagSet set the raw *flag.FlagSet
func (*Flags) SetHelpRender ¶
func (fs *Flags) SetHelpRender(fn func())
SetHelpRender set the raw *flag.FlagSet.Usage
func (*Flags) ShortNames ¶
ShortNames get all short-names of the option
func (*Flags) VarOpt ¶
VarOpt binding a custom var option Usage:
var names gcli.Strings cmd.VarOpt(&names, "tables", "t", "description ...")
func (*Flags) WithOptions ¶
func (fs *Flags) WithOptions(fns func(opt *FlagsOption)) *Flags
WithOptions for the object.
type FlagsOption ¶
type FlagsOption struct {
// WithoutType dont display flag data type on print help
WithoutType bool
// NameDescOL flag and desc at one line on print help
NameDescOL bool
// Alignment flag name align left or right. default is: right
Alignment uint8
// TagName on struct
TagName string
}
FlagsOption for render help information
type GOptions ¶
type GOptions struct {
NoColor bool
// contains filtered or unexported fields
}
GOptions global flag options
func (*GOptions) SetStrictMode ¶
SetStrictMode option
type Handler ¶
type Handler interface {
// Creator for create new command
Creator() *Command
// Config bind Flags or Arguments for the command
Config(c *Command)
// Execute the command
Execute(c *Command, args []string) error
}
Handler interface definition
type HandlersChain ¶
type HandlersChain []RunnerFunc
HandlersChain middleware handlers chain definition
func (HandlersChain) Last ¶
func (c HandlersChain) Last() RunnerFunc
Last returns the last handler in the chain. ie. the last handler is the main own.
type HelpVars ¶
type HelpVars struct {
// varLeft, varRight string
// varFormat string
// Vars you can add some vars map for render help info
Vars map[string]string
}
HelpVars struct. provide string var function for render help template.
func (*HelpVars) ReplaceVars ¶
ReplaceVars replace vars in the input string.
type HookCtx ¶
HookCtx struct
func (*HookCtx) SetData ¶
func (md *HookCtx) SetData(data map[string]interface{})
SetData set all data
type HookFunc ¶
type HookFunc func(data ...interface{}) (stop bool)
HookFunc definition. func arguments:
in app, like: func(app *App, data ...interface{})
in cmd, like: func(cmd *Command, data ...interface{})
type HookFunc func(obj interface{}, data interface{}) return: - True go on handle. default is True - False stop goon handle.
type Hooks ¶
type Hooks struct {
// contains filtered or unexported fields
}
Hooks struct
type RunnerFunc ¶
RunnerFunc definition
type SimplePrinter ¶
type SimplePrinter struct{}
SimplePrinter struct. for inject struct
func (SimplePrinter) Printf ¶
func (s SimplePrinter) Printf(format string, v ...interface{})
Printf message
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cliapp
command
|
|
|
ggit
command
|
|
|
multilevel
command
|
|
|
serveman
command
|
|
|
simpleone
command
|
|
|
sflag
Package sflag is an simple cli flag parse tool
|
Package sflag is an simple cli flag parse tool |
|
Package interact collect some interactive methods for CLI
|
Package interact collect some interactive methods for CLI |
|
Package progress provide terminal progress bar display.
|
Package progress provide terminal progress bar display. |
|
Package show provides some formatter tools for display data.
|
Package show provides some formatter tools for display data. |
Click to show internal directories.
Click to hide internal directories.