options

package
v12.45.0 Latest Latest
Warning

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

Go to latest
Published: May 3, 2022 License: Apache-2.0 Imports: 5 Imported by: 23

Documentation

Overview

Package options provides methods for working with command-line options

Index

Examples

Constants

View Source
const (
	STRING = iota // String option
	INT           // Int/Uint option
	BOOL          // Boolean option
	FLOAT         // Floating number option
	MIXED         // String or boolean option
)

Options types

View Source
const (
	ERROR_UNSUPPORTED = iota
	ERROR_NO_NAME
	ERROR_DUPLICATE_LONGNAME
	ERROR_DUPLICATE_SHORTNAME
	ERROR_OPTION_IS_NIL
	ERROR_EMPTY_VALUE
	ERROR_REQUIRED_NOT_SET
	ERROR_WRONG_FORMAT
	ERROR_CONFLICT
	ERROR_BOUND_NOT_SET
	ERROR_UNSUPPORTED_VALUE
)

Error codes

Variables

This section is empty.

Functions

func Add

func Add(name string, opt *V) error

Add add new supported option

Example
// Add options
Add("u:user", &V{Type: STRING, Value: "john"})
Add("l:lines", &V{Type: INT, Min: 1, Max: 100})

args, _ := Parse()

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Lines: %d\n", GetI("l:lines"))
Output:

func AddMap

func AddMap(optMap Map) []error

AddMap add supported option as map

Example
// Add options
AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

args, _ := Parse()

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Lines: %d\n", GetI("l:lines"))
Output:

func GetB

func GetB(name string) bool

GetB returns option value as boolean

Example
args, _ := Parse(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Force: %t\n", GetB("f:force"))
Output:

func GetF

func GetF(name string) float64

GetF returns option value as floating number

Example
args, _ := Parse(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Ratio: %g\n", GetF("r:ratio"))
Output:

func GetI

func GetI(name string) int

GetI returns option value as integer

Example
args, _ := Parse(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Lines: %d\n", GetI("l:lines"))
Output:

func GetS

func GetS(name string) string

GetS returns option value as string

Example
args, _ := Parse(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", GetS("u:user"))
fmt.Printf("Lines: %d\n", GetI("l:lines"))
Output:

func Has

func Has(name string) bool

Has check that option exists and set

Example
args, _ := Parse(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Has user option: %t\n", Has("u:user"))
fmt.Printf("Has lines option: %t\n", Has("l:lines"))
Output:

func ParseOptionName

func ParseOptionName(name string) (string, string)

ParseOptionName parses combined name and returns long and short options

func Q

func Q(opts ...string) string

Q merges several options to string

Types

type Argument added in v12.45.0

type Argument string

Argument is command argument

func (Argument) Base added in v12.45.0

func (a Argument) Base() Argument

Base is shorthand analog of path.Base

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"run", "/srv/app//conf/myapp.conf"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Clean: %s\n", args.Get(1).Clean())
fmt.Printf("Base: %s\n", args.Get(1).Base())
fmt.Printf("Dir: %s\n", args.Get(1).Dir())
fmt.Printf("Ext: %s\n", args.Get(1).Ext())
fmt.Printf("IsAbs: %t\n", args.Get(1).IsAbs())
Output:

Arguments: [run /srv/app//conf/myapp.conf]
Clean: /srv/app/conf/myapp.conf
Base: myapp.conf
Dir: /srv/app/conf
Ext: .conf
IsAbs: true

func (Argument) Bool added in v12.45.0

func (a Argument) Bool() (bool, error)

Int converts argument to int

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"release", "yes"},
)

fmt.Printf("Arguments: %v\n", args)
force, _ := args.Get(1).Bool()
fmt.Printf("Force: %t\n", force)
Output:

Arguments: [release yes]
Force: true

func (Argument) Clean added in v12.45.0

func (a Argument) Clean() Argument

Clean is shorthand analog of path.Clean

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"run", "/srv/app//conf/myapp.conf"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Clean: %s\n", args.Get(1).Clean())
fmt.Printf("Base: %s\n", args.Get(1).Base())
fmt.Printf("Dir: %s\n", args.Get(1).Dir())
fmt.Printf("Ext: %s\n", args.Get(1).Ext())
fmt.Printf("IsAbs: %t\n", args.Get(1).IsAbs())
Output:

Arguments: [run /srv/app//conf/myapp.conf]
Clean: /srv/app/conf/myapp.conf
Base: myapp.conf
Dir: /srv/app/conf
Ext: .conf
IsAbs: true

func (Argument) Dir added in v12.45.0

func (a Argument) Dir() Argument

Dir is shorthand analog of path.Dir

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"run", "/srv/app//conf/myapp.conf"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Clean: %s\n", args.Get(1).Clean())
fmt.Printf("Base: %s\n", args.Get(1).Base())
fmt.Printf("Dir: %s\n", args.Get(1).Dir())
fmt.Printf("Ext: %s\n", args.Get(1).Ext())
fmt.Printf("IsAbs: %t\n", args.Get(1).IsAbs())
Output:

Arguments: [run /srv/app//conf/myapp.conf]
Clean: /srv/app/conf/myapp.conf
Base: myapp.conf
Dir: /srv/app/conf
Ext: .conf
IsAbs: true

func (Argument) Ext added in v12.45.0

func (a Argument) Ext() Argument

Ext is shorthand analog of path.Ext

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"run", "/srv/app//conf/myapp.conf"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Clean: %s\n", args.Get(1).Clean())
fmt.Printf("Base: %s\n", args.Get(1).Base())
fmt.Printf("Dir: %s\n", args.Get(1).Dir())
fmt.Printf("Ext: %s\n", args.Get(1).Ext())
fmt.Printf("IsAbs: %t\n", args.Get(1).IsAbs())
Output:

Arguments: [run /srv/app//conf/myapp.conf]
Clean: /srv/app/conf/myapp.conf
Base: myapp.conf
Dir: /srv/app/conf
Ext: .conf
IsAbs: true

func (Argument) Float added in v12.45.0

func (a Argument) Float() (float64, error)

Int converts argument to int

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"ratio", "2.37"},
)

fmt.Printf("Arguments: %v\n", args)
lines, _ := args.Get(1).Float()
fmt.Printf("Ratio: %g\n", lines)
Output:

Arguments: [ratio 2.37]
Ratio: 2.37

func (Argument) Int added in v12.45.0

func (a Argument) Int() (int, error)

Int converts argument to int

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
lines, _ := args.Get(2).Int()
fmt.Printf("Lines: %d\n", lines)
Output:

Arguments: [head file.txt 10]
Lines: 10

func (Argument) Int64 added in v12.45.0

func (a Argument) Int64() (int64, error)

Int64 converts argument to int64

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
lines, _ := args.Get(2).Int64()
fmt.Printf("Lines: %d\n", lines)
Output:

Arguments: [head file.txt 10]
Lines: 10

func (Argument) IsAbs added in v12.45.0

func (a Argument) IsAbs() bool

IsAbs is shorthand analog of path.IsAbs

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"run", "/srv/app//conf/myapp.conf"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Clean: %s\n", args.Get(1).Clean())
fmt.Printf("Base: %s\n", args.Get(1).Base())
fmt.Printf("Dir: %s\n", args.Get(1).Dir())
fmt.Printf("Ext: %s\n", args.Get(1).Ext())
fmt.Printf("IsAbs: %t\n", args.Get(1).IsAbs())
Output:

Arguments: [run /srv/app//conf/myapp.conf]
Clean: /srv/app/conf/myapp.conf
Base: myapp.conf
Dir: /srv/app/conf
Ext: .conf
IsAbs: true

func (Argument) Match added in v12.45.0

func (a Argument) Match(pattern string) (bool, error)

Match is shorthand analog of path.Match

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"parse", "fileA.txt", "fileB.jpg"},
)

fmt.Printf("Arguments: %v\n", args)
m1, _ := args.Get(1).Match("*.txt")
m2, _ := args.Get(2).Match("*.txt")
fmt.Printf("%s is match: %t\n", args.Get(1), m1)
fmt.Printf("%s is match: %t\n", args.Get(2), m2)
Output:

Arguments: [parse fileA.txt fileB.jpg]
fileA.txt is match: true
fileB.jpg is match: false

func (Argument) String added in v12.45.0

func (a Argument) String() string

String converts argument to string

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Command: %s\n", args.Get(0).String())
Output:

Arguments: [head file.txt 10]
Command: head

func (Argument) ToLower added in v12.45.0

func (a Argument) ToLower() Argument

ToLower returns argument converted to lower case

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"add-user", "John"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", args.Get(1).ToLower().String())
Output:

Arguments: [add-user John]
User: john

func (Argument) ToUpper added in v12.45.0

func (a Argument) ToUpper() Argument

ToUpper returns argument converted to upper case

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"add-user", "John"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", args.Get(1).ToUpper().String())
Output:

Arguments: [add-user John]
User: JOHN

func (Argument) Uint added in v12.45.0

func (a Argument) Uint() (uint64, error)

Uint converts argument to uint

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
lines, _ := args.Get(2).Uint()
fmt.Printf("Lines: %d\n", lines)
Output:

Arguments: [head file.txt 10]
Lines: 10

type Arguments

type Arguments []Argument

Arguments is a slice with with command argument

func NewArguments added in v12.45.0

func NewArguments(args ...string) Arguments

NewArguments creates new arguments slice from given strings

Example
args := NewArguments("head", "file.txt", "10")

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Command: %s\n", args.Get(0).String())
fmt.Printf("File: %s\n", args.Get(1).String())

lines, _ := args.Get(2).Int()
fmt.Printf("Lines: %d\n", lines)
Output:

Arguments: [head file.txt 10]
Command: head
File: file.txt
Lines: 10

func Parse

func Parse(optMap ...Map) (Arguments, []error)

Parse parse options

Example
// Key is option in format "short-name:long-name" or "long-name"
// We highly recommend defining options names as constants
optMap := Map{
	"s:string":   {},                                     // By default, argument has string type
	"S:string2":  {Type: STRING, Value: "Default value"}, // You can predefine default values
	"int":        {Type: INT},                            // Integer without short name
	"I:int2":     {Type: INT, Min: 1, Max: 10},           // Integer with limits
	"f:float":    {Type: FLOAT, Value: 10.0},             // Float
	"b:boolean":  {Type: BOOL},                           // Boolean
	"r:required": {Type: INT, Required: true},            // Some options can be marked as required
	"m:merg":     {Type: STRING, Mergeble: true},         // Mergeble options can be defined more than one time
	"h:help":     {Type: BOOL, Alias: "u:usage about"},   // You can define argument aliases
	"e:example":  {Conflicts: "s:string S:string2"},      // Option conflicts with string and string2 (options can't be set at same time)
	"E:example2": {Bound: "int I:int2"},                  // Option bound with int and int2 (options must be set at same time)
}

// args is a slice with command arguments
args, errs := Parse(optMap)

if len(errs) != 0 {
	for _, err := range errs {
		fmt.Printf("Error: %v\n", err)
		os.Exit(1)
	}
}

if Has("s:string") {
	fmt.Println("\"--string/-s\" is set")
} else {
	fmt.Println("\"--string/-s\" is not set")
}

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("First argument: %s\n\n", args.Get(0).String())

fmt.Printf("string → %s\n", GetS("string"))
fmt.Printf("int → %d\n", GetI("int"))
fmt.Printf("float → %f\n", GetF("f:float"))
fmt.Printf("boolean → %t\n", GetB("b:boolean"))
Output:

func (Arguments) Append added in v12.45.0

func (a Arguments) Append(args ...string) Arguments

Append adds arguments to the end of the arguments slices

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt"},
)

args = args.Append("10")

fmt.Printf("Arguments: %v\n", args.Strings())
Output:

Arguments: [head file.txt 10]

func (Arguments) Filter added in v12.45.0

func (a Arguments) Filter(pattern string) Arguments

Filter filters arguments by given glob pattern

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"parse", "fileA.txt", "fileB.jpg", "fileC.txt"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Text files: %s\n", args[1:].Filter("*.txt"))
Output:

Arguments: [parse fileA.txt fileB.jpg fileC.txt]
Text files: [fileA.txt fileC.txt]

func (Arguments) Get

func (a Arguments) Get(index int) Argument

Get returns argument with given index

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Command: %s\n", args.Get(0).String())
fmt.Printf("File: %s\n", args.Get(1).String())

lines, _ := args.Get(2).Int()
fmt.Printf("Lines: %d\n", lines)
Output:

Arguments: [head file.txt 10]
Command: head
File: file.txt
Lines: 10

func (Arguments) Has

func (a Arguments) Has(index int) bool

Has returns true if arguments contains argument with given index

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Has command: %t\n", args.Has(0))
Output:

Arguments: [head file.txt 10]
Has command: true

func (Arguments) Last added in v12.45.0

func (a Arguments) Last() Argument

Get returns the last argument

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Last argument: %s\n", args.Last())
Output:

Arguments: [head file.txt 10]
Last argument: 10

func (Arguments) Strings added in v12.45.0

func (a Arguments) Strings() []string

Strings converts arguments to slice with strings

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"head", "file.txt", "10"},
)

fmt.Printf("Arguments: %v\n", args.Strings())
Output:

Arguments: [head file.txt 10]

func (Arguments) Unshift added in v12.45.0

func (a Arguments) Unshift(args ...string) Arguments

Unshift adds arguments to the beginning of the arguments slices

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"file.txt", "10"},
)

args = args.Unshift("head")

fmt.Printf("Arguments: %v\n", args.Strings())
Output:

Arguments: [head file.txt 10]

type Map

type Map map[string]*V

Map is map with list of options

type OptionError

type OptionError struct {
	Option      string
	BoundOption string
	Type        int
}

OptionError is argument parsing error

func (OptionError) Error

func (e OptionError) Error() string

type Options

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

Options is options struct

func NewOptions

func NewOptions() *Options

NewOptions create new options struct

Example
opts := NewOptions()

// Add options
opts.Add("u:user", &V{Type: STRING, Value: "john"})
opts.Add("l:lines", &V{Type: INT, Min: 1, Max: 100})

// args contains unparsed values
args, errs := opts.Parse([]string{"-u", "bob", "-l", "12", "file.txt"})

if len(errs) != 0 {
	for _, err := range errs {
		fmt.Printf("Error: %v\n", err)
		os.Exit(1)
	}
}

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

func (*Options) Add

func (opts *Options) Add(name string, option *V) error

Add adds a new supported option

Example
opts := NewOptions()

// Add options
opts.Add("u:user", &V{Type: STRING, Value: "john"})
opts.Add("l:lines", &V{Type: INT, Min: 1, Max: 100})

args, _ := opts.Parse([]string{"-u", "bob", "-l", "12", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

func (*Options) AddMap

func (opts *Options) AddMap(optMap Map) []error

AddMap adds supported options as map

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

args, _ := opts.Parse([]string{"-u", "bob", "-l", "12", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

func (*Options) GetB

func (opts *Options) GetB(name string) bool

GetB returns option value as boolean

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"f:force": {Type: BOOL},
})

args, _ := opts.Parse([]string{"-u", "bob", "-f", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Force: %t\n", opts.GetB("f:force"))
Output:

Arguments: [file.txt]
User: bob
Force: true

func (*Options) GetF

func (opts *Options) GetF(name string) float64

GetF returns option value as floating number

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"r:ratio": {Type: FLOAT},
})

args, _ := opts.Parse([]string{"-u", "bob", "-r", "2.35", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Ratio: %g\n", opts.GetF("r:ratio"))
Output:

Arguments: [file.txt]
User: bob
Ratio: 2.35

func (*Options) GetI

func (opts *Options) GetI(name string) int

GetI returns option value as integer

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

args, _ := opts.Parse([]string{"-u", "bob", "-l", "12", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

func (*Options) GetS

func (opts *Options) GetS(name string) string

GetS returns option value as string

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

args, _ := opts.Parse([]string{"-u", "bob", "-l", "12", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

func (*Options) Has

func (opts *Options) Has(name string) bool

Has check that option exists and set

Example
opts := NewOptions()

// Add options
opts.AddMap(Map{
	"u:user":  {Type: STRING, Value: "john"},
	"l:lines": {Type: INT, Min: 1, Max: 100},
})

args, _ := opts.Parse([]string{"-u", "bob", "file.txt"})

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("Has user option: %t\n", opts.Has("u:user"))
fmt.Printf("Has lines option: %t\n", opts.Has("l:lines"))
Output:

Arguments: [file.txt]
Has user option: true
Has lines option: false

func (*Options) Parse

func (opts *Options) Parse(rawOpts []string, optMap ...Map) (Arguments, []error)

Parse parse options

Example
opts := NewOptions()

args, _ := opts.Parse(
	[]string{"-u", "bob", "-l", "12", "file.txt"},
	Map{
		"u:user":  {Type: STRING, Value: "john"},
		"l:lines": {Type: INT, Min: 1, Max: 100},
	},
)

fmt.Printf("Arguments: %v\n", args)
fmt.Printf("User: %s\n", opts.GetS("u:user"))
fmt.Printf("Lines: %d\n", opts.GetI("l:lines"))
Output:

Arguments: [file.txt]
User: bob
Lines: 12

type V

type V struct {
	Type      int     // option type
	Max       float64 // maximum integer option value
	Min       float64 // minimum integer option value
	Alias     string  // list of aliases
	Conflicts string  // list of conflicts options
	Bound     string  // list of bound options
	Mergeble  bool    // option supports options value merging
	Required  bool    // option is required

	Value interface{} // default value
	// contains filtered or unexported fields
}

V is basic option struct

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL