cli

README

CLI

This Go module provides a simple way to register program flags, options, and environment variables.

Documentation

Overview

Package cli provides a simple way to register program flags, options, and environment variables.

Index

• Variables
• func ApplyEnvFileIfExists() error
• type Arg
• type CLI
  • func Create(name string, description string, usage string, version string, options []Opt, ...) *CLI
  • func CreateCLI(name string, description string, usage string, version string, options []Opt, ...) (*CLI, error)
  • func New(name string, description string, usage string, version string, options []Opt, ...) *CLI
  • func NewCLI(name string, description string, usage string, version string, options []Opt, ...) (*CLI, error)
  • func (cli *CLI) Parse() *CLI
  • func (cli *CLI) ParseArgs(arguments []string) error
  • func (cli *CLI) ReadEnv() error
  • func (cli *CLI) Usage() string
• type CLIOpt
  • func GetEnv(getEnv func(key string) string) CLIOpt
  • func UseFlagSet(flagSet ...*flag.FlagSet) CLIOpt
  • func WriteErr(w io.Writer) CLIOpt
  • func WriteOut(w io.Writer) CLIOpt
• type Opt
  • func (o Opt) String() string

Variables

var (
	// ErrMissingArgs is returned when required arguments are missing when parsing program args.
	ErrMissingArgs = errors.New("required arguments were not provided")
	// ErrInvalidArg is returned when a provided program argument was invalid.
	ErrInvalidArg = errors.New("invalid argument")
	// ErrInvalidEnv is returned when the value of an environment variable was invalid.
	ErrInvalidEnv = errors.New("invalid environment variable value")
)

Functions

func ApplyEnvFileIfExists

func ApplyEnvFileIfExists() error

ApplyEnvFileIfExists looks in the working directory for a ".env" file. If present, it will apply all lines in the format key=value with os.Setenv(key, value). Lines where the first non-whitespace rune (as defined by Unicode) is # will be treated as comments and skipped.

Lines which cannot be parsed into a key-value pair are ignored.

An error is returned only when there is an error reading the file.

Types

type Arg

type Arg struct {
	// Name of the program argument.
	Name string
	// Desc description the argument.
	Desc string
	// Ptr is a pointer to the value to set. Supported types are string, int,
	// bool, and flag.Value.
	Ptr any
}

type CLI

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

func Create

func Create(
	name string,
	description string,
	usage string,
	version string,
	options []Opt,
	arguments []Arg,
	cliOpts ...CLIOpt,
) *CLI

Create has the same function as CreateCLI but on error prints the problem and then exits.

func CreateCLI

func CreateCLI(
	name string,
	description string,
	usage string,
	version string,
	options []Opt,
	arguments []Arg,
	cliOpts ...CLIOpt,
) (*CLI, error)

CreateCLI create a new CLI, parses environment and program flags all at once. This is equivalent to calling NewCLI, [ReadEnv], [Parse]

func New

func New(
	name string,
	description string,
	usage string,
	version string,
	options []Opt,
	arguments []Arg,
	cliOpts ...CLIOpt,
) *CLI

New has the same function as NewCLI, but on error it prints the problem and then exits.

func NewCLI

func NewCLI(
	name string,
	description string,
	usage string,
	version string,
	options []Opt,
	arguments []Arg,
	cliOptions ...CLIOpt,
) (*CLI, error)

NewCLI registers environment variables and program flags according to the options and handles creation of a usage func. Make sure to call cli.ReadEnv to read the environment variables and Parse to parse the program flags.

func (*CLI) Parse

func (cli *CLI) Parse() *CLI

Parse reads the program flags into the variables pointed to in the options.

func (*CLI) ParseArgs

func (cli *CLI) ParseArgs(arguments []string) error

Parse parses flag definitions from the argument list, which should not include the command name. The return value will be flag.ErrHelp if -help or -h were set but not defined. ErrMissingArgs is returned if there are missing required args.

func (*CLI) ReadEnv

func (cli *CLI) ReadEnv() error

ReadEnv reads any non-empty environemnt variables into the values pointed to

func (*CLI) Usage

func (cli *CLI) Usage() string

Usage returns the usage of the CLI

type CLIOpt

type CLIOpt func(c *CLI)

CLIOpt is an option that is applied to a CLI to configure behavior such as where to direct output or get environment variables.

func GetEnv

func GetEnv(getEnv func(key string) string) CLIOpt

GetEnv configures a CLI to get environment variables using the provided func.

func UseFlagSet

func UseFlagSet(flagSet ...*flag.FlagSet) CLIOpt

UseFlagSet will create the CLI using the provided FlagSet or will create a new one to use if none is provided. This func will panic if more than one FlagSet is provided.

func WriteErr

func WriteErr(w io.Writer) CLIOpt

WriteErr configures a CLI to write error to the provided writer.

func WriteOut

func WriteOut(w io.Writer) CLIOpt

WriteOut configures a CLI to write output to the provided writer.

type Opt

type Opt struct {
	// Name of the program flag. If empty, no program flag is registered.
	Name string
	// Desc description of option.
	Desc string
	// Env is an optional environment variable to register.
	Env string
	// Ptr is a pointer to the value to set. Supported types are string, int,
	// bool, and flag.Value. If the value being pointed to is non-zero it will be
	// used as the default value for the option.
	Ptr any
	// DocumentationOnly is set to document environment variables which are not
	// parsed through this package. It is permitted only on Opts where both Name
	// and Ptr fields are unspecified.
	DocumentationOnly bool
	// TypeName is an optional hint to the user what the type of the option is.
	// If unset the type name pointed-to by Ptr will be used.
	TypeName string
	// contains filtered or unexported fields
}

Opt is a program option configurable by user input.

func (Opt) String

func (o Opt) String() string