star

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 a library for making command line applications

Index

• func Main(c Command)
• func OSEnv(prefix string) map[string]string
• func ParseFlags(dst map[Symbol][]any, flags []IParam, args []string) (rest []string, err error)
• func ParsePos(dst map[Symbol][]any, params []IParam, args []string) (rest []string, err error)
• func ParseString(x string) (string, error)
• func Ptr[T any](x T) *T
• func Run(ctx context.Context, cmd Command, env map[string]string, calledAs string, ...) error
• type Command
  • func NewDir(md Metadata, children map[Symbol]Command) Command
  • func (c Command) Doc(calledAs string) string
  • func (c Command) HasParam(x Symbol) bool
• type Context
  • func (c Context) Param(x Symbol) (any, bool)
  • func (c Context) Printf(format string, a ...any)
• type IParam
• type Metadata
• type Param
  • func NewString(name Symbol) Param[string]
  • func (p Param[T]) Load(c Context) T
  • func (p Param[T]) LoadAll(c Context) []T
  • func (p Param[T]) LoadOpt(c Context) (T, bool)
• type Symbol

Functions

func Main

func Main(c Command)

Main is a default entrypoint for a Command. e.g.

func main() {
  star.Main(yourCommandHere)
}

func OSEnv

func OSEnv(prefix string) map[string]string

func ParseFlags

func ParseFlags(dst map[Symbol][]any, flags []IParam, args []string) (rest []string, err error)

ParseFlags takes a slice of args, and parses paramaeters in the list of flags. ParseFlags writes values to dst.

func ParsePos

func ParsePos(dst map[Symbol][]any, params []IParam, args []string) (rest []string, err error)

ParsePos parses positional arguments

func ParseString

func ParseString(x string) (string, error)

ParseString is a parser for strings, it is the identity function on strings, and never errors.

func Ptr

func Ptr[T any](x T) *T

func Run

func Run(ctx context.Context, cmd Command, env map[string]string, calledAs string, args []string, stdin *bufio.Reader, stdout *bufio.Writer, stderr *bufio.Writer) error

Types

type Command

type Command struct {
	Flags []IParam
	Pos   []IParam
	F     func(c Context) error
	Metadata
}

func NewDir

func NewDir(md Metadata, children map[Symbol]Command) Command

func (Command) Doc

func (c Command) Doc(calledAs string) string

func (Command) HasParam

func (c Command) HasParam(x Symbol) bool

type Context

type Context struct {
	context.Context
	Params   map[Symbol][]any
	Env      map[string]string
	StdIn    *bufio.Reader
	StdOut   *bufio.Writer
	StdErr   *bufio.Writer
	CalledAs string
	Extra    []string
	// contains filtered or unexported fields
}

Context is the context in which a command is run. It provides parsed parameters, input and output streams, and a go context.Context

func (Context) Param

func (c Context) Param(x Symbol) (any, bool)

func (Context) Printf

func (c Context) Printf(format string, a ...any)

type IParam

type IParam interface {
	// contains filtered or unexported methods
}

type Metadata

type Metadata struct {
	Short string
	// Tags for grouping by category
	Tags []string
}

type Param

type Param[T any] struct {
	// Name identifies the parameter
	Name Symbol
	// Default is used as input to Parse if the parameter was not specified
	Default *string
	// Repeated means the parameter can be specified multiple times
	Repeated bool
	// Parse is called to convert strings
	Parse func(string) (T, error)
}

func NewString

func NewString(name Symbol) Param[string]

func (Param[T]) Load

func (p Param[T]) Load(c Context) T

Load acceses a parameter from the context

func (Param[T]) LoadAll

func (p Param[T]) LoadAll(c Context) []T

LoadAll returns a slice containing every specified value for the flag

func (Param[T]) LoadOpt

func (p Param[T]) LoadOpt(c Context) (T, bool)

LoadOpt acceses an optional parameter from the context

type Symbol

type Symbol string

Symbol is the name of a parameter