cmd

Documentation

Index

• Variables
• func CheckEmpty(args []string) error
• func FormatSmart(value interface{}) ([]byte, error)
• func FormatYaml(value interface{}) ([]byte, error)
• func Main(c Command, ctx *Context, args []string) int
• func ParseArgs(c Command, f *gnuflag.FlagSet, args []string) error
• func ZeroOrOneArgs(args []string) (string, error)
• type Command
• type CommandBase
  • func (c *CommandBase) Init(args []string) error
  • func (c *CommandBase) SetFlags(f *gnuflag.FlagSet)
• type Context
  • func DefaultContext() *Context
  • func (ctx *Context) AbsPath(path string) string
• type FileVar
  • func (f *FileVar) Read(ctx *Context) ([]byte, error)
  • func (f *FileVar) Set(v string) error
  • func (f *FileVar) String() string
• type Formatter
• type Info
  • func (i *Info) Help(f *gnuflag.FlagSet) []byte
• type Log
  • func (l *Log) AddFlags(f *gnuflag.FlagSet)
  • func (l *Log) Start(ctx *Context) (err error)
• type MissingCallback
• type Output
  • func (c *Output) AddFlags(f *gnuflag.FlagSet, defaultFormatter string, formatters map[string]Formatter)
  • func (c *Output) Name() string
  • func (c *Output) Write(ctx *Context, value interface{}) (err error)
• type SuperCommand
  • func NewSuperCommand(params SuperCommandParams) *SuperCommand
  • func (c *SuperCommand) AddHelpTopic(name, short, long string)
  • func (c *SuperCommand) AddHelpTopicCallback(name, short string, longCallback func() string)
  • func (c *SuperCommand) Info() *Info
  • func (c *SuperCommand) Init(args []string) error
  • func (c *SuperCommand) Register(subcmd Command)
  • func (c *SuperCommand) Run(ctx *Context) error
  • func (c *SuperCommand) SetFlags(f *gnuflag.FlagSet)
• type SuperCommandParams
• type UnrecognizedCommand
  • func (e *UnrecognizedCommand) Error() string
• type VersionCommand
  • func (v *VersionCommand) Info() *Info
  • func (v *VersionCommand) Run(ctxt *Context) error
  • func (v *VersionCommand) SetFlags(f *gnuflag.FlagSet)

Variables

var DefaultFormatters = map[string]Formatter{
	"smart": FormatSmart,
	"yaml":  FormatYaml,
	"json":  FormatJson,
}

DefaultFormatters holds the formatters that can be specified with the --format flag.

var ErrNoPath = errors.New("path not set")

var ErrSilent = errors.New("cmd: error out silently")

ErrSilent can be returned from Run to signal that Main should exit with code 1 without producing error output.

var FormatJson = json.Marshal

FormatJson marshals value to a json-formatted []byte.

Functions

func CheckEmpty

func CheckEmpty(args []string) error

CheckEmpty is a utility function that returns an error if args is not empty.

func FormatSmart

func FormatSmart(value interface{}) ([]byte, error)

FormatSmart marshals value into a []byte according to the following rules:

• string: untouched
• bool: converted to `True` or `False` (to match pyjuju)
• int or float: converted to sensible strings
• []string: joined by `\n`s into a single string
• anything else: delegate to FormatYaml

func FormatYaml

func FormatYaml(value interface{}) ([]byte, error)

FormatYaml marshals value to a yaml-formatted []byte, unless value is nil.

func Main

func Main(c Command, ctx *Context, args []string) int

Main runs the given Command in the supplied Context with the given arguments, which should not include the command name. It returns a code suitable for passing to os.Exit.

func ParseArgs

func ParseArgs(c Command, f *gnuflag.FlagSet, args []string) error

ParseArgs encapsulate the parsing of the args so this function can be called from the testing module too.

func ZeroOrOneArgs

func ZeroOrOneArgs(args []string) (string, error)

ZeroOrOneArgs checks to see that there are zero or one args, and returns the value of the arg if provided, or the empty string if not.

Types

type Command

type Command interface {
	// Info returns information about the Command.
	Info() *Info

	// SetFlags adds command specific flags to the flag set.
	SetFlags(f *gnuflag.FlagSet)

	// Init initializes the Command before running.
	Init(args []string) error

	// Run will execute the Command as directed by the options and positional
	// arguments passed to Init.
	Run(ctx *Context) error
}

Command is implemented by types that interpret command-line arguments.

type CommandBase

type CommandBase struct{}

CommandBase provides the default implementation for SetFlags, Init, and Help.

func (*CommandBase) Init

func (c *CommandBase) Init(args []string) error

Init in the simplest case makes sure there are no args.

func (*CommandBase) SetFlags

func (c *CommandBase) SetFlags(f *gnuflag.FlagSet)

SetFlags does nothing in the simplest case.

type Context

type Context struct {
	Dir    string
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

Context represents the run context of a Command. Command implementations should interpret file names relative to Dir (see AbsPath below), and print output and errors to Stdout and Stderr respectively.

func DefaultContext

func DefaultContext() *Context

DefaultContext returns a Context suitable for use in non-hosted situations.

func (*Context) AbsPath

func (ctx *Context) AbsPath(path string) string

AbsPath returns an absolute representation of path, with relative paths interpreted as relative to ctx.Dir.

type FileVar

type FileVar struct {
	Path string
}

FileVar represents a path to a file.

func (*FileVar) Read

func (f *FileVar) Read(ctx *Context) ([]byte, error)

Read returns the contents of the file.

func (*FileVar) Set

func (f *FileVar) Set(v string) error

Set stores the chosen path name in f.Path.

func (*FileVar) String

func (f *FileVar) String() string

String returns the path to the file.

type Formatter

type Formatter func(value interface{}) ([]byte, error)

Formatter converts an arbitrary object into a []byte.

type Info

type Info struct {
	// Name is the Command's name.
	Name string

	// Args describes the command's expected positional arguments.
	Args string

	// Purpose is a short explanation of the Command's purpose.
	Purpose string

	// Doc is the long documentation for the Command.
	Doc string

	// Aliases are other names for the Command.
	Aliases []string
}

Info holds some of the usage documentation of a Command.

func (*Info) Help

func (i *Info) Help(f *gnuflag.FlagSet) []byte

Help renders i's content, along with documentation for any flags defined in f. It calls f.SetOutput(ioutil.Discard).

type Log

type Log struct {
	Path    string
	Verbose bool
	Debug   bool
	Config  string
}

Log supplies the necessary functionality for Commands that wish to set up logging.

func (*Log) AddFlags

func (l *Log) AddFlags(f *gnuflag.FlagSet)

AddFlags adds appropriate flags to f.

func (*Log) Start

func (l *Log) Start(ctx *Context) (err error)

Start starts logging using the given Context.

type MissingCallback

type MissingCallback func(ctx *Context, subcommand string, args []string) error

MissingCallback defines a function that will be used by the SuperCommand if the requested subcommand isn't found.

type Output

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

Output is responsible for interpreting output-related command line flags and writing a value to a file or to stdout as directed.

func (*Output) AddFlags

func (c *Output) AddFlags(f *gnuflag.FlagSet, defaultFormatter string, formatters map[string]Formatter)

AddFlags injects the --format and --output command line flags into f.

func (*Output) Name

func (c *Output) Name() string

func (*Output) Write

func (c *Output) Write(ctx *Context, value interface{}) (err error)

Write formats and outputs the value as directed by the --format and --output command line flags.

type SuperCommand

type SuperCommand struct {
	CommandBase
	Name    string
	Purpose string
	Doc     string
	Log     *Log
	// contains filtered or unexported fields
}

SuperCommand is a Command that selects a subcommand and assumes its properties; any command line arguments that were not used in selecting the subcommand are passed down to it, and to Run a SuperCommand is to run its selected subcommand.

func NewSuperCommand

func NewSuperCommand(params SuperCommandParams) *SuperCommand

NewSuperCommand creates and initializes a new `SuperCommand`, and returns the fully initialized structure.

func (*SuperCommand) AddHelpTopic

func (c *SuperCommand) AddHelpTopic(name, short, long string)

AddHelpTopic adds a new help topic with the description being the short param, and the full text being the long param. The description is shown in 'help topics', and the full text is shown when the command 'help <name>' is called.

func (*SuperCommand) AddHelpTopicCallback

func (c *SuperCommand) AddHelpTopicCallback(name, short string, longCallback func() string)

AddHelpTopicCallback adds a new help topic with the description being the short param, and the full text being defined by the callback function.

func (*SuperCommand) Info

func (c *SuperCommand) Info() *Info

Info returns a description of the currently selected subcommand, or of the SuperCommand itself if no subcommand has been specified.

func (*SuperCommand) Init

func (c *SuperCommand) Init(args []string) error

Init initializes the command for running.

func (*SuperCommand) Register

func (c *SuperCommand) Register(subcmd Command)

Register makes a subcommand available for use on the command line. The command will be available via its own name, and via any supplied aliases.

func (*SuperCommand) Run

func (c *SuperCommand) Run(ctx *Context) error

Run executes the subcommand that was selected in Init.

func (*SuperCommand) SetFlags

func (c *SuperCommand) SetFlags(f *gnuflag.FlagSet)

SetFlags adds the options that apply to all commands, particularly those due to logging.

type SuperCommandParams

type SuperCommandParams struct {
	Name            string
	Purpose         string
	Doc             string
	Log             *Log
	MissingCallback MissingCallback
}

SuperCommandParams provides a way to have default parameter to the `NewSuperCommand` call.

type UnrecognizedCommand

type UnrecognizedCommand struct {
	Name string
}

func (*UnrecognizedCommand) Error

func (e *UnrecognizedCommand) Error() string

type VersionCommand

type VersionCommand struct {
	CommandBase
	// contains filtered or unexported fields
}

VersionCommand is a cmd.Command that prints the current version.

func (*VersionCommand) Info

func (v *VersionCommand) Info() *Info

func (*VersionCommand) Run

func (v *VersionCommand) Run(ctxt *Context) error

func (*VersionCommand) SetFlags

func (v *VersionCommand) SetFlags(f *gnuflag.FlagSet)