params

README

Params-Go

This package provides a simple Parser that can parse a sequence of arguments, for instande command line arguments. However, it can parse any parameters given.

Purpose

This a just a programmatic exercise for me where I try to implement a package with a simple API for handling command line arguments.

Usage

The usage is best demonstrated with examples.

Non-positional arguments

Non-positional arguments are those which are provided with dashes followed by a name, e.g. --myarg 10 and is either string or int type. The argument can the be used in the following ways:

prog --myarg <val>	# argument name and value separated by space
prog --myarg=<val>	# argument name and value separated by =
prog -myarg=<val>	# same as above, only with one dash

These can be created by using the AddString and AddInt functions, respectively:

parser := params.NewParser()
var strArg string
var intArg int

parser.AddString(&strArg, "str", "my default string value", "a string arg")
parser.AddInt(&intArg, "int", 666, "an int arg")
parser.Parse()

As you can see, you provide a pointer to the variable which you want to set.

Options are just specified as, well, an option, and requires no value. They are always false by default.

parser := params.NewParser()
var boolArg bool
parser.AddOption(&boolArg, "myopt", "my special flag")

Positional arguments

Positional arguments can be added using the AddPosString function. Positional arguments currently have the following limitations:

• Are always required
• Only type string
• The order of the calls to AddPosString determines the order of the arguments (i.e the positional arguments are expected in that order)

Just the like other functions AddPosString first takes a pointer to the variable which should be set followed by the name and description.

parser := params.NewParser()
var pos string
parser.AddPosString(&pos, "pos1", "positional arg")

Alias

You can give arguments an alias by specifying a single letter as the last parameter on any Add_ function:

parser := params.NewParser()
var arg string
parser.AddPosString(&arg, "marg", "defval", "some arg", "m")

Example

The following example demonstrate how to parse command line arguments.

parser := params.NewParser()
var strArg string
var intArg int
var option bool
var posArg string

parser.AddString(&strArg, "mystr", "my default string value", "a string arg", "s")
parser.AddInt(&intArg, "myint", 1234, "an int arg")
parser.AddOption(&option, "myopt", "an option")
parser.AddPosString(&posArg, "pos", "a positional arg")

parser.Name("gnarg-demo")
parser.Description("A demo of this fantastic (?) Go package")

err := parser.Parse() // Must be called to process the arguments
if err != nil {
      panic(err)
}

fmt.Println("Value of the string argument:", strArg)
fmt.Println("Value of the int argument:", intArg)
fmt.Println("Value of the option:", option)
fmt.Println("Value of the positional argument:", posArg)

fmt.Println("Remaining arguments after parse:", parser.Args())

$ ./gnarg --myint=1337 pos-arg-val -s=lol
Value of the string argument: lol
Value of the int argument: 1337
Value of the option: false
Value of the positional argument: pos-arg-val
Remaining arguments after parse: []

Help

params.-go also provide a -h/--help flag that prints a classic usage text. For instance, the program above would print the following:

$ ./params --help
Usage: demo pos [-h/--help] [-s/--mystr[=]MYSTR] [--myint[=]MYINT] [--myopt]

A demo of this sheety (?) Go package
                pos    a positional arg
          -h/--help    Displays this message
 -s/--mystr[=]MYSTR    a string arg
    --myint[=]MYINT    an int arg
            --myopt    an option

Documentation

Index

• type Parser
  • func NewParser() *Parser
  • func (parser *Parser) AddInt(variable *int, name string, defaultValue int, description string, ...) error
  • func (parser *Parser) AddOption(variable *bool, name, description string, opt ...string) error
  • func (parser *Parser) AddPosInt(variable *int, name, description string) error
  • func (parser *Parser) AddPosString(variable *string, name, description string) error
  • func (parser *Parser) AddString(variable *string, name, defaultValue, description string, opt ...string) error
  • func (parser *Parser) Args() []string
  • func (parser *Parser) Description(desc string)
  • func (parser *Parser) HasErrors() bool
  • func (parser *Parser) Name(n string)
  • func (parser *Parser) Parse(params ...string) error
  • func (parser *Parser) Parsed() bool
  • func (parser *Parser) PrintUsageAndExit(status int)
  • func (parser *Parser) Reset()

Types

type Parser

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

Parser represents an argument parser

func NewParser

func NewParser() *Parser

NewParser creates a new parser

func (*Parser) AddInt

func (parser *Parser) AddInt(variable *int, name string, defaultValue int, description string, opt ...string) error

AddInt ...

func (*Parser) AddOption

func (parser *Parser) AddOption(variable *bool, name, description string, opt ...string) error

AddOption adds an optional flag

func (*Parser) AddPosInt

func (parser *Parser) AddPosInt(variable *int, name, description string) error

AddPosInt adds a new positional int argument

func (*Parser) AddPosString

func (parser *Parser) AddPosString(variable *string, name, description string) error

AddPosString adds a new positional string argument

func (*Parser) AddString

func (parser *Parser) AddString(variable *string, name, defaultValue, description string, opt ...string) error

AddString adds a new string parameter.

func (*Parser) Args

func (parser *Parser) Args() []string

Args returns the remaing arguments after Parse() has been called.

func (*Parser) Description

func (parser *Parser) Description(desc string)

Description adds a description of the program, which will be displayed in the usage text

func (*Parser) HasErrors

func (parser *Parser) HasErrors() bool

HasErrors returns true if the parser found errors when parsing

func (*Parser) Name

func (parser *Parser) Name(n string)

Name sets the name of the program, which will be displayed in the usage text

func (*Parser) Parse

func (parser *Parser) Parse(params ...string) error

Parse tries to parse the arguments specified. If no is given, it uses os.Args.

func (*Parser) Parsed

func (parser *Parser) Parsed() bool

Parsed returns true if Parse() has been called

func (*Parser) PrintUsageAndExit

func (parser *Parser) PrintUsageAndExit(status int)

PrintUsageAndExit can be used if parsing os.Args

func (*Parser) Reset

func (parser *Parser) Reset()

Reset the global state