README
¶
Star
Star is an opinionated Go library for writing CLI applications.
Goals
- Make testing commands easy.
- Make working with parameters (args and flags) easy.
- No parsing or nullable flag/arg noise in the applications main flow.
- Separate the way a parameter is passed (via flag or positionally) from its use.
- Eliminate the need to use shared package level state.
Design
Commands in Star are just metadata around functions. Utilities are provided to create "directory" or "parent" commands which are common in modern CLI apps. Parent commands take 1 argument and use it to lookup the name of a child command.
Command functions are of type func(*star.Context) error
The Context has references to std{in, out, err}, as well as methods to access any parameters the command is expecting.
Commands will never be executed without their requested parameters.
Retreiving a parameter from the star.Context will always succeed or always panic, regardless of the programs runtime input.
So panicing when accessing parameters is always a logic error, never a user error.
If the user forgets a parameter it will not panic and instead return an error without running any of the application logic.
Documentation
¶
Overview ¶
package star is for creating command line tools
Index ¶
- func Execute(ctx context.Context, c *Command, env Env, calledAs string, args []string) error
- func M[T any](ctx *Context, x string) (T, bool)
- func Main(name string, c *Command, opts ...MainOpt)
- func V[T any](ctx *Context, x string) T
- type Command
- type Context
- func (c *Context) Bytes(x string) []byte
- func (c *Context) Int64(x string) int64
- func (c *Context) MaybeInt64(x string) (int64, bool)
- func (c *Context) MaybeString(x string) (string, bool)
- func (c *Context) MaybeUint64(x string) (uint64, bool)
- func (c *Context) String(x string) string
- func (c *Context) StringSlice(x string) []string
- func (c *Context) Time(x string) string
- func (c *Context) Uint64(x string) uint64
- func (c *Context) WithValue(k, v interface{}) *Context
- type Env
- type ExitCodeError
- type Flag
- type Func
- type MainOpt
- type Param
- type Pos
- type Type
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Command ¶
type Command struct {
// Short is a short doc string
Short string
// Pos is a slice of specifications for positional arguments
Pos []Pos
// Flags are the flags the command is expecting
Flags []Flag
// F is the function to run
F Func
}
Command is a Func and associated metadata.
type Context ¶
type Context struct {
context.Context
// In is stdin
In io.Reader
// Out is stdout
Out io.Writer
// Err is stderr
Err io.Writer
CalledAs string
Args []string
// contains filtered or unexported fields
}
Context is passed to Funcs
func (*Context) StringSlice ¶
type Env ¶
Env is the total environment in which the command runs. TODO: add FS interface, and environment variables.
type ExitCodeError ¶
type ExitCodeError interface {
ExitCode() int
}
ExitCodeError is an error which can set an exit code.
type Flag ¶
Flag is a the specification of an argument
func (Flag) WithDefault ¶
type Func ¶
Func is the type of functions which can be run as commands
func PostExec ¶
PostExec returns a function which calls postF after x. PostExec always runs after x, even if x returns an error. x's error is prioritized in the return value
Source Files
Directories