argparse: github.com/akamensky/argparse Index | Examples | Files | Directories

package argparse

import "github.com/akamensky/argparse"

Package argparse provides users with more flexible and configurable option for command line arguments parsing.

Index

Examples

Package Files

argparse.go argument.go command.go errors.go extras.go

Constants

const DisableDescription = "DISABLEDDESCRIPTIONWILLNOTSHOWUP"

DisableDescription can be assigned as a command or arguments description to hide it from the Usage output

type Arg Uses

type Arg interface {
    GetOpts() *Options
    GetSname() string
    GetLname() string
}

Arg interface provides exporting of arg structure, while exposing it

type Command Uses

type Command struct {
    HelpFunc func(c *Command, msg interface{}) string
    // contains filtered or unexported fields
}

Command is a basic type for this package. It represents top level Parser as well as any commands and sub-commands Command MUST NOT ever be created manually. Instead one should call NewCommand method of Parser or Command, which will setup appropriate fields and call methods that have to be called when creating new command.

func (*Command) ExitOnHelp Uses

func (o *Command) ExitOnHelp(b bool)

ExitOnHelp sets the exitOnHelp variable of Parser

func (*Command) File Uses

func (o *Command) File(short string, long string, flag int, perm os.FileMode, opts *Options) *os.File

File creates new file argument, which is when provided will check if file exists or attempt to create it depending on provided flags (same as for os.OpenFile). It takes same as all other arguments short and long names, additionally it takes flags that specify in which mode the file should be open (see os.OpenFile for details on that), file permissions that will be applied to a file and argument options. Returns a pointer to os.File which will be set to opened file on success. On error the Parser.Parse will return error and the pointer might be nil.

func (*Command) FileList Uses

func (o *Command) FileList(short string, long string, flag int, perm os.FileMode, opts *Options) *[]os.File

FileList creates new file list argument. This is the argument that is allowed to be present multiple times on CLI. All appearances of this argument on CLI will be collected into the list of os.File values. If no argument provided, then the list is empty. Takes same parameters as File Returns a pointer the list of os.File values.

func (*Command) Flag Uses

func (o *Command) Flag(short string, long string, opts *Options) *bool

Flag Creates new flag type of argument, which is boolean value showing if argument was provided or not. Takes short name, long name and pointer to options (optional). Short name must be single character, but can be omitted by giving empty string. Long name is required. Returns pointer to boolean with starting value `false`. If Parser finds the flag provided on Command line arguments, then the value is changed to true. Set of Flag and FlagCounter shorthand arguments can be combined together such as `tar -cvaf foo.tar foo`

func (*Command) FlagCounter Uses

func (o *Command) FlagCounter(short string, long string, opts *Options) *int

FlagCounter Creates new flagCounter type of argument, which is integer value showing the number of times the argument has been provided. Takes short name, long name and pointer to options (optional). Short name must be single character, but can be omitted by giving empty string. Long name is required. Returns pointer to integer with starting value `0`. Each time Parser finds the flag provided on Command line arguments, the value is incremented by 1. Set of FlagCounter and Flag shorthand arguments can be combined together such as `tar -cvaf foo.tar foo`

func (*Command) Float Uses

func (o *Command) Float(short string, long string, opts *Options) *float64

Float creates new float argument, which will attempt to parse following argument as float64. Takes as arguments short name (must be single character or an empty string) long name and (optional) options. If parsing fails parser.Parse() will return an error.

func (*Command) FloatList Uses

func (o *Command) FloatList(short string, long string, opts *Options) *[]float64

FloatList creates new float list argument. This is the argument that is allowed to be present multiple times on CLI. All appearances of this argument on CLI will be collected into the list of float64 values. If no argument provided, then the list is empty. Takes same parameters as Float Returns a pointer the list of float64 values.

func (Command) GetArgs Uses

func (o Command) GetArgs() (args []Arg)

GetArgs exposes Command's args field

func (Command) GetCommands Uses

func (o Command) GetCommands() []*Command

GetCommands exposes Command's commands field

func (Command) GetDescription Uses

func (o Command) GetDescription() string

GetDescription exposes Command's description field

func (Command) GetName Uses

func (o Command) GetName() string

GetName exposes Command's name field

func (Command) GetParent Uses

func (o Command) GetParent() *Command

GetParent exposes Command's parent field

func (*Command) Happened Uses

func (o *Command) Happened() bool

Happened shows whether Command was specified on CLI arguments or not. If Command did not "happen", then all its descendant commands and arguments are not parsed. Returns a boolean value.

func (*Command) Help Uses

func (o *Command) Help(msg interface{}) string

Help calls the overriddable Command.HelpFunc on itself, called when the help argument strings are passed via CLI

Code:

parser := NewParser("parser", "")
parser.HelpFunc = func(c *Command, msg interface{}) string {
    return fmt.Sprintf("Name: %s\n", c.GetName())
}
fmt.Println(parser.Help(nil))

Output:

Name: parser

Code:

parser := NewParser("parser", "")
parser.HelpFunc = func(c *Command, msg interface{}) string {
    helpString := fmt.Sprintf("Name: %s\n", c.GetName())
    for _, com := range c.GetCommands() {
        // Calls parser.HelpFunc, because command.HelpFuncs are nil
        helpString += com.Help(nil)
    }
    return helpString
}
parser.NewCommand("subcommand1", "")
parser.NewCommand("subcommand2", "")
fmt.Println(parser.Help(nil))

Output:

Name: parser
Name: subcommand1
Name: subcommand2

Code:

parser := NewParser("parser", "")
parser.HelpFunc = func(c *Command, msg interface{}) string {
    helpString := fmt.Sprintf("Name: %s\n", c.GetName())
    for _, com := range c.GetCommands() {
        // Calls command.HelpFunc, because command.HelpFuncs are not nil
        helpString += com.Help(nil)
    }
    return helpString
}
com1 := parser.NewCommand("subcommand1", "Test description")
com1.HelpFunc = func(c *Command, msg interface{}) string {
    helpString := fmt.Sprintf("Name: %s, Description: %s\n", c.GetName(), c.GetDescription())
    return helpString
}
com2 := parser.NewCommand("subcommand2", "")
com2.String("s", "string", &Options{Required: false})
com2.String("i", "integer", &Options{Required: true})
com2.HelpFunc = func(c *Command, msg interface{}) string {
    helpString := fmt.Sprintf("Name: %s\n", c.GetName())
    for _, arg := range c.GetArgs() {
        helpString += fmt.Sprintf("\tLname: %s, Required: %t\n", arg.GetLname(), arg.GetOpts().Required)
    }
    return helpString
}
fmt.Print(parser.Help(nil))
fmt.Print(com1.Help(nil))
fmt.Print(com2.Help(nil))

Output:

Name: parser
Name: subcommand1, Description: Test description
Name: subcommand2
	Lname: string, Required: false
	Lname: integer, Required: true
Name: subcommand1, Description: Test description
Name: subcommand2
	Lname: string, Required: false
	Lname: integer, Required: true

func (*Command) Int Uses

func (o *Command) Int(short string, long string, opts *Options) *int

Int creates new int argument, which will attempt to parse following argument as int. Takes as arguments short name (must be single character or an empty string) long name and (optional) options. If parsing fails parser.Parse() will return an error.

func (*Command) IntList Uses

func (o *Command) IntList(short string, long string, opts *Options) *[]int

IntList creates new integer list argument. This is the argument that is allowed to be present multiple times on CLI. All appearances of this argument on CLI will be collected into the list of integers. If no argument provided, then the list is empty. Takes same parameters as Int Returns a pointer the list of integers.

func (*Command) List Uses

func (o *Command) List(short string, long string, opts *Options) *[]string

List creates new list argument. This is the argument that is allowed to be present multiple times on CLI. All appearances of this argument on CLI will be collected into the list of default type values ​​which is strings. If no argument provided, then the list is empty. Takes same parameters as String Returns a pointer the list of strings.

func (*Command) NewCommand Uses

func (o *Command) NewCommand(name string, description string) *Command

NewCommand will create a sub-command and propagate all necessary fields. All commands are always at the beginning of the arguments. Parser can have commands and those commands can have sub-commands, which allows for very flexible workflow. All commands are considered as required and all commands can have their own argument set. Commands are processed Parser -> Command -> sub-Command. Arguments will be processed in order of sub-Command -> Command -> Parser.

func (*Command) Selector Uses

func (o *Command) Selector(short string, long string, options []string, opts *Options) *string

Selector creates a selector argument. Selector argument works in the same way as String argument, with the difference that the string value must be from the list of options provided by the program. Takes short and long names, argument options and a slice of strings which are allowed values for CLI argument. Returns a pointer to a string. If argument is not required (as in argparse.Options.Required), and argument was not provided, then the string is empty.

func (*Command) String Uses

func (o *Command) String(short string, long string, opts *Options) *string

String creates new string argument, which will return whatever follows the argument on CLI. Takes as arguments short name (must be single character or an empty string) long name and (optional) options

func (*Command) StringList Uses

func (o *Command) StringList(short string, long string, opts *Options) *[]string

StringList creates new string list argument. This is the argument that is allowed to be present multiple times on CLI. All appearances of this argument on CLI will be collected into the list of strings. If no argument provided, then the list is empty. Takes same parameters as String Returns a pointer the list of strings.

func (*Command) Usage Uses

func (o *Command) Usage(msg interface{}) string

Usage returns a multiline string that is the same as a help message for this Parser or Command. Since Parser is a Command as well, they work in exactly same way. Meaning that usage string can be retrieved for any level of commands. It will only include information about this Command, its sub-commands, current Command arguments and arguments of all preceding commands (if any)

Accepts an interface that can be error, string or fmt.Stringer that will be prepended to a message. All other interface types will be ignored

type Options Uses

type Options struct {
    Required bool
    Validate func(args []string) error
    Help     string
    Default  interface{}
}

Options are specific options for every argument. They can be provided if necessary. Possible fields are:

Options.Required - tells Parser that this argument is required to be provided. useful when specific Command requires some data provided.

Options.Validate - is a validation function. Using this field anyone can implement a custom validation for argument. If provided and argument is present, then function is called. If argument also consumes any following values (e.g. as String does), then these are provided as args to function. If validation fails the error must be returned, which will be the output of `Parser.Parse` method.

Options.Help - A help message to be displayed in Usage output. Can be of any length as the message will be formatted to fit max screen width of 100 characters.

Options.Default - A default value for an argument. This value will be assigned to the argument at the end of parsing in case if this argument was not supplied on command line. File default value is a string which it will be open with provided options. In case if provided value type does not match expected, the error will be returned on run-time.

type Parser Uses

type Parser struct {
    Command
}

Parser is a top level object of argparse. It MUST NOT ever be created manually. Instead one should use argparse.NewParser() method that will create new parser, propagate necessary private fields and call needed functions.

func NewParser Uses

func NewParser(name string, description string) *Parser

NewParser creates new Parser object that will allow to add arguments for parsing It takes program name and description which will be used as part of Usage output Returns pointer to Parser object

func (*Parser) DisableHelp Uses

func (o *Parser) DisableHelp()

DisableHelp removes any help arguments from the commands list of arguments This prevents prevents help from being parsed or invoked from the argument list

func (*Parser) Parse Uses

func (o *Parser) Parse(args []string) error

Parse method can be applied only on Parser. It takes a slice of strings (as in os.Args) and it will process this slice as arguments of CLI (the original slice is not modified). Returns error on any failure. In case of failure recommended course of action is to print received error alongside with usage information (might want to check which Command was active when error happened and print that specific Command usage). In case no error returned all arguments should be safe to use. Safety of using arguments before Parse operation is complete is not guaranteed.

func (*Parser) SetHelp Uses

func (o *Parser) SetHelp(sname, lname string)

SetHelp removes the previous help argument, and creates a new one with the desired sname/lname

Directories

PathSynopsis
examples/command-help
examples/commands
examples/commands-advanced
examples/commands-advanced/zoo
examples/default
examples/flags
examples/help
examples/help-argument-names
examples/help-no-exit
examples/no-help
examples/print
examples/required-args
examples/sleep

Package argparse imports 6 packages (graph) and is imported by 24 packages. Updated 2020-03-03. Refresh now. Tools for package owners.