cli

Documentation

Overview

Package cli is the krowk command line. Run is the whole entry point, taking its streams and environment as arguments so tests never touch the process.

Index

• Variables
• func Run(args []string, stdout, stderr io.Writer, env func(string) string, isTTY bool) int
• type Arg
• type Catalog
  • func Surface() Catalog
  • func (c Catalog) Find(path []string) (Command, bool)
  • func (c Catalog) Leaves() []Command
• type Command
• type EnvVar
• type Flag

Variables

var Version = "dev"

Version is stamped at build time: -ldflags "-X .../internal/cli.Version=1.2.3". The default is "dev", not a number: an unstamped `go build` is a source build, and calling it one keeps `upgrade` and the update notice honest about it — neither will touch a build that git owns.

Functions

func Run

func Run(args []string, stdout, stderr io.Writer, env func(string) string, isTTY bool) int

Run executes one invocation and returns the process exit code.

Types

type Arg

type Arg struct {
	Name     string `json:"name"`
	Summary  string `json:"summary"`
	Required bool   `json:"required"`
	Repeated bool   `json:"repeated,omitempty"`
}

Arg is one positional. Required and Repeated are separate questions: `push` takes one file or twenty, and needs at least one.

type Catalog

type Catalog struct {
	Name string `json:"name"`
	// Version is stamped at build time, so it is filled in when the catalog is
	// asked for rather than written down here.
	Version     string    `json:"version"`
	Summary     string    `json:"summary"`
	Commands    []Command `json:"commands"`
	GlobalFlags []Flag    `json:"global_flags"`
	Environment []EnvVar  `json:"environment"`
}

Catalog is the whole surface: what krowk is called, what it can do, and what it reads from the environment.

func Surface

func Surface() Catalog

Surface is the catalog as this build of krowk would report it.

func (Catalog) Find

func (c Catalog) Find(path []string) (Command, bool)

Find resolves what a caller typed after `help` to one entry: a leaf, or a group with everything under it. The path is words, so `help uploads attach` and `help uploads` both land somewhere sensible.

func (Catalog) Leaves

func (c Catalog) Leaves() []Command

Leaves are the commands that can actually be run, each with the whole path a caller types. A group is not one of them: `krowk uploads` on its own is not a command, and the tests that hold the catalog to the routing switch would otherwise be looking for a case that should not exist.

type Command

type Command struct {
	Name        string    `json:"name"`
	Usage       string    `json:"usage,omitempty"`
	Summary     string    `json:"summary"`
	Args        []Arg     `json:"args,omitempty"`
	Flags       []Flag    `json:"flags,omitempty"`
	Subcommands []Command `json:"subcommands,omitempty"`
}

Command is one thing krowk does, or a group of them. A group carries subcommands and is not invocable itself: `krowk uploads` alone is not a command, which is why Usage is empty for one.

type EnvVar

type EnvVar struct {
	Name    string `json:"name"`
	Usage   string `json:"usage"`
	Default string `json:"default,omitempty"`
}

EnvVar is one variable krowk reads.

type Flag

type Flag struct {
	Name string `json:"name"`
	// Aliases are the other spellings that set the same value, e.g. `h` for
	// `help`. They are the same flag, so they are not separate entries.
	Aliases []string `json:"aliases,omitempty"`
	Type    string   `json:"type"`
	Default string   `json:"default"`
	Usage   string   `json:"usage"`
	// Repeatable says the flag may be given more than once and collects every
	// value, rather than the last one winning.
	Repeatable bool `json:"repeatable,omitempty"`
}

Flag is one flag as the flag set actually registers it. Type and Default are the flag set's, not a description of them — a test holds the two together.