cli

package module
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2025 License: MIT Imports: 17 Imported by: 1

README

cli

A Go package for building CLIs.

Installation

go get github.com/broothie/cli@latest

Documentation

https://pkg.go.dev/github.com/broothie/cli

To Do

  • Audit bare err returns
    • Two types of errors: config and parse
  • Tab completion
  • Allow variadic arguments
  • Allow slice and map based flags?

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	NotACommandContextError = errors.New("not a command context")
	FlagNotFoundError       = errors.New("flag not found")
	ArgumentNotFoundError   = errors.New("argument not found")
)
View Source 
var (
	InvalidFlagError        = errors.New("invalid flag")
	MissingFlagValueError   = errors.New("missing flag value")
	TooManyArgumentsError   = errors.New("too many arguments")
	FlagGroupWithEqualError = errors.New("short flags with equal signs cannot be grouped")
)
View Source 
var ArgumentMissingValueError = errors.New("argument missing value")
View Source 
var NotParseableError = errors.New("type not parseable")

Functions

func AddAlias 

func AddAlias(alias string) option.Func[*Command]

AddAlias adds an alias to the command.

func AddArg 

func AddArg(name, description string, options ...option.Option[*Argument]) option.Func[*Command]

AddArg adds an argument to the command.

Example 
command, _ := NewCommand("server", "An http server.",
	AddArg("port", "Port to run server on", SetArgParser(IntParser)),
)

command.renderHelp(os.Stdout)

Output:

server: An http server.

Usage:
  server <port>

Arguments:
  <port>  Port to run server on  (type: int)

func AddFlag 

func AddFlag(name, description string, options ...option.Option[*Flag]) option.Func[*Command]

AddFlag adds a flag to the command.

Example 
command, _ := NewCommand("server", "An http server.",
	AddFlag("port", "Port to run server on",
		AddFlagShort('p'),
		SetFlagDefault(3000),
	),
)

command.renderHelp(os.Stdout)

Output:

server: An http server.

Usage:
  server [flags]

Flags:
  --port  -p  Port to run server on  (type: int, default: "3000")

func AddFlagAlias 

func AddFlagAlias(alias string) option.Func[*Flag]

AddFlagAlias adds an alias to the flag.

func AddFlagShort 

func AddFlagShort(short rune) option.Func[*Flag]

AddFlagShort adds a short flag to the flag.

func AddHelpFlag 

func AddHelpFlag(options ...option.Option[*Flag]) option.Func[*Command]

AddHelpFlag adds a help flag to the command.

Example 
command, _ := NewCommand("server", "An http server.",
	AddHelpFlag(AddFlagShort('h')),
)

command.renderHelp(os.Stdout)

Output:

server: An http server.

Usage:
  server [flags]

Flags:
  --help  -h  Print help.  (type: bool, default: "false")

func AddSubCmd 

func AddSubCmd(name, description string, options ...option.Option[*Command]) option.Func[*Command]

AddSubCmd adds a subcommand to the command.

Example 
command, _ := NewCommand("server", "An http server.",
	AddSubCmd("start", "Start the server"),
)

command.renderHelp(os.Stdout)

Output:

server: An http server.

Usage:
  server [sub-commands]

Sub-commands:
  start: Start the server

func AddVersionFlag 

func AddVersionFlag(options ...option.Option[*Flag]) option.Func[*Command]
Example 
command, _ := NewCommand("server", "An http server.",
	SetVersion("v0.1.0"),
	AddVersionFlag(AddFlagShort('V')),
)

command.renderHelp(os.Stdout)

Output:

server v0.1.0: An http server.

Usage:
  server [flags]

Flags:
  --version  -V  Print version.  (type: bool, default: "false")

func ArgValue 

func ArgValue[T any](ctx context.Context, name string) (T, error)

func BoolParser 

func BoolParser(s string) (bool, error)

BoolParser parses a string into a bool.

func DurationParser 

func DurationParser(s string) (time.Duration, error)

DurationParser parses a string into a time.Duration.

func FlagValue 

func FlagValue[T any](ctx context.Context, name string) (T, error)

func Float64Parser 

func Float64Parser(s string) (float64, error)

Float64Parser parses a string into a float64.

func IntParser 

func IntParser(s string) (int, error)

IntParser parses a string into an int.

func Run 

func Run(name, description string, options ...option.Option[*Command])

Run creates and runs a command using os.Args as the arguments and context.Background as the context.

func SetArgDefault added in v0.1.2 

func SetArgDefault[T Parseable](defaultValue T) option.Func[*Argument]

SetArgDefault sets the default value of the argument.

func SetArgParser 

func SetArgParser[T any](parser ArgParser[T]) option.Func[*Argument]

SetArgParser sets the parser of the argument.

func SetFlagDefault 

func SetFlagDefault[T Parseable](defaultValue T) option.Func[*Flag]

SetFlagDefault sets the default value of the flag.

func SetFlagDefaultAndParser 

func SetFlagDefaultAndParser[T any](defaultValue T, argParser ArgParser[T]) option.Func[*Flag]

SetFlagDefaultAndParser sets the default value and parser of the flag.

func SetFlagIsHidden 

func SetFlagIsHidden(isHidden bool) option.Func[*Flag]

SetFlagIsHidden controls whether the flag is hidden from the help message.

func SetFlagIsInherited 

func SetFlagIsInherited(isInherited bool) option.Func[*Flag]

SetFlagIsInherited controls whether the flag is inherited by child commands.

func SetHandler 

func SetHandler(handler Handler) option.Func[*Command]

SetHandler sets the handler of the command.

Example 
command, _ := NewCommand("server", "An http server.",
	SetHandler(func(ctx context.Context) error {
		fmt.Println("running server")
		return nil
	}),
)

command.Run(context.Background(), nil)

Output:

running server

func SetVersion 

func SetVersion(version string) option.Func[*Command]

SetVersion sets the version of the command.

Example 
command, _ := NewCommand("server", "An http server.",
	SetVersion("v0.1.0"),
)

command.renderHelp(os.Stdout)

Output:

server v0.1.0: An http server.

Usage:
  server

func StringParser 

func StringParser(s string) (string, error)

StringParser parses a string into a string.

func TimeParser 

func TimeParser(s string) (time.Time, error)

TimeParser parses a string into a time.Time.

func URLParser 

func URLParser(s string) (*url.URL, error)

URLParser parses a string into a *url.URL.

Types

type ArgParser 

type ArgParser[T any] func(string) (T, error)

ArgParser is a function that parses a string into a value of type T.

func NewArgParser 

func NewArgParser[T any](f ArgParser[T]) ArgParser[T]

NewArgParser creates a new ArgParser.

func TimeLayoutParser 

func TimeLayoutParser(timeLayout string) ArgParser[time.Time]

TimeLayoutParser parses a string into a time.Time using a specific time layout.

func (ArgParser[T]) Parse 

func (p ArgParser[T]) Parse(s string) (any, error)

func (ArgParser[T]) Type 

func (ArgParser[T]) Type() any

type Argument 

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

type Command 

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

func NewCommand 

func NewCommand(name, description string, options ...option.Option[*Command]) (*Command, error)

NewCommand creates a new command.

Example 
command, _ := NewCommand("server", "An http server.",
	AddHelpFlag(AddFlagShort('h')),
	SetVersion("v0.1.0"),
	AddVersionFlag(AddFlagShort('V')),
	AddFlag("port", "Port to run server on.",
		SetFlagDefault(3000),
		AddFlagShort('p'),
	),
	AddFlag("auth-required", "Whether to require authentication.",
		SetFlagDefault(true),
	),
	AddSubCmd("proxy", "Proxy requests to another server.",
		AddArg("target", "Target server to proxy requests to.",
			SetArgParser(URLParser),
		),
	),
)

command.renderHelp(os.Stdout)

Output:

server v0.1.0: An http server.

Usage:
  server [flags] [sub-commands]

Sub-commands:
  proxy: Proxy requests to another server.

Flags:
  --help           -h  Print help.                         (type: bool, default: "false")
  --version        -V  Print version.                      (type: bool, default: "false")
  --port           -p  Port to run server on.              (type: int, default: "3000")
  --auth-required      Whether to require authentication.  (type: bool, default: "true")

func (*Command) Run 

func (c *Command) Run(ctx context.Context, rawArgs []string) error

Run runs the command.

type Flag 

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

type Handler 

type Handler func(ctx context.Context) error

type Parseable 

type Parseable interface {
	string | bool | int | float64 | time.Time | time.Duration | *url.URL
}

Parseable is a type that can be parsed from a string.

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.