structarg

package module
v0.0.0-...-7c3bbf8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2018 License: Apache-2.0 Imports: 10 Imported by: 0

README

structarg

Argument parser for go that defines and parses command line arguements into a struct type variable. The attributes of arguments are defined in the comment tags of the struct. after parsing command-line argument or configuration files, the values are stored in this struct.

please refer to examples/example.go for example usages.

An example of a struct definition is shown as follows:

type Options struct {
    Help bool       `help:"Show help messages" short-token:"h"`
    Debug bool      `help:"Show extra debug information"`
    Timeout int     `default:"600" help: "Number of seconds to wait for a response"`
    SUBCOMMAND string `help:"subcommand" subcommand:"true"`
}

Argument name

Each member variable of the struct represents an argument. The variable name is the argument name.

Positional and optional arguments

If the variable name is all uppercased, the argument is a positional argument, otherwise, it is an optional argument. Additionally, boolean tag "optional" explicitly defines whether the argument is optional or positional.

Tags

The attributes of an argument are defined in the comment tags of the member variable of the struct. The following tags are supported:

	/*
	   help text of the argument
	   the argument is optional.
	*/
	TAG_HELP = "help"
	/*
	   command-line token for the optional argument, e.g. token:"url"
	   the command-line argument will be "--url http://127.0.0.1:3306"
	   the tag is optional.
	   if the tag is missing, the variable name will be used as token.
	   If the variable name is CamelCase, the token will be transformed
	   into kebab-case, e.g. if the variable is "AuthURL", the token will
	   be "--auth-url"
	*/
	TAG_TOKEN = "token"
	/*
	   short form of command-line token, e.g. short-token:"u"
	   the command-line argument will be "-u http://127.0.0.1:3306"
	   the tag is optional
	*/
	TAG_SHORT_TOKEN = "short-token"
	/*
	   Metavar of the argument
	   the tag is optional
	*/
	TAG_METAVAR = "metavar"
	/*
	   The default value of the argument.
	   the tag is optional
	*/
	TAG_DEFAULT = "default"
	/*
	   The possible values of an arguments. All choices are are concatenatd by "|".
	   e.g. `choices:"1|2|3"`
	   the tag is optional
	*/
	TAG_CHOICES = "choices"
	/*
	   A boolean value explicitly declare whether the argument is optional,
	   the tag is optional
	*/
	TAG_OPTIONAL = "optional"
	/*
	   A boolean value explicitly decalre whther the argument is an subcommand
	   A subcommand argument must be the last positional argument.
	   the tag is optional, the default value is false
	*/
	TAG_SUBCOMMAND = "subcommand"
	/*
	   The attribute defines the possible number of argument. Possible values
	   are:
	       * positive integers, e.g. "1", "2"
	       * "*" any number of arguments
	       * "+" at lease one argument
	       * "?" at most one argument
	   the tag is optional, the default value is "1"
	*/
	TAG_NARGS = "nargs"
	/*
		Alias name of argument
	*/
	TAG_ALIAS = "alias"

Example usage


parser, e := structarg.NewArgumentParser(&Options{},
                                        "programname",
                                        `description text`,
                                        `epilog of the program`)

e = parser.ParseArgs(os.Args[1:], false)
if e != nil {
    panic(e)
}

options := parser.Options().(*Options)

// then access argument values via options
// ...

Documentation

Index

Constants

View Source 
const (
	/*
	   help text of the argument
	   the argument is optional.
	*/
	TAG_HELP = "help"
	/*
	   command-line token for the optional argument, e.g. token:"url"
	   the command-line argument will be "--url http://127.0.0.1:3306"
	   the tag is optional.
	   if the tag is missing, the variable name will be used as token.
	   If the variable name is CamelCase, the token will be transformed
	   into kebab-case, e.g. if the variable is "AuthURL", the token will
	   be "--auth-url"
	*/
	TAG_TOKEN = "token"
	/*
	   short form of command-line token, e.g. short-token:"u"
	   the command-line argument will be "-u http://127.0.0.1:3306"
	   the tag is optional
	*/
	TAG_SHORT_TOKEN = "short-token"
	/*
	   Metavar of the argument
	   the tag is optional
	*/
	TAG_METAVAR = "metavar"
	/*
	   The default value of the argument.
	   the tag is optional
	*/
	TAG_DEFAULT = "default"
	/*
	   The possible values of an arguments. All choices are are concatenatd by "|".
	   e.g. `choices:"1|2|3"`
	   the tag is optional
	*/
	TAG_CHOICES = "choices"
	/*
	   A boolean value explicitly declare whether the argument is optional,
	   the tag is optional
	*/
	TAG_OPTIONAL = "optional"
	/*
	   A boolean value explicitly decalre whther the argument is an subcommand
	   A subcommand argument must be the last positional argument.
	   the tag is optional, the default value is false
	*/
	TAG_SUBCOMMAND = "subcommand"
	/*
	   The attribute defines the possible number of argument. Possible values
	   are:
	       * positive integers, e.g. "1", "2"
	       * "*" any number of arguments
	       * "+" at lease one argument
	       * "?" at most one argument
	   the tag is optional, the default value is "1"
	*/
	TAG_NARGS = "nargs"
	/*
		Alias name of argument
	*/
	TAG_ALIAS = "alias"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Argument 

type Argument interface {
	NeedData() bool
	Token() string
	AliasToken() string
	ShortToken() string
	MetaVar() string
	IsOptional() bool
	IsPositional() bool
	IsMulti() bool
	IsSubcommand() bool
	HelpString(indent string) string
	String() string
	SetValue(val string) error
	Reset()
	DoAction() error
	Validate() error
	SetDefault()
}

type ArgumentParser 

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

func NewArgumentParser 

func NewArgumentParser(target interface{}, prog, desc, epilog string) (*ArgumentParser, error)

func (*ArgumentParser) AddArgument 

func (this *ArgumentParser) AddArgument(arg Argument) error

func (*ArgumentParser) GetOptArgs 

func (this *ArgumentParser) GetOptArgs() []Argument

func (*ArgumentParser) GetPosArgs 

func (this *ArgumentParser) GetPosArgs() []Argument

func (*ArgumentParser) GetSubcommand 

func (this *ArgumentParser) GetSubcommand() *SubcommandArgument

func (*ArgumentParser) HelpString 

func (this *ArgumentParser) HelpString() string

func (*ArgumentParser) Options 

func (this *ArgumentParser) Options() interface{}

func (*ArgumentParser) ParseArgs 

func (this *ArgumentParser) ParseArgs(args []string, ignore_unknown bool) error

func (*ArgumentParser) ParseFile 

func (this *ArgumentParser) ParseFile(filepath string) error

func (*ArgumentParser) ParseKnownArgs 

func (this *ArgumentParser) ParseKnownArgs(args []string) error

func (*ArgumentParser) ShortDescription 

func (this *ArgumentParser) ShortDescription() string

func (*ArgumentParser) Usage 

func (this *ArgumentParser) Usage() string

func (*ArgumentParser) Validate 

func (this *ArgumentParser) Validate() error

type BaseOptions 

type BaseOptions struct {
	PidFile string `help:"Pid file path"`
	Config  string `help:"Configuration file"`
	Help    bool   `help:"Show help and exit"`
	Version bool   `help:"Show version and exit"`
}

type MultiArgument 

type MultiArgument struct {
	SingleArgument
	// contains filtered or unexported fields
}

func (*MultiArgument) IsMulti 

func (this *MultiArgument) IsMulti() bool

func (*MultiArgument) SetValue 

func (this *MultiArgument) SetValue(val string) error

func (*MultiArgument) Validate 

func (this *MultiArgument) Validate() error

type SingleArgument 

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

func (*SingleArgument) AliasToken 

func (this *SingleArgument) AliasToken() string

func (*SingleArgument) AllToken 

func (this *SingleArgument) AllToken() string

func (*SingleArgument) DoAction 

func (this *SingleArgument) DoAction() error

func (*SingleArgument) HelpString 

func (this *SingleArgument) HelpString(indent string) string

func (*SingleArgument) InChoices 

func (this *SingleArgument) InChoices(val string) bool

func (*SingleArgument) IsMulti 

func (this *SingleArgument) IsMulti() bool

func (*SingleArgument) IsOptional 

func (this *SingleArgument) IsOptional() bool

func (*SingleArgument) IsPositional 

func (this *SingleArgument) IsPositional() bool

func (*SingleArgument) IsSubcommand 

func (this *SingleArgument) IsSubcommand() bool

func (*SingleArgument) MetaVar 

func (this *SingleArgument) MetaVar() string

func (*SingleArgument) NeedData 

func (this *SingleArgument) NeedData() bool

func (*SingleArgument) Reset 

func (this *SingleArgument) Reset()

func (*SingleArgument) SetDefault 

func (this *SingleArgument) SetDefault()

func (*SingleArgument) SetValue 

func (this *SingleArgument) SetValue(val string) error

func (*SingleArgument) ShortToken 

func (this *SingleArgument) ShortToken() string

func (*SingleArgument) String 

func (this *SingleArgument) String() string

func (*SingleArgument) Token 

func (this *SingleArgument) Token() string

func (*SingleArgument) Validate 

func (this *SingleArgument) Validate() error

type SubcommandArgument 

type SubcommandArgument struct {
	SingleArgument
	// contains filtered or unexported fields
}

func (*SubcommandArgument) AddSubParser 

func (this *SubcommandArgument) AddSubParser(target interface{}, command string, desc string, callback interface{}) (*ArgumentParser, error)

func (*SubcommandArgument) GetSubParser 

func (this *SubcommandArgument) GetSubParser() *ArgumentParser

func (*SubcommandArgument) HelpString 

func (this *SubcommandArgument) HelpString(indent string) string

func (*SubcommandArgument) Invoke 

func (this *SubcommandArgument) Invoke(args ...interface{}) error

func (*SubcommandArgument) IsSubcommand 

func (this *SubcommandArgument) IsSubcommand() bool

func (*SubcommandArgument) String 

func (this *SubcommandArgument) String() string

func (*SubcommandArgument) SubHelpString 

func (this *SubcommandArgument) SubHelpString(cmd string) (string, error)

type SubcommandArgumentData 

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

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.