argparse

Documentation

Overview

Argparse is a Go module that makes it easy to write the command-line parsing part of your program. It loosely follows the conceptual model of the Python argparse module.

Highlights:

• You can have nested subcommands.
• The values for the command-line options are stored in a struct of your creation.
• Argparse can deduce the name of the value field in the struct by looking at the name of the option. Or, you can tell it exactly which field to use.
• Argparse will tell you if a particular option was present on the command-line or not present, in case you need that information.
• Options can be inherited by sub-comands, so you need only define them once.
• The built-in help strings are translatable.

Index

• Constants
• Variables
• type Argument
  • func (self *Argument) PrettyName() string
• type ArgumentParser
  • func New(cmd *Command) *ArgumentParser
  • func (self *ArgumentParser) Add(arg *Argument)
  • func (self *ArgumentParser) New(c *Command) *Command
  • func (self *ArgumentParser) Parse()
  • func (self *ArgumentParser) ParseAndExit()
• type Command
  • func (self *Command) Add(arg *Argument)
  • func (self *Command) New(cmd *Command) *Command
• type Messages
• type ParserCallback
• type Values

Constants

const (
	Scalar valueStorageType = iota
	Slice
)

Variables

var DefaultMessages_en = Messages{
	SubCommands:     "Sub-Commands",
	Options:         "Options",
	HelpDescription: "See this list of options",

	CannotParseBooleanFmt:   "Cannot convert \"%s\" to a boolean",
	ChoicesOfWrongTypeFmt:   "Choices should be []%s",
	ShouldBeAValidChoiceFmt: "Not a valid choice. Should be one of: %v",
}

Types

type Argument

type Argument struct {
	// Any number of switch patterns, each starting with at lease one hypen
	Switches []string

	// The name of the positional argument. No starting hyphens.
	Name string

	// The help string to display to the user
	Help string

	// The name of the value field to show in the usage statement,
	// for non-boolean switches
	MetaVar string

	// The name of the destination field for the value of the switch
	// or positional argument, if it is named differently from any of the
	// Switches, or Name.
	Dest string

	// Number of arguments that can or should appear
	// If NumArgs is 0 (never initialized), and NumArgsGlob is "",
	// the value of NumArgs is set to 1, unless this is a Bool, in which case
	// it's set to 0.
	// If NumArgs is not 0 or 1, then NumArgsGlob must be "", in which case
	// the number of args is exactly NumArgs.
	// If NumArgs is 0, and NumArgsGlob is not "", then it must be one
	// of "+" ("one or more"), "?" ("zero or one"), or "*" ("zero or more"),
	// and then NumArgs is set to -1
	NumArgs     int
	NumArgsGlob string

	// Will a sub-command inherit this argument definition if one is not
	// defined for that sub-command, *and* if the Value struct for that
	// Command has a suitable field?
	Inherit bool

	// For non-boolean options, the valid values that the user can provide.
	// If Choices is given, and the user provides a value not in this list,
	// the user will be presented with an error.
	Choices interface{}
	// contains filtered or unexported fields
}

func (*Argument) PrettyName

func (self *Argument) PrettyName() string

type ArgumentParser

type ArgumentParser struct {
	// If this is set, instead of printing the help statement,
	// when --help is requested, to os.Stdout, the output goes here.
	Stdout io.Writer

	// If this is set, instead of printing the usage statement,
	// when a ParseErr is encountered, to os.Stderr, the output goes here.
	Stderr io.Writer

	// Allow the user to modify strings produced by argparse.
	// This is essential for i18n
	Messages Messages

	// The switch strings that can invoke help
	HelpSwitches []string

	// The root Command object.
	Root *Command
	// contains filtered or unexported fields
}

func New

func New(cmd *Command) *ArgumentParser

Create a new ArgumentParser, with the Command as its root Command

func (*ArgumentParser) Add

func (self *ArgumentParser) Add(arg *Argument)

Add an argument to the root command

func (*ArgumentParser) New

func (self *ArgumentParser) New(c *Command) *Command

Add a command to the root command

func (*ArgumentParser) Parse

func (self *ArgumentParser) Parse()

Parse the os.Argv arguments and return, having filled out Values. On a request for help (-h), print the help and exit with os.Exit(0). On a user input error, print the error message and exit with os.Exit(1).

func (*ArgumentParser) ParseAndExit

func (self *ArgumentParser) ParseAndExit()

Parse the os.Argv arguments, call the Function for the triggered Command, and then exit. An error returned from the Function causes us to exit with 1, otherwise, exit with 0. On a request for help (-h), print the help and exit with os.Exit(0). On a user input error, print the error message and exit with os.Exit(1).

type Command

type Command struct {
	// The name of the program or subcommand
	Name string

	// This can be a multi-line string that is shown
	// after after the command name, and before the options.
	Description string

	// This can be a multi-line string that is shown
	// after all the options in the --help output
	Epilog string

	// The struct that will receive the values after parsing
	Values Values

	// The function to call when this parser is selected
	Function ParserCallback

	// Was an option seen during the parse? The key is the name
	// of the destination variable.
	Seen map[string]bool

	// Was a sub-command seen during the parse?
	CommandSeen map[string]bool
	// contains filtered or unexported fields
}

func (*Command) Add

func (self *Command) Add(arg *Argument)

TODO - check that it's not a HelpSwitch; Command will need to know HelpSwitches

func (*Command) New

func (self *Command) New(cmd *Command) *Command

type Messages

type Messages struct {
	// "Sub-Commands"
	SubCommands string

	// "Options'
	Options string

	// The description for the help options (-h / --help):
	// "See this list of options"
	HelpDescription string

	// Error when parsing a boolean
	// "Cannot convert \"%s\" to a boolean"
	CannotParseBooleanFmt string

	// The Choices slice is of the wrong type.
	// "Choices should be []%s"
	ChoicesOfWrongTypeFmt string

	// The given value is not a valid choice
	// "Not a valid choice. Should be one of: %v"
	// TODO This should be changed to have %s and %v, to show the incorrect value
	ShouldBeAValidChoiceFmt string
}

Strings that can be printed out to the user. They can be overridden for i18n

type ParserCallback

type ParserCallback func(*Command, Values) error

type Values

type Values interface{}