gcmd

Documentation

Overview

Package gcmd provides console operations, like options/arguments reading and command running.

Index

• Constants
• func BuildOptions(m map[string]string, prefix ...string) string
• func ContainsOpt(name string) bool
• func GetArg(index int, def ...string) *gvar.Var
• func GetArgAll() []string
• func GetOpt(name string, def ...string) *gvar.Var
• func GetOptAll() map[string]string
• func GetOptWithEnv(key string, def ...interface{}) *gvar.Var
• func Init(args ...string)
• func Scan(info ...interface{}) string
• func Scanf(format string, info ...interface{}) string
• type Command
  • func NewFromObject(object interface{}) (rootCmd Command, err error)
  • func (c *Command) AddCommand(commands ...Command) error
  • func (c *Command) AddObject(objects ...interface{}) error
  • func (c *Command) Print()
  • func (c *Command) Run(ctx context.Context) error
  • func (c *Command) RunWithValue(ctx context.Context) (value interface{}, err error)
• type FuncWithValue
• type Function
• type Option
• type Parser
  • func Parse(supportedOptions map[string]bool, strict ...bool) (*Parser, error)
  • func ParseWithArgs(args []string, supportedOptions map[string]bool, strict ...bool) (*Parser, error)
  • func ParserFromCtx(ctx context.Context) *Parser
  • func (p *Parser) AutoRun() error
  • func (p *Parser) BindHandle(cmd string, f func()) error
  • func (p *Parser) BindHandleMap(m map[string]func()) error
  • func (p *Parser) ContainsOpt(name string) bool
  • func (p *Parser) GetArg(index int, def ...string) *gvar.Var
  • func (p *Parser) GetArgAll() []string
  • func (p *Parser) GetOpt(name string, def ...interface{}) *gvar.Var
  • func (p *Parser) GetOptAll() map[string]string
  • func (p *Parser) MarshalJSON() ([]byte, error)
  • func (p *Parser) RunHandle(cmd string) error

Constants

const (
	CtxKeyParser gctx.StrKey = `GoFrameCommandParser`
)

Functions

func BuildOptions

func BuildOptions(m map[string]string, prefix ...string) string

BuildOptions builds the options as string.

func ContainsOpt

func ContainsOpt(name string) bool

ContainsOpt checks whether option named `name` exist in the arguments.

func GetArg

func GetArg(index int, def ...string) *gvar.Var

GetArg returns the argument at `index` as gvar.Var.

func GetArgAll

func GetArgAll() []string

GetArgAll returns all parsed arguments.

func GetOpt

func GetOpt(name string, def ...string) *gvar.Var

GetOpt returns the option value named `name` as gvar.Var.

func GetOptAll

func GetOptAll() map[string]string

GetOptAll returns all parsed options.

func GetOptWithEnv

func GetOptWithEnv(key string, def ...interface{}) *gvar.Var

GetOptWithEnv returns the command line argument of the specified `key`. If the argument does not exist, then it returns the environment variable with specified `key`. It returns the default value `def` if none of them exists.

Fetching Rules: 1. Command line arguments are in lowercase format, eg: gf.`package name`.<variable name>; 2. Environment arguments are in uppercase format, eg: GF_`package name`_<variable name>；

func Init

func Init(args ...string)

Init does custom initialization.

func Scan

func Scan(info ...interface{}) string

Scan prints `info` to stdout, reads and returns user input, which stops by '\n'.

func Scanf

func Scanf(format string, info ...interface{}) string

Scanf prints `info` to stdout with `format`, reads and returns user input, which stops by '\n'.

Types

type Command

type Command struct {
	Name          string        // Command name(case-sensitive).
	Usage         string        // A brief line description about its usage, eg: gf build main.go [OPTION]
	Brief         string        // A brief info that describes what this command will do.
	Description   string        // A detailed description.
	Options       []Option      // Option array, configuring how this command act.
	Func          Function      // Custom function.
	FuncWithValue FuncWithValue // Custom function with output parameters that can interact with command caller.
	HelpFunc      Function      // Custom help function
	Examples      string        // Usage examples.
	Additional    string        // Additional info about this command, which will be appended to the end of help info.
	Strict        bool          // Strict parsing options, which means it returns error if invalid option given.
	// contains filtered or unexported fields
}

Command holds the info about an argument that can handle custom logic.

func NewFromObject

func NewFromObject(object interface{}) (rootCmd Command, err error)

NewFromObject creates and returns a root command object using given object.

func (*Command) AddCommand

func (c *Command) AddCommand(commands ...Command) error

AddCommand adds one or more sub-commands to current command.

func (*Command) AddObject

func (c *Command) AddObject(objects ...interface{}) error

AddObject adds one or more sub-commands to current command using struct object.

func (*Command) Print

func (c *Command) Print()

Print prints help info to stdout for current command.

func (*Command) Run

func (c *Command) Run(ctx context.Context) error

Run calls custom function that bound to this command.

func (*Command) RunWithValue

func (c *Command) RunWithValue(ctx context.Context) (value interface{}, err error)

RunWithValue calls custom function that bound to this command with value output.

type FuncWithValue

type FuncWithValue func(ctx context.Context, parser *Parser) (out interface{}, err error)

FuncWithValue is similar like Func but with output parameters that can interact with command caller.

type Function

type Function func(ctx context.Context, parser *Parser) (err error)

Function is a custom command callback function that is bound to a certain argument.

type Option

type Option struct {
	Name   string // Option name.
	Short  string // Option short.
	Brief  string // Brief info about this Option, which is used in help info.
	Orphan bool   // Whether this Option having or having no value bound to it.
}

Option is the command value that is specified by a name or shor name. An Option can have or have no value bound to it.

type Parser

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

Parser for arguments.

func Parse

func Parse(supportedOptions map[string]bool, strict ...bool) (*Parser, error)

Parse creates and returns a new Parser with os.Args and supported options.

Note that the parameter `supportedOptions` is as [option name: need argument], which means the value item of `supportedOptions` indicates whether corresponding option name needs argument or not.

The optional parameter `strict` specifies whether stops parsing and returns error if invalid option passed.

func ParseWithArgs

func ParseWithArgs(args []string, supportedOptions map[string]bool, strict ...bool) (*Parser, error)

ParseWithArgs creates and returns a new Parser with given arguments and supported options.

Note that the parameter `supportedOptions` is as [option name: need argument], which means the value item of `supportedOptions` indicates whether corresponding option name needs argument or not.

The optional parameter `strict` specifies whether stops parsing and returns error if invalid option passed.

func ParserFromCtx

func ParserFromCtx(ctx context.Context) *Parser

ParserFromCtx retrieves and returns Parser from context.

func (*Parser) AutoRun

func (p *Parser) AutoRun() error

AutoRun automatically recognizes and executes the callback function by value of index 0 (the first console parameter).

func (*Parser) BindHandle

func (p *Parser) BindHandle(cmd string, f func()) error

BindHandle registers callback function `f` with `cmd`.

func (*Parser) BindHandleMap

func (p *Parser) BindHandleMap(m map[string]func()) error

BindHandleMap registers callback function with map `m`.

func (*Parser) ContainsOpt

func (p *Parser) ContainsOpt(name string) bool

ContainsOpt checks whether option named `name` exist in the arguments.

func (*Parser) GetArg

func (p *Parser) GetArg(index int, def ...string) *gvar.Var

GetArg returns the argument at `index` as gvar.Var.

func (*Parser) GetArgAll

func (p *Parser) GetArgAll() []string

GetArgAll returns all parsed arguments.

func (*Parser) GetOpt

func (p *Parser) GetOpt(name string, def ...interface{}) *gvar.Var

GetOpt returns the option value named `name` as gvar.Var.

func (*Parser) GetOptAll

func (p *Parser) GetOptAll() map[string]string

GetOptAll returns all parsed options.

func (*Parser) MarshalJSON

func (p *Parser) MarshalJSON() ([]byte, error)

MarshalJSON implements the interface MarshalJSON for json.Marshal.

func (*Parser) RunHandle

func (p *Parser) RunHandle(cmd string) error

RunHandle executes the callback function registered by `cmd`.