README
¶
go-subcommand
Option parser for go programs a la git/mercurial/go loosely inspired by Ruby's OptionParser.
It allows to build CLIs easily supporting syntax similar to:
program --prog_option1 opt1 --prog_switch1 subcommand --subcommand_opt1 opt1 --subcommand_switch more_arguments
Documentation
¶
Overview ¶
Package subcommand is an option parsing utility a la git/mercurial/go loosely inspired by Ruby's OptionParser
Index ¶
- Constants
- type Arity
- type Command
- func (c *Command) AddOption(long, short, shortDesc, longDesc, values string, fn FlagFunction) *Flag
- func (c *Command) AddSwitch(long string, short string, shortDesc string, fn FlagFunction) *Flag
- func (c Command) Arity() Arity
- func (c *Command) Flags() []Flag
- func (c *Command) MandatoryFlags() []Flag
- func (c *Command) NonMandatoryFlags() []Flag
- func (c Command) Parent() *Command
- func (c *Command) SetArity(arity int, description string) *Command
- type CommandFunction
- type Flag
- type FlagFunction
- type FlagType
- type Flagged
- type Parser
- func (p *Parser) AddCommand(name string, shortDesc string, longDesc string, fn CommandFunction) *Command
- func (p *Parser) OnCommand(fn CommandFunction)
- func (p *Parser) Parse(args []string) (leftOvers []string, err error)
- func (p *Parser) PostFlags(fn func() error)
- func (p *Parser) SetHelp(name string, description string, fn CommandFunction) *Command
- type ParsingError
Constants ¶
const ( PARSER_HELP_TEMPLATE = `` /* 361-byte string literal not displayed */ COMMAND_HELP_TEMPLATE = `` /* 244-byte string literal not displayed */ )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Command ¶
type Command struct {
//Name
Name string
ShortDesc string //Command help line
LongDesc string
// contains filtered or unexported fields
}
Command aggregates different flags under a common name. Every time a command is found during the parsing process the associated function is executed.
func (*Command) AddOption ¶
func (c *Command) AddOption(long, short, shortDesc, longDesc, values string, fn FlagFunction) *Flag
Adds a new option to the command to be used as "--option OPTION" (expects a value after the flag) in the command line The short definition has no length restriction but it should be significantly shorter that its long counterpart, it can be an empty string. The function fn receives the name of the option and its value Example: command.AddOption("path","p",setPath)//option [...]
func setPath(option,value string){
printf("According the option %v the path is set to %v",option,value);
}
func (*Command) AddSwitch ¶
Adds a new switch to the command to be used as "--switch" (expects no value after the flag) in the command line The short definition has no length restriction but it should be significantly shorter that its long counterpart, it can be an empty string. The function fn receives two strings, the first is the switch name and the second is just an empty string Example: command.AddSwitch("verbose","v",setVerbose)//option [...]
func setVerbose(switch string){
printf("I'm get to get quite talkative! I'm set to be %v ",switch);
}
func (*Command) MandatoryFlags ¶
func (*Command) NonMandatoryFlags ¶
type CommandFunction ¶
Convinience type for funcions passed to commands
type Flag ¶
type Flag struct {
//long definition (--option OPTION)
Long string
//Short definition (-o )
Short string
//Short description
ShortDesc string
//Long description
LongDesc string
//Possible values
Values string
//FlagType, option or switch
Type FlagType
//Says if the flag is optional or mandatory
Mandatory bool
// contains filtered or unexported fields
}
Flag structure
func (Flag) FlagStringPrefix ¶
type FlagFunction ¶
Convinience type for funcions passed flags
type FlagType ¶
type FlagType int
FlagType defines the different flag types. Options have values associated to the flag, Switches have no value associated.
type Parser ¶
type Parser struct {
Command
Commands map[string]*Command
// contains filtered or unexported fields
}
Parser contains other commands. It's the data structure and its name should be the program's name.
func (*Parser) AddCommand ¶
func (p *Parser) AddCommand(name string, shortDesc string, longDesc string, fn CommandFunction) *Command
AddCommand inserts a new subcommand to the parser. The callback fn receives as first argument the command name followed by the left overs of the parsing process Example: command "hello" prints the non flags (options and switches) arguments. The associated callback should be something like
func processCommand(commandName string,args ...string){
fmt.Printf("The command %v says:\n",commandName)
for _,arg:= rage args{
fmt.Printf("%v \n",arg)
}
}
func (*Parser) OnCommand ¶
func (p *Parser) OnCommand(fn CommandFunction)
First level execution when parsing. The passed function is exectued taking the leftovers until the first command ./prog -switch left1 left2 command in this case name will be prog, and left overs left1 and left2
func (*Parser) Parse ¶
Parse parses the arguments executing the associated functions for each command and flag. It returns the left overs if some non-option strings or commands were not processed. Errors are returned in case an unknown flag is found or a mandatory flag was not supplied. The set of function calls to be performed are carried in order and once the parsing process is done
type ParsingError ¶
func (ParsingError) Error ¶
func (e ParsingError) Error() string
Source Files