bargle

README

bargle

bargle (N.B. bARGle) is a command-line argument parsing library for Go. The name is an homage to Bargle the Enchanter, and a phonetic expression of how frustrating good argument parsing is to use and implement in Go.

Documentation

Index

• Constants
• Variables
• func Env(key string, u Unmarshaler) *env
• func Keyword(arg string) keyword
• func Long(key string, u Unmarshaler) long
• func LongElems(u Unmarshaler, firstElem string, elems ...string) long
• func ParseAll(p *Parser, params ...Arg)
• func ParseLongBuiltin[U BuiltinUnmarshalerType](p *Parser, value *U, elem string, elems ...string) bool
• func UnaryUnmarshalFunc[T any](t *T, f func(string) (T, error)) unaryUnmarshalFunc[T]
• func WithDesc(desc string, arg Arg) interface{ ... }
• type Arg
  • func NewBuiltinUnmarshalerLongElemsParser[U BuiltinUnmarshalerType](value *U, elem string, elems ...string) Arg
  • func Positional(metavar string, u Unmarshaler) Arg
• type ArgDescer
• type ArgInfo
• type ArgType
• type ArgValuer
• type Builtin
  • func (b *Builtin[T]) Unmarshal(ctx UnmarshalContext) error
• type BuiltinUnmarshalerType
• type Helper
• type Input
• type Metavar
• type ParseAttempt
• type ParseContext
• type Parser
  • func NewParser() *Parser
  • func NewParserNoArgs() *Parser
  • func (p *Parser) DoHelpIfHelping()
  • func (p *Parser) DoHelpIfHelpingOpts(opts PrintHelpOpts)
  • func (p *Parser) Err() error
  • func (p *Parser) Fail() error
  • func (p *Parser) FailIfArgsRemain()
  • func (p *Parser) Ok() bool
  • func (p *Parser) Parse(arg Arg) (matched bool)
  • func (p *Parser) ParseAny(arg ...Arg) bool
  • func (p *Parser) PopAll() (all []string)
  • func (p *Parser) SetArgs(args ...string)
  • func (p *Parser) SetDefault(u Unmarshaler, args ...string) bool
  • func (p *Parser) SetError(err error)
  • func (p *Parser) SetHelper(helper Helper)
  • func (p *Parser) SetHelping()
• type PrintHelpOpts
• type UnmarshalContext
• type Unmarshaler
  • func AppendSlice[T any](s *[]T, uc func(*T) Unmarshaler) Unmarshaler
  • func BuiltinOptionUnmarshaler[V BuiltinUnmarshalerType](o *g.Option[V]) Unmarshaler
  • func BuiltinUnmarshaler[T BuiltinUnmarshalerType](t *T) Unmarshaler
  • func BuiltinUnmarshalerFromAny(t any) Unmarshaler
  • func OptionUnmarshaler[V any](o *g.Option[V], vu func(*V) Unmarshaler) Unmarshaler
  • func String(s *string) Unmarshaler
  • func TextUnmarshaler(tu encoding.TextUnmarshaler) Unmarshaler
• type UnmarshalerValuer

Constants

const (
	ArgTypeSwitch = iota + 1
	ArgTypeEnvVar
	ArgTypePos
)

Variables

var (
	ErrNoArgs            = errors.New("no arguments remaining")
	ErrExpectedArguments = errors.New("expected arguments")
)

Functions

func Env

func Env(key string, u Unmarshaler) *env

func Keyword

func Keyword(arg string) keyword

func Long

func Long(key string, u Unmarshaler) long

Don't include the prefix "--" for now.

func LongElems

func LongElems(u Unmarshaler, firstElem string, elems ...string) long

An experiment with maybe allowing separators and key styling to be propagated from a config down the track.

func ParseAll

func ParseAll(p *Parser, params ...Arg)

Continues parsing preferring earlier arguments to later ones until nothing parses anymore. Doesn't distinguish positional arguments or support "after parse" effects for now.

func ParseLongBuiltin

func ParseLongBuiltin[U BuiltinUnmarshalerType](p *Parser, value *U, elem string, elems ...string) bool

Convenience function to parse a long using builtin unmarshaller. TODO: *Parser should be relaxed to a Parser interface when it can be separated out.

func UnaryUnmarshalFunc

func UnaryUnmarshalFunc[T any](t *T, f func(string) (T, error)) unaryUnmarshalFunc[T]

func WithDesc

func WithDesc(desc string, arg Arg) interface {
	Arg
	ArgDescer
}

Types

type Arg

type Arg interface {
	Parse(ctx ParseContext) bool
	ArgInfo() ArgInfo
}

func NewBuiltinUnmarshalerLongElemsParser

func NewBuiltinUnmarshalerLongElemsParser[U BuiltinUnmarshalerType](value *U, elem string, elems ...string) Arg

Returns a long-option parser for a builtin unmarshallable value.

func Positional

func Positional(metavar string, u Unmarshaler) Arg

Creates a positional argument. Positional arguments are parsed based on their relative position in the argument stream.

type ArgDescer

type ArgDescer interface {
	ArgDesc() string
}

type ArgInfo

type ArgInfo struct {
	MatchingForms []string
	ArgType       ArgType
	// Whether the argument is set at a global level and so always relevant to a parsing scope.
	// Environment variables for example.
	Global bool
}

type ArgType

type ArgType int

type ArgValuer

type ArgValuer interface {
	Value() any
}

type Builtin

type Builtin[T BuiltinUnmarshalerType] struct {
	Value T
}

func (*Builtin[T]) Unmarshal

func (b *Builtin[T]) Unmarshal(ctx UnmarshalContext) error

type BuiltinUnmarshalerType

type BuiltinUnmarshalerType interface {
	string | *url.URL | int | net.IP | time.Duration | bool | int32 | uint32 | uint64 | float64 | float32
}

A set of types supported by the builtin unmarshaler.

type Helper

type Helper interface {
	Arg
	Parsed(ParseAttempt)
	Helping() bool
	DoHelp(PrintHelpOpts)
	SetHelping()
}

type Input

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

type Metavar

type Metavar interface {
	Metavar() string
}

A Metavar is an Arg that has a name. This is used for example with positional arguments that can't derive an obvious name from their matching forms.

type ParseAttempt

type ParseAttempt struct {
	Arg     Arg
	Matched bool
}

type ParseContext

type ParseContext interface {
	NumArgs() int
	Pop() (string, bool)
	Unmarshal(Unmarshaler) bool
	UnmarshalArg(u Unmarshaler, arg string) bool
	// Whether "--" has been given.
	PositionalOnly() bool
	PeekArgs() []string
}

type Parser

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

A parser for a sequence of strings.

func NewParser

func NewParser() *Parser

Creates a new Parser bound to the system-level arguments.

func NewParserNoArgs

func NewParserNoArgs() *Parser

func (*Parser) DoHelpIfHelping

func (p *Parser) DoHelpIfHelping()

func (*Parser) DoHelpIfHelpingOpts

func (p *Parser) DoHelpIfHelpingOpts(opts PrintHelpOpts)

func (*Parser) Err

func (p *Parser) Err() error

Returns any error the Parser has encountered. Usually this is the first error and blocks further parsing until it's convenient to handle it.

func (*Parser) Fail

func (p *Parser) Fail() error

Return existing Parser error, or set one based on how many arguments remain.

func (*Parser) FailIfArgsRemain

func (p *Parser) FailIfArgsRemain()

This asserts that no arguments remain, and if they do sets an appropriate error. You would call this when you're ready to start actual work after parsing, and then check Parser.Ok().

func (*Parser) Ok

func (p *Parser) Ok() bool

Returns false if there's an error, or help has been issued. You would normally then return Parser.Err(), which may be nil.

func (*Parser) Parse

func (p *Parser) Parse(arg Arg) (matched bool)

Parse the given parameter, if we're in the right state. Returns true if it matched, and sets an error if it matched and failed to unmarshal.

func (*Parser) ParseAny

func (p *Parser) ParseAny(arg ...Arg) bool

func (*Parser) PopAll

func (p *Parser) PopAll() (all []string)

Removes and returns all remaining unused arguments. This might be used to pass handling on to something else, or to process the rest of the arguments manually.

func (*Parser) SetArgs

func (p *Parser) SetArgs(args ...string)

func (*Parser) SetDefault

func (p *Parser) SetDefault(u Unmarshaler, args ...string) bool

Applies the given arguments through the unmarshaller. Returns false if an error occurred. TODO: This doesn't look completed.

func (*Parser) SetError

func (p *Parser) SetError(err error)

func (*Parser) SetHelper

func (p *Parser) SetHelper(helper Helper)

func (*Parser) SetHelping

func (p *Parser) SetHelping()

type PrintHelpOpts

type PrintHelpOpts struct {
	// Don't print the usage string which includes the program basename. Helpful for testing or
	// temporary binaries.
	NoPrintUsage bool
}

type UnmarshalContext

type UnmarshalContext interface {
	Pop() (string, error)
	// Value was specifically linked to this context, such as --like=this.
	HaveExplicitValue() bool
}

type Unmarshaler

type Unmarshaler interface {
	Unmarshal(ctx UnmarshalContext) error
	ArgTypes() []string
}

func AppendSlice

func AppendSlice[T any](s *[]T, uc func(*T) Unmarshaler) Unmarshaler

func BuiltinOptionUnmarshaler

func BuiltinOptionUnmarshaler[V BuiltinUnmarshalerType](o *g.Option[V]) Unmarshaler

func BuiltinUnmarshaler

func BuiltinUnmarshaler[T BuiltinUnmarshalerType](t *T) Unmarshaler

An unmarshaler for any of the types in the BuiltinUnmarshalerType type set.

func BuiltinUnmarshalerFromAny

func BuiltinUnmarshalerFromAny(t any) Unmarshaler

Returns an unmarshaler for a builtin type. t must be a pointer to a type in the BuiltinUnmarshalerType type set.

func OptionUnmarshaler

func OptionUnmarshaler[V any](o *g.Option[V], vu func(*V) Unmarshaler) Unmarshaler

func String

func String(s *string) Unmarshaler

func TextUnmarshaler

func TextUnmarshaler(tu encoding.TextUnmarshaler) Unmarshaler

type UnmarshalerValuer

type UnmarshalerValuer interface {
	Value() any
}