command

README

command

The command package provides enhanced command line parsing, built on top of and extending the flag package provided in Go's standard library.

Install

go get github.com/michaeljpetter/command

Documentation

Full go doc style documentation for the package can be viewed online without installing this package by using the GoDoc site here: https://pkg.go.dev/github.com/michaeljpetter/command

Documentation

Overview

Package command implements a command line parser that extends the stdlib flag package, adding support for commands, subcommands, positional parameters, and checked values.

Index

• type Bound
  • func Program(usage string) Bound
  • func (b Bound) Parse() error
• type Command
  • func New(name, usage string, errorHandling flag.ErrorHandling) *Command
  • func (c *Command) Arg(i int) string
  • func (c *Command) Args() []string
  • func (c *Command) Bind(args []string) Bound
  • func (c *Command) HasFlags() bool
  • func (c *Command) HasPositional() bool
  • func (c *Command) HasSubcommands() bool
  • func (c *Command) NArg() int
  • func (c *Command) Parse(args []string) error
  • func (c *Command) PositionalDuration(name string, value *time.Duration, usage string, ...) *time.Duration
  • func (c *Command) PositionalDurationVar(p *time.Duration, name string, value *time.Duration, usage string, ...)
  • func (c *Command) PositionalFloat64(name string, value *float64, usage string, checks ...value.CheckFunc[float64]) *float64
  • func (c *Command) PositionalFloat64Var(p *float64, name string, value *float64, usage string, ...)
  • func (c *Command) PositionalInt(name string, value *int, usage string, checks ...value.CheckFunc[int]) *int
  • func (c *Command) PositionalInt64(name string, value *int64, usage string, checks ...value.CheckFunc[int64]) *int64
  • func (c *Command) PositionalInt64Var(p *int64, name string, value *int64, usage string, ...)
  • func (c *Command) PositionalIntVar(p *int, name string, value *int, usage string, checks ...value.CheckFunc[int])
  • func (c *Command) PositionalString(name string, value *string, usage string, checks ...value.CheckFunc[string]) *string
  • func (c *Command) PositionalStringVar(p *string, name string, value *string, usage string, ...)
  • func (c *Command) PositionalUint(name string, value *uint, usage string, checks ...value.CheckFunc[uint]) *uint
  • func (c *Command) PositionalUint64(name string, value *uint64, usage string, checks ...value.CheckFunc[uint64]) *uint64
  • func (c *Command) PositionalUint64Var(p *uint64, name string, value *uint64, usage string, ...)
  • func (c *Command) PositionalUintVar(p *uint, name string, value *uint, usage string, ...)
  • func (c *Command) PositionalVar(value Value, name, usage string)
  • func (c *Command) PrintPositional()
  • func (c *Command) PrintSubcommands()
  • func (c *Command) Subcommand(name, usage string, handler HandlerFunc)
• type HandlerFunc
• type Value

Types

type Bound

type Bound struct {
	// The embedded command which has been bound.
	*Command
	// contains filtered or unexported fields
}

Bound represents a Command that has been paired with a specific set of command arguments. It is returned from explicit calls to Command.Bind, and implicitly in subcommand handlers.

func Program

func Program(usage string) Bound

Program creates a new top-level Command with a name extracted from os.Args[0], the given usage, and flag.ExitOnError error handling. The result is then bound to os.Args[1:].

This is the typical starting point for most command-line processing.

func (Bound) Parse

func (b Bound) Parse() error

Parse calls Command.Parse with its bound arguments.

type Command

type Command struct {
	// The embedded FlagSet contains the name of the command, plus its flag definitions.
	*flag.FlagSet

	// The behavior of Usage is analogous to FlagSet, but it extended by default to
	// display usage information for all flags, subcommands, and positional parameters.
	// Usage may be replaced with a user function to customize output.
	Usage func()
	// contains filtered or unexported fields
}

Command represents a single command in a command tree, which may contain flags, subcommands, and positional parameters.

func New

func New(name, usage string, errorHandling flag.ErrorHandling) *Command

New creates a new Command with the given name, usage, and error handling.

func (*Command) Arg

func (c *Command) Arg(i int) string

Arg provides indexed access to the remaining arguments after parsing. Arg returns an empty string if the requested element does not exist.

func (*Command) Args

func (c *Command) Args() []string

Args returns the remaining arguments after parsing.

func (*Command) Bind

func (c *Command) Bind(args []string) Bound

Bind pairs this command with a specific set of arguments to be parsed, and returns a Bound command representing that pairing.

func (*Command) HasFlags

func (c *Command) HasFlags() bool

HasFlags indicates whether flags have been defined on this command.

func (*Command) HasPositional

func (c *Command) HasPositional() bool

HasPositional indicates whether positional parameters have been defined on this command.

func (*Command) HasSubcommands

func (c *Command) HasSubcommands() bool

HasSubcommands indicates whether subcommands have been defined on this command.

func (*Command) NArg

func (c *Command) NArg() int

NArg returns the number of remaining arguments after parsing.

func (*Command) Parse

func (c *Command) Parse(args []string) error

Parse parses the given arguments according to the definition of the command. The behavior on error is defined by the flag.ErrorHandling value used to create the command.

func (*Command) PositionalDuration

func (c *Command) PositionalDuration(name string, value *time.Duration, usage string, checks ...value.CheckFunc[time.Duration]) *time.Duration

PositionalDuration defines a positional time.Duration parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalDurationVar

func (c *Command) PositionalDurationVar(p *time.Duration, name string, value *time.Duration, usage string, checks ...value.CheckFunc[time.Duration])

PositionalDurationVar defines a positional time.Duration parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalFloat64

func (c *Command) PositionalFloat64(name string, value *float64, usage string, checks ...value.CheckFunc[float64]) *float64

PositionalFloat64 defines a positional float64 parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalFloat64Var

func (c *Command) PositionalFloat64Var(p *float64, name string, value *float64, usage string, checks ...value.CheckFunc[float64])

PositionalFloat64Var defines a positional float64 parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalInt

func (c *Command) PositionalInt(name string, value *int, usage string, checks ...value.CheckFunc[int]) *int

PositionalInt defines a positional int parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalInt64

func (c *Command) PositionalInt64(name string, value *int64, usage string, checks ...value.CheckFunc[int64]) *int64

PositionalInt64 defines a positional int64 parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalInt64Var

func (c *Command) PositionalInt64Var(p *int64, name string, value *int64, usage string, checks ...value.CheckFunc[int64])

PositionalInt64Var defines a positional int64 parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalIntVar

func (c *Command) PositionalIntVar(p *int, name string, value *int, usage string, checks ...value.CheckFunc[int])

PositionalIntVar defines a positional int parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalString

func (c *Command) PositionalString(name string, value *string, usage string, checks ...value.CheckFunc[string]) *string

PositionalString defines a positional string parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalStringVar

func (c *Command) PositionalStringVar(p *string, name string, value *string, usage string, checks ...value.CheckFunc[string])

PositionalStringVar defines a positional string parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalUint

func (c *Command) PositionalUint(name string, value *uint, usage string, checks ...value.CheckFunc[uint]) *uint

PositionalUint defines a positional uint parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalUint64

func (c *Command) PositionalUint64(name string, value *uint64, usage string, checks ...value.CheckFunc[uint64]) *uint64

PositionalUint64 defines a positional uint64 parameter with the given name, default value, usage, and checks. The returned pointer receives the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalUint64Var

func (c *Command) PositionalUint64Var(p *uint64, name string, value *uint64, usage string, checks ...value.CheckFunc[uint64])

PositionalUint64Var defines a positional uint64 parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalUintVar

func (c *Command) PositionalUintVar(p *uint, name string, value *uint, usage string, checks ...value.CheckFunc[uint])

PositionalUintVar defines a positional uint parameter with the given name, default value, usage, and checks. The pointer p defines the location to receive the parsed value.

If value is nil, the parameter will have no default and will be treated as required.

func (*Command) PositionalVar

func (c *Command) PositionalVar(value Value, name, usage string)

PositionalVar defines a positional parameter with the given Value, name, and usage.

Panics if subcommands have been defined on the same command, as they are mutually exclusive.

Panics if the Value is required, and optional positional parameters have already been defined on the same command.

func (*Command) PrintPositional

func (c *Command) PrintPositional()

PrintPositional prints, to standard error unless configured otherwise, the list of all defined positional parameters and their usage strings.

func (*Command) PrintSubcommands

func (c *Command) PrintSubcommands()

PrintSubcommands prints, to standard error unless configured otherwise, the list of all defined subcommands and their usage strings.

func (*Command) Subcommand

func (c *Command) Subcommand(name, usage string, handler HandlerFunc)

Subcommand defines a subcommand with the given name, usage, and handler. The handler is called only when the subcommand name has been parsed by this command, and is then bound to the remaining arguments.

Panics if positional parameters have been defined on the same command, as they are mutually exclusive.

type HandlerFunc

type HandlerFunc func(Bound)

HandlerFunc defines a function that processes a Bound command. It is used during parsing to delegate to subcommands.

type Value

type Value interface {
	flag.Value
	Required() bool
}

Value extends the flag.Value type, adding support for required values.