Documentation
¶
Overview ¶
Package cli implements the collage command-line tool: scaffolding a new project, and driving an existing one's dev and static-build workflows.
Every command writes to the io.Writers the CLI struct carries rather than to os.Stdout/os.Stderr directly, and Run returns an exit code instead of calling os.Exit itself, so the whole surface is testable without touching the real process streams or spawning a real process. cmd/collage/main.go is the only place os.Exit is called.
dev, build and export operate on the current directory's own Go project — the project that imports pkg/collage — rather than on anything internal/cli builds itself: the application is that project's code, which the CLI cannot link into itself, so it cannot construct that project's App in process. Instead it shells out to the go tool in that project, the same way a developer would by hand, through an injectable CommandRunner so tests can assert the constructed command without starting a real process.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrAddUsage = errors.New("collage: add")
ErrAddUsage is returned by the "add" command for arguments it cannot act on.
var ErrDuplicateCommand = errors.New("collage: duplicate command name")
ErrDuplicateCommand is returned when two entries in CLI.Commands share the same Name.
var ErrEmptyCommandName = errors.New("collage: empty command name")
ErrEmptyCommandName is returned when a CLI.Commands entry has an empty Name.
var ErrEnvFile = errors.New("collage: malformed environment file")
ErrEnvFile reports a line in an environment file that is not KEY=value.
A malformed line is an error rather than a skipped one. A skipped line is a setting somebody wrote and the program never saw, and the symptom — a default where a value was meant to be — points everywhere except at the file.
var ErrMissingProjectName = errors.New("collage: missing project name")
ErrMissingProjectName is returned by the "new" command when it is called with no project name.
var ErrNoCommand = errors.New("collage: no command given")
ErrNoCommand is returned when Run is called with no arguments at all.
var ErrReservedCommandName = errors.New("collage: command name collides with a built-in command")
ErrReservedCommandName is returned when a CLI.Commands entry's Name matches a built-in command ("new", "add", "dev", "build", "export", "serve", "inspect", "check", "version", or "help"). A plugin is not permitted to shadow a built-in command.
var ErrTargetNotEmpty = errors.New("collage: target directory is not empty")
ErrTargetNotEmpty is returned by the "new" command when its target directory already has contents and -force was not given.
var ErrUnknownCommand = errors.New("collage: unknown command")
ErrUnknownCommand is returned when the requested command name matches neither a built-in command nor a registered plugin command.
var ErrUnknownTemplate = errors.New("collage: unknown template")
ErrUnknownTemplate is returned by the "new" command for a -template it has no scaffold for.
var Version = buildVersion()
Version is the collage CLI's own version string, printed by "collage version". It identifies this tool, not any project it scaffolds or drives.
Read from the build rather than written down, because a written-down version is one somebody has to remember to change and nobody does: this said 0.1.0 through four releases, so anyone who installed v0.4.1 was told they had the first one. "go install ...@v0.4.1" records that version in the binary, and this reports what is actually there.
Functions ¶
This section is empty.
Types ¶
type CLI ¶
type CLI struct {
// Stdout is where command output is written. A nil Stdout means
// os.Stdout.
Stdout io.Writer
// Stderr is where usage text and error output is written. A nil Stderr
// means os.Stderr.
Stderr io.Writer
// Stdin is where a command that asks a question reads the answer. A nil
// Stdin means os.Stdin; only "build -i" reads it.
Stdin io.Reader
// Runner runs the external "go" commands the dev and build commands
// construct. A nil Runner means a CommandRunner that starts a real
// process; tests substitute a fake to assert the constructed command
// without starting one.
Runner CommandRunner
// Commands lists the CLI subcommands a plugin contributed through
// plugin.Host.RegisterCommand, in the order they should be listed and
// dispatched. Run rejects the whole invocation — see
// ErrReservedCommandName, ErrDuplicateCommand, and ErrEmptyCommandName —
// if any entry is malformed, rather than silently dropping it.
Commands []plugin.Command
}
CLI is the collage command-line tool. It dispatches a command by name, running either one of the built-ins (new, dev, build, version, help) or one of Commands, and returns an exit code rather than terminating the process.
The zero value is usable: Stdout and Stderr default to os.Stdout and os.Stderr, and Runner defaults to a CommandRunner that starts a real process.
func (*CLI) Run ¶
Run dispatches args[0] as a command name and runs it with the remaining arguments, returning the process exit code: 0 on success, 2 for a usage error (no command, an unknown command, or a malformed CLI.Commands), and 1 for a command that parsed correctly but failed to do its work.
Run never calls os.Exit; that is main's job, and main's only job.
type CommandRunner ¶
type CommandRunner interface {
// Run starts name with args in dir (the empty string means the calling
// process's own current directory), with env appended to the started
// process's environment, streaming its output to stdout and stderr, and
// blocks until it exits.
Run(ctx context.Context, dir string, env []string, stdout, stderr io.Writer, name string, args ...string) error
}
CommandRunner runs an external command. dev and build go through this interface, rather than calling os/exec directly, so a test can substitute a fake and assert the command that would have run — its directory, environment, name, and arguments — without starting a real process or a real server.
Source Files