opt

README

Description

Package opt implements command line options parsing, which can be used instead of flag package from Go's standard library. It is inspired by GNU getopt package, and try to be close to it (but optional arguments not supported for now).

Short and long option formats are supported: -o and --option. Multiple short options can be grouped with one dash sign: -abc. Option can has non-optional argument. Short option parameter can be passed as a part of option string or with a next coming string. To pass value foo for option o next two syntaxes can be used: -ofoo, -o foo. Long option can be separated from its value with space or equals sign: --option foo, --option=foo. Command-line options and arguments can be passed in any order. -- indicates and of the passed options, and rest is treated as arguments only, even if it is started from dash.

Installation

opt is available using the standard go get command.

Install by running:

go get github.com/vchimishuk/opt

Run tests by running:

go test github.com/vchimishuk/opt

Usage

Define supported options list using Desc structure to describe every option.

descs := []*opt.Desc{
	{"a", "add", opt.ArgNone,
		"", "add new item"},
	{"d", "delete", opt.ArgNone,
		"", "delete item"},
	{"h", "help", opt.ArgNone,
		"", "display help information and exit"},
	{"p", "path", opt.ArgString,
		"path", "path to store output files to"},
}

Parse command-line arguments.

opts, args, err := opt.Parse(os.Args[1:], descs)
if err != nil {
	fmt.Fprintf(os.Stderr, "%s\n", err)
	os.Exit(1)
}

Use options and arguments.

if opts.Has("help") {
	fmt.Println("Options:")
	fmt.Print(opt.Usage(descs))
}

path := "default"
if opts.Has("path") {
	path = opts.String("path")
}
// Alternative way is to use the next line.
// path := opts.StringOr("path", "default")

if opts.Has("add") {
	fmt.Printf("Adding new item into '%s'...\n", path)
}
if opts.Has("delete") {
	fmt.Printf("Deleting new item from '%s'...\n", path)
}

fmt.Printf("arguments: %s\n", args)

Documentation

Overview

Package opt implements command line options parsing.

Short and long option formats are supported: -o and --option. Multiple short options can be grouped with one dash sign: -abc. Option can has non-optional argument. Short option parameter can be passed as a part of option string or with a next coming string. To pass value `foo` for option `o` next two syntaxes can be used: -ofoo, -o foo. Long option can be separated from its value with space or equals sign: --option foo, --option=foo. Command-line options and arguments can be passed in any order. `--` indicates and of the passed options, and rest is treated as arguments only, even if it is started from dash.

Usage:

1. Define supported options list using Desc structure to describe every option.

descs := []*opt.Desc{
	{"a", "add", opt.ArgNone,
		"", "add new item"},
	{"d", "delete", opt.ArgNone,
		"", "delete item"},
	{"h", "help", opt.ArgNone,
		"", "display help information and exit"},
	{"p", "path", opt.ArgString,
		"path", "path to store output files to"},
}

2. Parse command-line arguments. opts, args, err := opt.Parse(os.Args[1:], descs) if err != nil { fmt.Fprintf(os.Stderr, "%s\n", err) os.Exit(1) }

3. Use options and arguments. if opts.Has("help") { fmt.Println("Options:") fmt.Print(opt.Usage(descs)) }

   path := opts.StringOr("path", "")

   if opts.Has("add") { fmt.Printf("Adding new item into '%s'...\n", path) } if opts.Has("delete") { fmt.Printf("Deleting new item from '%s'...\n", path) }

   fmt.Printf("arguments: %s\n", args)

Index

• func Usage(descs []*Desc) string
• type ArgType
• type Desc
• type Option
• type Options
  • func Parse(args []string, descs []*Desc) (Options, []string, error)
  • func (o Options) Float(name string) (float64, bool)
  • func (o Options) FloatOr(name string, value float64) float64
  • func (o Options) Floats(name string) []float64
  • func (o Options) Has(name string) bool
  • func (o Options) Int(name string) (int, bool)
  • func (o Options) IntOr(name string, value int) int
  • func (o Options) Ints(name string) []int
  • func (o Options) String(name string) (string, bool)
  • func (o Options) StringOr(name string, value string) string
  • func (o Options) Strings(name string) []string

Functions

func Usage

func Usage(descs []*Desc) string

Usage returns option description lines ready to be printed to stdout.

Return string example:

-a, --add     add new item
-d, --delete  delete item

Types

type ArgType

type ArgType int

Argument type type.

const (
	ArgNone ArgType = iota
	ArgFloat
	ArgInt
	ArgString
)

type Desc

type Desc struct {
	// Short, one letter, name of the option. Short options
	// starts with single dash sign.
	Short string
	// Long option name. Long options starts with two dash signs.
	Long string
	// Arg is an option type description.
	Arg ArgType
	// Name of the argument for string, int and float options.
	// This name is used for usage information generation.
	ArgName string
	// Option's description. Used for usage information generation.
	Description string
}

Desc describes available option. Short or Long option can be empty, in case option doen't have short or long version respectively.

type Option

type Option struct {
	// Option description.
	Desc *Desc
	// Arguments passed with command line arguments.
	Args []interface{}
}

Option parsed from command line arguments.

type Options

type Options []*Option

Options is a list of all parsed options.

func Parse

func Parse(args []string, descs []*Desc) (Options, []string, error)

Parse parses given command line arguments. Available application arguments are defined by `descs` argument. Returns a list of parsed options and a list of free arguments.

func (Options) Float

func (o Options) Float(name string) (float64, bool)

Float returns float64 option's argument by its short or long name. If option was not defined second parameter is false.

func (Options) FloatOr

func (o Options) FloatOr(name string, value float64) float64

FloatOr returns argument of float option or default value if option was not defined by command line arguments list.

func (Options) Floats

func (o Options) Floats(name string) []float64

Floats returns a list of arguments for float64 option by its short or long name.

func (Options) Has

func (o Options) Has(name string) bool

Has returns true if option named `name` was passed with args.

func (Options) Int

func (o Options) Int(name string) (int, bool)

Int returns integer option's argument by its short or long name. If option was not defined second parameter is false.

func (Options) IntOr

func (o Options) IntOr(name string, value int) int

IntOr returns argument of int option or default value if option was not defined by command line arguments list.

func (Options) Ints

func (o Options) Ints(name string) []int

Ints returns a list of arguments for int option by its short or long name.

func (Options) String

func (o Options) String(name string) (string, bool)

String returns string option's argument by its short or long name. If option was not defined second parameter is false.

func (Options) StringOr

func (o Options) StringOr(name string, value string) string

StringOr returns argument of string option or default value if option was not defined by command line arguments list.

func (Options) Strings

func (o Options) Strings(name string) []string

Strings returns a list of arguments for string option by its short or long name.