app

Documentation

Overview

Package app provides application primitives.

This should be used for all mains. It provides common globals for the OS and environment in containers, so that they can be isolated for testing.

This package has three sub-packages:

- appext: More containers for typical buf-related needs, to provide things like loggers. - appcmd: A wrapper for cobra. - appcmd/appcmdtesting: Testing utilities for appcmd.

Index

• Constants
• func Args(argList ArgContainer) []string
• func CacheDirPath(envContainer EnvContainer) (string, error)
• func ConfigDirPath(envContainer EnvContainer) (string, error)
• func DataDirPath(envContainer EnvContainer) (string, error)
• func EnvBool(container EnvContainer, key string, defaultValue bool) (bool, error)
• func Environ(envContainer EnvContainer) []string
• func EnvironMap(envContainer EnvContainer) map[string]string
• func GetExitCode(err error) int
• func HomeDirPath(envContainer EnvContainer) (string, error)
• func IsDevNull(path string) bool
• func IsDevPath(path string) bool
• func IsDevStderr(path string) bool
• func IsDevStdin(path string) bool
• func IsDevStdout(path string) bool
• func Main(ctx context.Context, f func(context.Context, Container) error)
• func NewError(exitCode int, message string) error
• func NewErrorf(exitCode int, format string, args ...interface{}) error
• func Run(ctx context.Context, container Container, ...) error
• func WrapError(exitCode int, err error) error
• type ArgContainer
  • func NewArgContainer(args ...string) ArgContainer
  • func NewArgContainerForOS() ArgContainer
• type Container
  • func NewContainer(env map[string]string, stdin io.Reader, stdout io.Writer, stderr io.Writer, ...) Container
  • func NewContainerForArgs(container Container, newArgs ...string) Container
  • func NewContainerForOS() (Container, error)
• type EnvContainer
  • func NewEnvContainer(m map[string]string) EnvContainer
  • func NewEnvContainerForEnviron(environ []string) (EnvContainer, error)
  • func NewEnvContainerForOS() (EnvContainer, error)
  • func NewEnvContainerWithOverrides(envContainer EnvContainer, overrides map[string]string) EnvContainer
• type EnvStderrContainer
• type EnvStdinContainer
• type EnvStdioContainer
• type EnvStdoutContainer
• type StderrContainer
  • func NewStderrContainer(writer io.Writer) StderrContainer
  • func NewStderrContainerForOS() StderrContainer
• type StdinContainer
  • func NewStdinContainer(reader io.Reader) StdinContainer
  • func NewStdinContainerForOS() StdinContainer
• type StdioContainer
• type StdoutContainer
  • func NewStdoutContainer(writer io.Writer) StdoutContainer
  • func NewStdoutContainerForOS() StdoutContainer

Constants

const (
	// DevStdinFilePath is the equivalent of /dev/stdin.
	//
	// This will be /dev/stdin for darwin and linux.
	// This does not exist for windows.
	DevStdinFilePath = "/dev/stdin"
	// DevStdoutFilePath is the equivalent of /dev/stdout.
	//
	// This will be /dev/stdout for darwin and linux.
	// This does not exist for windows.
	DevStdoutFilePath = "/dev/stdout"
	// DevStderrFilePath is the equivalent of /dev/stderr.
	//
	// This will be /dev/stderr for darwin and linux.
	// This does not exist for windows.
	DevStderrFilePath = "/dev/stderr"
	// DevNullFilePath is the equivalent of /dev/null.
	//
	// This will be /dev/null for darwin and linux.
	// This will be nul for windows.
	DevNullFilePath = "/dev/null"
)

Functions

func Args

func Args(argList ArgContainer) []string

Args returns all arguments.

Equivalent to os.Args.

func CacheDirPath

func CacheDirPath(envContainer EnvContainer) (string, error)

CacheDirPath returns the cache directory path.

This will be $XDG_CACHE_HOME for darwin and linux, falling back to $HOME/.cache. This will be %LocalAppData% for windows.

See https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html for darwin and linux. Note that we use the same for darwin and linux as this is what developers expect, as opposed to ~/Library/Preferences etc as the stdlib does for Go.

Users cannot assume that CacheDirPath, ConfigDirPath, and DataDirPath are unique.

func ConfigDirPath

func ConfigDirPath(envContainer EnvContainer) (string, error)

ConfigDirPath returns the config directory path.

This will be $XDG_CONFIG_HOME for darwin and linux, falling back to $HOME/.config. This will be %AppData% for windows.

See https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html for darwin and linux. Note that we use the same for darwin and linux as this is what developers expect, as opposed to ~/Library/Preferences etc as the stdlib does for Go.

Users cannot assume that CacheDirPath, ConfigDirPath, and DataDirPath are unique.

func DataDirPath

func DataDirPath(envContainer EnvContainer) (string, error)

DataDirPath returns the data directory path.

This will be $XDG_DATA_HOME for darwin and linux, falling back to $HOME/.local/share. This will be %LocalAppData% for windows.

See https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html for darwin and linux. Note that we use the same for darwin and linux as this is what developers expect, as opposed to ~/Library/Preferences etc as the stdlib does for Go.

Users cannot assume that CacheDirPath, ConfigDirPath, and DataDirPath are unique.

func EnvBool

func EnvBool(container EnvContainer, key string, defaultValue bool) (bool, error)

EnvBool EnvBoolValue gets and parses the environment variable bool value for the key.

Returns error on parsing error.

func Environ

func Environ(envContainer EnvContainer) []string

Environ returns all environment variables in the form "KEY=VALUE".

Equivalent to os.Environ.

Sorted.

func EnvironMap

func EnvironMap(envContainer EnvContainer) map[string]string

EnvironMap returns all environment variables in a map.

No key will have an empty value.

func GetExitCode

func GetExitCode(err error) int

GetExitCode gets the exit code.

If err == nil, this returns 0. If err was created by this package, this returns the exit code from the error. Otherwise, this returns 1.

func HomeDirPath

func HomeDirPath(envContainer EnvContainer) (string, error)

HomeDirPath returns the home directory path.

This will be $HOME for darwin and linux. This will be %USERPROFILE% for windows.

func IsDevNull

func IsDevNull(path string) bool

IsDevNull returns true if the path is the equivalent of /dev/null.

func IsDevPath

func IsDevPath(path string) bool

IsDevPath returns true if the path is the equivalent of /dev/stdin, /dev/stdout, /dev/stderr, or /dev/null.

func IsDevStderr

func IsDevStderr(path string) bool

IsDevStderr returns true if the path is the equivalent of /dev/stderr.

func IsDevStdin

func IsDevStdin(path string) bool

IsDevStdin returns true if the path is the equivalent of /dev/stdin.

func IsDevStdout

func IsDevStdout(path string) bool

IsDevStdout returns true if the path is the equivalent of /dev/stdout.

func Main

func Main(ctx context.Context, f func(context.Context, Container) error)

Main runs the application using the OS Container and calling os.Exit on the return value of Run.

func NewError

func NewError(exitCode int, message string) error

NewError returns a new Error that contains an exit code.

The exit code cannot be 0.

func NewErrorf

func NewErrorf(exitCode int, format string, args ...interface{}) error

NewErrorf returns a new error that contains an exit code.

The exit code cannot be 0.

func Run

func Run(ctx context.Context, container Container, f func(context.Context, Container) error) error

Run runs the application using the container.

The run will be stopped on interrupt signal. The exit code can be determined using GetExitCode.

func WrapError

func WrapError(exitCode int, err error) error

WrapError returns a new error that contains an exit code.

The exit code cannot be 0 and the err cannot be nil.

Types

type ArgContainer

type ArgContainer interface {
	// NumArgs gets the number of arguments.
	NumArgs() int
	// Arg gets the ith argument.
	//
	// Panics if i < 0 || i >= Len().
	Arg(i int) string
}

ArgContainer provides the arguments.

func NewArgContainer

func NewArgContainer(args ...string) ArgContainer

NewArgContainer returns a new ArgContainer.

func NewArgContainerForOS

func NewArgContainerForOS() ArgContainer

NewArgContainerForOS returns a new ArgContainer for the operating system.

type Container

type Container interface {
	EnvContainer
	StdinContainer
	StdoutContainer
	StderrContainer
	ArgContainer
}

Container contains environment variables, args, and stdio.

func NewContainer

func NewContainer(
	env map[string]string,
	stdin io.Reader,
	stdout io.Writer,
	stderr io.Writer,
	args ...string,
) Container

NewContainer returns a new Container.

func NewContainerForArgs

func NewContainerForArgs(container Container, newArgs ...string) Container

NewContainerForArgs returns a new Container with the replacement args.

func NewContainerForOS

func NewContainerForOS() (Container, error)

NewContainerForOS returns a new Container for the operating system.

type EnvContainer

type EnvContainer interface {
	// Env gets the environment variable raw string value for the key.
	//
	// Returns empty string if the key is not set or the value is empty.
	Env(key string) string
	// ForEachEnv iterates over all non-empty environment variables and calls the function.
	//
	// The value will never be empty.
	ForEachEnv(func(string, string))
}

EnvContainer provides environment variables.

func NewEnvContainer

func NewEnvContainer(m map[string]string) EnvContainer

NewEnvContainer returns a new EnvContainer.

Empty values are effectively ignored.

func NewEnvContainerForEnviron

func NewEnvContainerForEnviron(environ []string) (EnvContainer, error)

NewEnvContainerForEnviron returns a new EnvContainer for the environ slice.

func NewEnvContainerForOS

func NewEnvContainerForOS() (EnvContainer, error)

NewEnvContainerForOS returns a new EnvContainer for the operating system.

func NewEnvContainerWithOverrides

func NewEnvContainerWithOverrides(envContainer EnvContainer, overrides map[string]string) EnvContainer

NewEnvContainerWithOverrides returns a new EnvContainer with the values of the input EnvContainer, overridden by the values in overrides.

Empty values are effectively ignored. To unset a key, set the value to "" in overrides.

type EnvStderrContainer

type EnvStderrContainer interface {
	EnvContainer
	StderrContainer
}

EnvStderrContainer is an environment and stderr container.

type EnvStdinContainer

type EnvStdinContainer interface {
	EnvContainer
	StdinContainer
}

EnvStdinContainer is an environment and stdin container.

type EnvStdioContainer

type EnvStdioContainer interface {
	EnvContainer
	StdioContainer
}

EnvStdioContainer is an environment and stdio container.

type EnvStdoutContainer

type EnvStdoutContainer interface {
	EnvContainer
	StdoutContainer
}

EnvStdoutContainer is an environment and stdout container.

type StderrContainer

type StderrContainer interface {
	// Stderr provides stderr.
	//
	// If no value was passed when Stdio was created, this will return io.EOF on any call.
	Stderr() io.Writer
}

StderrContainer provides stderr.

func NewStderrContainer

func NewStderrContainer(writer io.Writer) StderrContainer

NewStderrContainer returns a new StderrContainer.

func NewStderrContainerForOS

func NewStderrContainerForOS() StderrContainer

NewStderrContainerForOS returns a new StderrContainer for the operaterrg system.

type StdinContainer

type StdinContainer interface {
	// Stdin provides stdin.
	//
	// If no value was passed when Stdio was created, this will return io.EOF on any call.
	Stdin() io.Reader
}

StdinContainer provides stdin.

func NewStdinContainer

func NewStdinContainer(reader io.Reader) StdinContainer

NewStdinContainer returns a new StdinContainer.

func NewStdinContainerForOS

func NewStdinContainerForOS() StdinContainer

NewStdinContainerForOS returns a new StdinContainer for the operating system.

type StdioContainer

type StdioContainer interface {
	StdinContainer
	StdoutContainer
	StderrContainer
}

StdioContainer is a stdio container.

type StdoutContainer

type StdoutContainer interface {
	// Stdout provides stdout.
	//
	// If no value was passed when Stdio was created, this will return io.EOF on any call.
	Stdout() io.Writer
}

StdoutContainer provides stdout.

func NewStdoutContainer

func NewStdoutContainer(writer io.Writer) StdoutContainer

NewStdoutContainer returns a new StdoutContainer.

func NewStdoutContainerForOS

func NewStdoutContainerForOS() StdoutContainer

NewStdoutContainerForOS returns a new StdoutContainer for the operatoutg system.