args

README

args

Simple go command line argument parser

Documentation

Overview

Package args implements a simple command line argument parser

It supports GNU-style command line invocations like:

git commit --verbose --level=info --message "message"

Grouped or "fused" options like the following are not supported:

program -l value -Q -v -i  // OK
program -lvalue -Qvi       // Not supported

Usage of the package revolves around calling Parse to convert command line arguments into a Bag data structure, then using the attached methdos to extract what you need

Terminology

• Option: A switch with a value (e.g. "--option=value" or "--option value")
• Flag: A switch without a value (e.g. "--flag")
• Operand: A positional parameter (e.g. "whatever")
• Ignored: All arguments that appear after the end-of-options marker: (e.g. "./program -- nothing here is parsed")

Index

• type Bag
  • func Parse(args []string) (*Bag, error)
  • func (b *Bag) IsEmpty() bool
  • func (b *Bag) RemoveFlag(aliases ...string) bool
  • func (b *Bag) RemoveIgnored() []string
  • func (b *Bag) RemoveOperand() string
  • func (b *Bag) RemoveOption(aliases ...string) string
  • func (b *Bag) RemoveRemaining() []string

Types

type Bag

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

A bag of parsed command line arguments. Its zero value is a bag with no arguments.

func Parse

func Parse(args []string) (*Bag, error)

Parses the given command line arguments and returns an Bag

The first element of args should be the name of the executing program

func (*Bag) IsEmpty

func (b *Bag) IsEmpty() bool

Returns true when there are no more flags, options or arguments left

Ignored arguments are not counted

func (*Bag) RemoveFlag

func (b *Bag) RemoveFlag(aliases ...string) bool

Removes the first flag whose name matches any of the given aliases

func (*Bag) RemoveIgnored

func (b *Bag) RemoveIgnored() []string

Returns a slice of all the arguments after the end-of-options marker (i.e. `--`)

Subsequent calls will return an empty slice

func (*Bag) RemoveOperand

func (b *Bag) RemoveOperand() string

Removes the next operand, if any

Returns an empty string if there are no more operands to remove.

func (*Bag) RemoveOption

func (b *Bag) RemoveOption(aliases ...string) string

Removes the first option from the bag whose name matches any of the given aliases, and returns its value.

This works with both space-separated and `=`-separated option forms (i.e. `--option=value` and `--option value`)

func (*Bag) RemoveRemaining

func (b *Bag) RemoveRemaining() []string

Removes any leftover flag, options and operands that have not been `Remove*`d.

The returned slice will not include any arguments that appeared after the end-of-options marker (i.e. `--`). Use [RemoveIgnored] for those.

Subsequent calls will return an empty slice