cli

Documentation

Overview

Package cli contains helper functions related to flag parsing and logging.

Index

• Constants
• Variables
• func ActiveCommand(command *flags.Command) string
• func ContainsString(needle string, haystack []string) bool
• func Fprintf(w io.Writer, msg string, args ...interface{})
• func InitFileLogging(logFile string, logFileLevel Verbosity)
• func InitLogging(verbosity Verbosity)
• func NewProgressReader(reader io.ReadCloser, total string) io.ReadCloser
• func ParseFlags(appname string, data interface{}, args []string, opts flags.Options, ...) (*flags.Parser, []string, error)
• func ParseFlagsFromArgsOrDie(appname, version string, data interface{}, args []string) string
• func ParseFlagsOrDie(appname, version string, data interface{}) string
• func PrintCompletions(items []flags.Completion)
• func Printf(msg string, args ...interface{})
• func ReadAllStdin() []string
• func ReadStdin() <-chan string
• func WindowSize() (int, int, error)
• type Arch
  • func NewArch(os, arch string) Arch
  • func (arch *Arch) GoArch() string
  • func (arch *Arch) String() string
  • func (arch *Arch) UnmarshalFlag(in string) error
  • func (arch *Arch) UnmarshalText(text []byte) error
  • func (arch *Arch) XArch() string
  • func (arch *Arch) XOS() string
• type ByteSize
  • func (b *ByteSize) UnmarshalFlag(in string) error
  • func (b *ByteSize) UnmarshalText(text []byte) error
• type CompletionHandler
• type Duration
  • func (d *Duration) UnmarshalFlag(in string) error
  • func (d *Duration) UnmarshalText(text []byte) error
• type Filepath
  • func (f *Filepath) Complete(match string) []flags.Completion
• type LogBackend
  • func NewLogBackend(interactiveRows int) *LogBackend
  • func (backend *LogBackend) Deactivate()
  • func (backend *LogBackend) RecalcLines()
  • func (backend *LogBackend) SetActive()
• type StdinStrings
  • func (s StdinStrings) Get() []string
• type URL
  • func (u *URL) String() string
  • func (u *URL) UnmarshalFlag(in string) error
  • func (u *URL) UnmarshalText(text []byte) error
• type Verbosity
  • func (v *Verbosity) UnmarshalFlag(in string) error
• type Version
  • func MustNewVersion(in string) *Version
  • func NewVersion(in string) (*Version, error)
  • func (v *Version) Semver() semver.Version
  • func (v Version) String() string
  • func (v *Version) UnmarshalFlag(in string) error
  • func (v *Version) UnmarshalText(text []byte) error
  • func (v *Version) Unset()
  • func (v *Version) VersionString() string

Constants

const GiByte = humanize.GiByte

GiByte is a re-export for convenience of other things using it.

Variables

var StdErrIsATerminal = terminal.IsTerminal(int(os.Stderr.Fd()))

StdErrIsATerminal is true if the process' stderr is an interactive TTY.

var StdOutIsATerminal = terminal.IsTerminal(int(os.Stdout.Fd()))

StdOutIsATerminal is true if the process' stdout is an interactive TTY.

var StripAnsi = regexp.MustCompile("\x1b[^m]+m")

StripAnsi is a regex to find & replace ANSI console escape sequences.

Functions

func ActiveCommand

func ActiveCommand(command *flags.Command) string

ActiveCommand returns the name of the currently active command.

func ContainsString

func ContainsString(needle string, haystack []string) bool

ContainsString returns true if the given slice contains an individual string.

func Fprintf

func Fprintf(w io.Writer, msg string, args ...interface{})

Fprintf implements essentially fmt.Fprintf with replacements of some ANSI sequences, e.g. ${BOLD_RED} -> \x1bwhatever.

func InitFileLogging

func InitFileLogging(logFile string, logFileLevel Verbosity)

InitFileLogging initialises an optional logging backend to a file.

func InitLogging

func InitLogging(verbosity Verbosity)

InitLogging initialises logging backends.

func NewProgressReader

func NewProgressReader(reader io.ReadCloser, total string) io.ReadCloser

NewProgressReader returns a new progress bar reader.

func ParseFlags

func ParseFlags(appname string, data interface{}, args []string, opts flags.Options, completionHandler CompletionHandler) (*flags.Parser, []string, error)

ParseFlags parses the app's flags and returns the parser, any extra arguments, and any error encountered. It may exit if certain options are encountered (eg. --help).

func ParseFlagsFromArgsOrDie

func ParseFlagsFromArgsOrDie(appname, version string, data interface{}, args []string) string

ParseFlagsFromArgsOrDie is similar to ParseFlagsOrDie but allows control over the flags passed. It returns the active command if there is one.

func ParseFlagsOrDie

func ParseFlagsOrDie(appname, version string, data interface{}) string

ParseFlagsOrDie parses the app's flags and dies if unsuccessful. Also dies if any unexpected arguments are passed. It returns the active command if there is one.

func PrintCompletions

func PrintCompletions(items []flags.Completion)

PrintCompletions prints a set of completions to stdout.

func Printf

func Printf(msg string, args ...interface{})

Printf is a convenience wrapper to Fprintf that always writes to stderr.

func ReadAllStdin

func ReadAllStdin() []string

ReadAllStdin reads standard input in its entirety to a slice. Since this reads it completely before returning it won't handle a slow input very nicely. ReadStdin is therefore preferable when possible.

func ReadStdin

func ReadStdin() <-chan string

ReadStdin reads a sequence of space-delimited words from standard input. Words are pushed onto the returned channel asynchronously.

func WindowSize

func WindowSize() (int, int, error)

WindowSize finds and returns the size of the console window as (rows, columns)

Types

type Arch

type Arch struct {
	OS, Arch string
}

Arch represents a combined Go-style operating system and architecture pair, as in "linux_amd64".

func NewArch

func NewArch(os, arch string) Arch

NewArch constructs a new Arch instance.

func (*Arch) GoArch

func (arch *Arch) GoArch() string

GoArch returns the architecture as Go would name it.

func (*Arch) String

func (arch *Arch) String() string

String prints this Arch to its string representation.

func (*Arch) UnmarshalFlag

func (arch *Arch) UnmarshalFlag(in string) error

UnmarshalFlag implements the flags.Unmarshaler interface.

func (*Arch) UnmarshalText

func (arch *Arch) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface

func (*Arch) XArch

func (arch *Arch) XArch() string

XArch returns the "alternative" architecture spelling which some things prefer. In this case amd64 is instead returned as x86_64 and x86 as x86_32.

func (*Arch) XOS

func (arch *Arch) XOS() string

XOS returns the "alternative" OS spelling which some things prefer. The difference here is that "darwin" is instead returned as "osx".

type ByteSize

type ByteSize uint64

A ByteSize is used for flags that represent some quantity of bytes that can be passed as human-readable quantities (eg. "10G").

func (*ByteSize) UnmarshalFlag

func (b *ByteSize) UnmarshalFlag(in string) error

UnmarshalFlag implements the flags.Unmarshaler interface.

func (*ByteSize) UnmarshalText

func (b *ByteSize) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface

type CompletionHandler

type CompletionHandler func(parser *flags.Parser, items []flags.Completion)

A CompletionHandler is the type of function that our flags library uses to handle completions.

type Duration

type Duration time.Duration

A Duration is used for flags that represent a time duration; it's just a wrapper around time.Duration that implements the flags.Unmarshaler and encoding.TextUnmarshaler interfaces.

func (*Duration) UnmarshalFlag

func (d *Duration) UnmarshalFlag(in string) error

UnmarshalFlag implements the flags.Unmarshaler interface.

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface

type Filepath

type Filepath string

A Filepath implements completion for file paths. This is distinct from upstream's in that it knows about completing into directories.

func (*Filepath) Complete

func (f *Filepath) Complete(match string) []flags.Completion

Complete implements the flags.Completer interface.

type LogBackend

type LogBackend struct {
	sync.Mutex                                                  // Protects access to LogMessages
	Rows, Cols, MaxRecords, InteractiveRows, MaxInteractiveRows int
	Output                                                      []string
	LogMessages                                                 *list.List
	Formatter                                                   logging.Formatter // TODO(pebers): seems a bit weird that we have to have this here, but it doesn't
	// contains filtered or unexported fields

} //               seem to be possible to retrieve the formatter from outside the package?

LogBackend is the backend we use for logging during the interactive console display.

func NewLogBackend

func NewLogBackend(interactiveRows int) *LogBackend

NewLogBackend constructs a new logging backend.

func (*LogBackend) Deactivate

func (backend *LogBackend) Deactivate()

Deactivate removes this backend as the currently active log backend.

func (*LogBackend) RecalcLines

func (backend *LogBackend) RecalcLines()

RecalcLines recalculates how many lines we have available, typically in response to the window size changing

func (*LogBackend) SetActive

func (backend *LogBackend) SetActive()

SetActive sets this backend as the currently active log backend.

type StdinStrings

type StdinStrings []string

StdinStrings is a type used for flags; it accepts a slice of strings but also if it's a single - it reads its contents from stdin.

func (StdinStrings) Get

func (s StdinStrings) Get() []string

Get reads stdin if needed and returns the contents of this slice.

type URL

type URL string

A URL is used for flags or config fields that represent a URL. It's just a string because it's more convenient that way; we haven't needed them as a net.URL so far.

func (*URL) String

func (u *URL) String() string

String implements the fmt.Stringer interface

func (*URL) UnmarshalFlag

func (u *URL) UnmarshalFlag(in string) error

UnmarshalFlag implements the flags.Unmarshaler interface.

func (*URL) UnmarshalText

func (u *URL) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface

type Verbosity

type Verbosity logging.Level

A Verbosity is used as a flag to define logging verbosity.

const MaxVerbosity Verbosity = Verbosity(logging.DEBUG)

MaxVerbosity is the maximum verbosity we support.

const MinVerbosity Verbosity = Verbosity(logging.ERROR)

MinVerbosity is the maximum verbosity we support.

func (*Verbosity) UnmarshalFlag

func (v *Verbosity) UnmarshalFlag(in string) error

UnmarshalFlag implements flag parsing. It accepts input in three forms: As an integer level, -v 4 (where -v 1 == warning & error only) As a named level, -v debug As a series of flags, -vvv (note that bare -v does *not* work)

type Version

type Version struct {
	semver.Version
	IsGTE bool
	IsSet bool
}

A Version is an extension to semver.Version extending it with the ability to recognise >= prefixes.

func MustNewVersion

func MustNewVersion(in string) *Version

MustNewVersion creates a new version and dies if it is not parseable.

func NewVersion

func NewVersion(in string) (*Version, error)

NewVersion creates a new version from the given string.

func (*Version) Semver

func (v *Version) Semver() semver.Version

Semver converts a Version to a semver.Version

func (Version) String

func (v Version) String() string

String implements the fmt.Stringer interface

func (*Version) UnmarshalFlag

func (v *Version) UnmarshalFlag(in string) error

UnmarshalFlag implements the flags.Unmarshaler interface.

func (*Version) UnmarshalText

func (v *Version) UnmarshalText(text []byte) error

UnmarshalText implements the encoding.TextUnmarshaler interface

func (*Version) Unset

func (v *Version) Unset()

Unset resets this version to the default.

func (*Version) VersionString

func (v *Version) VersionString() string

VersionString returns just the version, without any preceding >=.