cli

README

docs

Documentation

Overview

Package cli turns a gloo-foo/cmd-* pipeline command into a Unix-style executable.

A wrapper binary declares a Spec — its name, flags, and a Build that maps a parsed invocation to a pipeline — and calls Main. This package owns everything that touches the framework: it constructs the urfave/cli command, overrides the default --version flag, wires standard input/output, executes the pipeline, and reports the process exit code. A wrapper therefore depends on this package and its cmd-* library only — never on the framework directly.

The framework's byte pipeline type and source constructors are re-exported (Command, Source, Stdin, Files, OperandsOrStdin) so a wrapper builds its pipeline without importing the framework at all.

Index

• func Main(spec Spec, version Version)
• type Build
• type Command
• type ExitCode
• type File
• type Invocation
• type Name
• type Path
• type Source
  • func Files(fs afero.Fs, paths ...Path) Source
  • func OperandsOrStdin(inv Invocation) Source
  • func Stdin(r io.Reader) Source
• type Spec
• type Summary
• type Synopsis
• type Version

Functions

func Main

func Main(spec Spec, version Version)

Main is a wrapper's entry point. It runs spec against the real process environment and exits with the resulting code, so a wrapper's main is:

func main() { cli.Main(spec, version) }

Types

type Build

type Build func(inv Invocation) (Source, Command, error)

Build maps one parsed Invocation to the pipeline to execute: the Source that feeds it and an optional filter Command.

• A non-nil filter runs source → filter → stdout (an ordinary Unix filter).
• A nil filter runs source → stdout, so the Source is the whole pipeline (a source command such as ls, seq, or yes).
• A non-nil error aborts the run with that error (e.g. a missing operand).

type Command

type Command = gloo.Command[[]byte, []byte]

Command is a byte-to-byte pipeline stage, re-exported from the framework so a wrapper names it through this package rather than importing the framework.

type ExitCode

type ExitCode int

ExitCode is the process status [run] reports: 0 on success, 1 on any error.

type File

type File = gloo.File

File is a filesystem path a source command reads from (e.g. the root of ls or find), re-exported so a wrapper converts a path operand without importing the framework.

type Invocation

type Invocation struct {
	// Args accesses parsed flags (Bool/String/…) and operands (Args/NArg).
	Args *urf.Command
	// Stdin is the process's standard input, for filters that read it.
	Stdin io.Reader
	// Fs is the filesystem file operands are read through (injectable for tests).
	Fs afero.Fs
}

Invocation is the parsed command line handed to a Build: the urfave/cli accessor for flags and operands, plus the injected standard input and filesystem the source is drawn from.

type Name

type Name string

Name is the executable's invoked name (e.g. "cat").

type Path

type Path string

Path is one filesystem path operand a filter reads its input from.

type Source

type Source = gloo.Source[[]byte]

Source is a byte pipeline source, re-exported for the same reason.

func Files

func Files(fs afero.Fs, paths ...Path) Source

Files builds a Source that reads the named files in order, through fs.

func OperandsOrStdin

func OperandsOrStdin(inv Invocation) Source

OperandsOrStdin is the canonical Unix-filter source: the file operands when any are given, otherwise standard input. It centralizes the per-wrapper source helper that every file-or-stdin filter (cat, head, wc, …) repeats.

func Stdin

func Stdin(r io.Reader) Source

Stdin builds a Source that reads the given reader (a wrapper passes inv.Stdin). It lets a filter draw its input from standard input without importing the framework.

type Spec

type Spec struct {
	Name     Name
	Summary  Summary
	Synopsis Synopsis
	Build    Build
	Flags    []urf.Flag
}

Spec declares one wrapper executable: its identity, its flags, and how it builds its pipeline. It is an immutable value passed by a wrapper to Main.

type Summary

type Summary string

Summary is the one-line description shown in the --help header.

type Synopsis

type Synopsis string

Synopsis is the multi-line usage block shown in --help. urfave/cli indents the whole block three spaces, so a wrapper keeps its lines flush-left.

type Version

type Version = string

Version is the build version string a wrapper threads in from its main via ldflags. It is a plain alias because urfave/cli's Version field is a string and must stay bound to that ldflags symbol without conversion.