bargle

package module
v0.0.0-...-4f27390 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 14, 2022 License: MPL-2.0 Imports: 14 Imported by: 4

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.

Image containing Bargle

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewFlag 

func NewFlag(target any) *flagMaker

func NewUnaryOption 

func NewUnaryOption(u UnaryUnmarshaler) *unaryOptionMaker

func SetUnaryDefault 

func SetUnaryDefault(p Param, s string)

Types

type AfterParseParamFunc 

type AfterParseParamFunc func(ctx Context) error

type Args 

type Args interface {
	Push(string)
	Pop() string
	Len() int
	Clone() Args
}

func NewArgs 

func NewArgs(ss []string) Args

type BuiltinUnaryUnmarshaler 

type BuiltinUnaryUnmarshaler[T builtinUnaryUnmarshalTarget] struct{}

type Choice 

type Choice[T any] struct {
	Choices map[string]T
	// contains filtered or unexported fields
}

func NewChoice 

func NewChoice[T any](choices map[string]T) *Choice[T]

func (Choice[T]) Add 

func (me Choice[T]) Add(name string, value T)

func (Choice[T]) Get 

func (me Choice[T]) Get(key string) T

func (Choice[T]) Matching 

func (me Choice[T]) Matching() bool

func (Choice[T]) TargetHelp 

func (me Choice[T]) TargetHelp() string

func (*Choice[T]) UnaryUnmarshal 

func (me *Choice[T]) UnaryUnmarshal(choice string) error

func (Choice[T]) Value 

func (me Choice[T]) Value() T

type Choices 

type Choices[T any] map[string]T

type Command 

type Command struct {
	// Parameters that can be parsed as matched.
	Options []Param
	// Parameters that are parsed in order.
	Positionals []Param
	// A function executed after this command is parsed. Parsing is not yet complete, so any actions should be deferred
	// from this callback.
	AfterParseFunc AfterParseParamFunc
	// Action taken if no subcommand is invoked. If there are subcommands, and none is chosen and there is no
	// DefaultAction, parsing fails.
	DefaultAction func() error
	// A human description of what this command does.
	Desc string
}

A Command represents a collection of parameters and behaviour that are parsed together. Some parameters might themselves be Commands that are parsed recursively.

func FromStruct 

func FromStruct(target interface{}) (cmd Command)

func (Command) AllParams 

func (me Command) AllParams() []Param

func (Command) HasSubcommands 

func (me Command) HasSubcommands() bool

func (Command) Help 

func (cmd Command) Help() (hf commandHelp)

func (Command) Init 

func (me Command) Init() error

type Context 

type Context = *context

func NewContext 

func NewContext(args []string) Context

type ContextFunc 

type ContextFunc func(ctx Context)

type ExitCoder 

type ExitCoder interface {
	ExitCode() int
}

type Flag 

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

A flag is an optional argument that results in a boolean value. It has a negative form, and can parse from a bound value in the same argument (with '=').

func (Flag) Help 

func (f Flag) Help() ParamHelp

func (Flag) Init 

func (f Flag) Init() error

func (Flag) Match 

func (f Flag) Match(args Args) (mr MatchResult)

func (Flag) Parse 

func (f Flag) Parse(args Args) (err error)

func (Flag) Satisfied 

func (Flag) Satisfied() bool

type FormHelper 

type FormHelper interface {
	Help(*ParamHelp)
}

type HelpCommand 

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

func (HelpCommand) AddToCommand 

func (me HelpCommand) AddToCommand(cmd *Command)

func (HelpCommand) Help 

func (h HelpCommand) Help() ParamHelp

func (HelpCommand) Init 

func (h HelpCommand) Init() error

func (HelpCommand) Match 

func (h HelpCommand) Match(args Args) MatchResult

func (HelpCommand) Parse 

func (h HelpCommand) Parse(args Args) error

func (HelpCommand) Satisfied 

func (HelpCommand) Satisfied() bool

type HelpWriter 

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

func (HelpWriter) Indented 

func (me HelpWriter) Indented() HelpWriter

func (HelpWriter) WriteLine 

func (me HelpWriter) WriteLine(s string)

type LongParser 

type LongParser struct {
	Long     string
	CanUnary bool
	// contains filtered or unexported fields
}

func (LongParser) GotValue 

func (me LongParser) GotValue() bool

func (LongParser) Help 

func (me LongParser) Help(f *ParamHelp)

func (*LongParser) Match 

func (me *LongParser) Match(args Args) bool

type Main 

type Main struct {
	OnError func(err error)

	Command
	NoDefaultHelpSubcommand bool
	// contains filtered or unexported fields
}

func (*Main) Defer 

func (me *Main) Defer(f func())

func (*Main) Run 

func (me *Main) Run()

Runs the command then exits with an appropriate exit code. There is no return from this function.

type MatchResult 

type MatchResult interface {
	// Could this be represented by a nil interface?
	Matched() generics.Option[string]
	Args() Args
	Parse(args Args) error
	// Should the caller of Matcher.Match remember this?
	Param() Param
}

type Matcher 

type Matcher interface {
	// Should this allow a nil return for no match?
	Match(args Args) MatchResult
}

type Option 

type Option[T any] struct {
	TargetOk         *bool
	TargetValue      *T
	ValueUnmarshaler UnaryUnmarshaler
}

func NewOption 

func NewOption[T any](target *generics.Option[T], u UnaryUnmarshaler) Option[T]

func (Option[T]) Matching 

func (me Option[T]) Matching() bool

func (Option[T]) TargetHelp 

func (o Option[T]) TargetHelp() string

func (Option[T]) UnaryUnmarshal 

func (o Option[T]) UnaryUnmarshal(s string) error

func (Option[T]) Value 

func (me Option[T]) Value() generics.Option[T]

type Param 

type Param interface {
	Satisfied() bool
	Matcher
	// This should not be used directly, normally, and instead Parse is called on a match result.
	// This is used for parsing defaults for example. TODO: Move to Unmarshaler Value and don't
	// expose here?
	Parse(args Args) error
	Subcommand() generics.Option[Command]
	Help() ParamHelp
	AfterParse(ctx Context) error
	Init() error
}

type ParamHelp 

type ParamHelp struct {
	Forms       []string
	Description string
	Values      string
	Default     string
	Options     []ParamHelp
	Subcommand  commandHelp
}

func (ParamHelp) Print 

func (ph ParamHelp) Print(w HelpWriter)

func (ParamHelp) Write 

func (me ParamHelp) Write(w HelpWriter)

type Parser 

type Parser interface {
	Parse(ctx Context) error
}

type Positional 

type Positional struct {
	Value UnaryUnmarshaler
	Name  string
	Desc  string

	AfterParseFunc AfterParseParamFunc
	// contains filtered or unexported fields
}

func NewPositional 

func NewPositional(u UnaryUnmarshaler) *Positional

func (*Positional) AfterParse 

func (me *Positional) AfterParse(ctx Context) error

func (*Positional) Help 

func (me *Positional) Help() ParamHelp

func (*Positional) Init 

func (me *Positional) Init() error

func (*Positional) Match 

func (me *Positional) Match(args Args) MatchResult

func (*Positional) Parse 

func (me *Positional) Parse(args Args) error

func (*Positional) Satisfied 

func (me *Positional) Satisfied() bool

type ShortParser 

type ShortParser struct {
	Short    rune
	CanUnary bool
	Prefix   rune
	// contains filtered or unexported fields
}

func (ShortParser) GotValue 

func (me ShortParser) GotValue() bool

func (ShortParser) Help 

func (me ShortParser) Help(f *ParamHelp)

func (*ShortParser) Match 

func (me *ShortParser) Match(args Args) bool

type Slice 

type Slice[T any] struct {
	Unmarshaler UnaryUnmarshaler
	// contains filtered or unexported fields
}

func (Slice[T]) TargetHelp 

func (s2 Slice[T]) TargetHelp() string

func (Slice[T]) UnaryUnmarshal 

func (sl Slice[T]) UnaryUnmarshal(s string) error

type String 

type String struct {
	Target *string
	Ok     bool
}

func NewString 

func NewString() *String

func (*String) Matching 

func (me *String) Matching() bool

func (String) TargetHelp 

func (s2 String) TargetHelp() string

func (*String) UnaryUnmarshal 

func (me *String) UnaryUnmarshal(arg string) error

func (String) Value 

func (me String) Value() string

type Subcommand 

type Subcommand struct {
	Name string
	Command
	// contains filtered or unexported fields
}

func (Subcommand) Help 

func (me Subcommand) Help() ParamHelp

func (Subcommand) Match 

func (me Subcommand) Match(args Args) MatchResult

func (Subcommand) Parse 

func (me Subcommand) Parse(args Args) error

func (Subcommand) Satisfied 

func (Subcommand) Satisfied() bool

func (Subcommand) Subcommand 

func (me Subcommand) Subcommand() generics.Option[Command]

type Switch 

type Switch struct {
	Longs          []string
	Shorts         []rune
	Desc           string
	AfterParseFunc AfterParseParamFunc
	// contains filtered or unexported fields
}

A switch is an option that takes no values and has no negative form.

func (Switch) AfterParse 

func (f Switch) AfterParse(ctx Context) error

func (Switch) Help 

func (f Switch) Help() ParamHelp

func (Switch) Init 

func (f Switch) Init() error

func (Switch) Match 

func (f Switch) Match(args Args) (mr MatchResult)

func (Switch) Parse 

func (f Switch) Parse(args Args) error

func (Switch) Satisfied 

func (Switch) Satisfied() bool

type TargetHelper 

type TargetHelper interface {
	TargetHelp() string
}

type UnaryOption 

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

func (*UnaryOption) AfterParse 

func (me *UnaryOption) AfterParse(Context) error

func (*UnaryOption) Help 

func (me *UnaryOption) Help() ParamHelp

func (*UnaryOption) Init 

func (me *UnaryOption) Init() error

func (*UnaryOption) Match 

func (me *UnaryOption) Match(args Args) MatchResult

func (*UnaryOption) Parse 

func (me *UnaryOption) Parse(args Args) error

func (*UnaryOption) Satisfied 

func (me *UnaryOption) Satisfied() bool

type UnarySwitch 

type UnarySwitch interface {
	GotValue() bool
}

type UnaryUnmarshaler 

type UnaryUnmarshaler interface {
	UnaryUnmarshal(s string) error
	//CurrentValue() string
	TargetHelp() string
	Matching() bool
}

func AutoUnmarshaler 

func AutoUnmarshaler[T any](t *T) (u UnaryUnmarshaler)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.