README
¶
cmd-toolkit
Basic code for windows command line tools; take a look at the GoDoc reference.
Documentation
¶
Index ¶
- Constants
- Variables
- func AddCommandData(name string, d *CommandDescription)
- func AppName() (string, error)
- func ApplicationPath() string
- func AssignFileSystem(fs afero.Fs) afero.Fs
- func BuildDependencies() []string
- func BuildInformationHeader() string
- func CopyFile(src, dest string) (err error)
- func Copyright(o output.Bus, first int, timestamp, owner string) string
- func CreateAppSpecificPath(topDir string) (string, error)
- func CreateFile(fileName string, content []byte) error
- func CreateFileInDirectory(dir, name string, content []byte) error
- func DecorateBoolFlagUsage(usage string, defaultValue bool) string
- func DecorateIntFlagUsage(usage string, defaultValue int) string
- func DecorateStringFlagUsage(usage, defaultValue string) string
- func DecoratedAppName(applicationName, applicationVersion, timestamp string) string
- func DefaultConfigFileName() string
- func DereferenceEnvVar(s string) (string, error)
- func DirExists(path string) bool
- func Execute(o output.Bus, firstYear int, appName, appVersion, buildTimestamp string, ...) (exitCode int)
- func FileSystem() afero.Fs
- func FlagIndicator() string
- func FlowerBox(lines []string) []string
- func FormatBuildDependencies(dependencies []string) []string
- func FormatGoVersion(version string) string
- func GenerateAboutContent(o output.Bus)
- func GoVersion() string
- func InitApplicationPath(o output.Bus) bool
- func InitBuildData(version, creation string)
- func InitLogging(o output.Bus) (ok bool)
- func InitLoggingWithLevel(o output.Bus, l output.Level) (ok bool)
- func InterpretBuildData() (v string, dependencies []string)
- func LogCommandStart(o output.Bus, name string, m map[string]any)
- func LogFileDeletionFailure(o output.Bus, s string, e error)
- func LogPath() string
- func LogUnreadableDirectory(o output.Bus, s string, e error)
- func Mkdir(dir string) error
- func PlainFileExists(path string) bool
- func ProcessArgs(o output.Bus, f *flag.FlagSet, rawArgs []string) (ok bool)
- func ReadDirectory(o output.Bus, dir string) (files []fs.FileInfo, ok bool)
- func ReportDirectoryCreationFailure(o output.Bus, cmd, dir string, e error)
- func ReportFileCreationFailure(o output.Bus, cmd, file string, e error)
- func ReportFileDeletionFailure(o output.Bus, file string, e error)
- func ReportInvalidConfigurationData(o output.Bus, s string, e error)
- func ReportNothingToDo(o output.Bus, cmd string, fields map[string]any)
- func SecureAbsolutePath(path string) string
- func SetAppName(s string) error
- func SetApplicationPath(s string) (previous string)
- func SetAuthor(s string)
- func SetDefaultConfigFileName(s string)
- func SetFirstYear(i int)
- func SetFlagIndicator(val string)
- func WriteDirectoryCreationError(o output.Bus, d string, e error)
- type CommandDescription
- type CommandProcessor
- type Configuration
- func (c *Configuration) BoolDefault(key string, defaultValue bool) (b bool, err error)
- func (c *Configuration) BooleanValue(key string) (value, ok bool)
- func (c *Configuration) HasSubConfiguration(key string) bool
- func (c *Configuration) IntDefault(key string, b *IntBounds) (i int, err error)
- func (c *Configuration) IntValue(key string) (value int, ok bool)
- func (c *Configuration) String() string
- func (c *Configuration) StringDefault(key, defaultValue string) (s string, err error)
- func (c *Configuration) StringValue(key string) (value string, ok bool)
- func (c *Configuration) SubConfiguration(key string) *Configuration
- type EnvVarMemento
- type IntBounds
Constants ¶
const ( StdFilePermissions = 0o644 // -rw-r--r-- StdDirPermissions = 0o755 // -rwxr-xr-x )
const ApplicationDataEnvVarName = "APPDATA"
ApplicationDataEnvVarName is the name of the environment variable used to read/write application-specific files that are intended to have some permanence.
Variables ¶
var ProductionLogger *simpleLogger = &simpleLogger{ exitFunction: os.Exit, currentLogLevel: defaultLoggingLevel, lock: &sync.RWMutex{}, }
Functions ¶
func AddCommandData ¶
func AddCommandData(name string, d *CommandDescription)
func ApplicationPath ¶
func ApplicationPath() string
ApplicationPath returns the path to application-specific data (%APPDATA%\appname)
func AssignFileSystem ¶ added in v0.10.0
AssignFileSystem sets the current afero.Fs instance and returns the original pre-assignment value
func BuildDependencies ¶
func BuildDependencies() []string
BuildDependencies returns information about the dependencies used to compile the program
func BuildInformationHeader ¶ added in v0.8.0
func BuildInformationHeader() string
func CopyFile ¶
CopyFile copies a file. Adapted from https://github.com/cleversoap/go-cp/blob/master/cp.go
func CreateAppSpecificPath ¶
CreateAppSpecificPath creates a path string for an app-related directory
func CreateFile ¶
CreateFile creates a file; it returns an error if the file already exists
func CreateFileInDirectory ¶
CreateFileInDirectory creates a file in a specified directory. It returns an error if the file already exists
func DecorateBoolFlagUsage ¶
DecorateBoolFlagUsage appends a default value to the provided usage if the default value is false. This is a work-around for the flag package's defaultUsage function, which displays each flag's usage, along with its default value - but it only includes the default value if the default value is not the zero value for the flag's type.
func DecorateIntFlagUsage ¶
DecorateIntFlagUsage appends a default value to the provided usage if the default value is 0. This is a work-around for the flag package's defaultUsage function, which displays each flag's usage, along with its default value - but it only includes the default value if the default value is not the zero value for the flag's type.
func DecorateStringFlagUsage ¶
DecorateStringFlagUsage appends a default value to the provided usage if the default value is the empty string. This is a work-around for the flag package's defaultUsage function, which displays each flag's usage, along with its default value - but it only includes the default value if the default value is not the zero value for the flag's type.
func DecoratedAppName ¶ added in v0.8.0
func DefaultConfigFileName ¶
func DefaultConfigFileName() string
DefaultConfigFileName retrieves the name of the configuration file that contains defaults for the commands
func DereferenceEnvVar ¶
DereferenceEnvVar scans a string for environment variable references, looks up the values of those environment variables, and replaces the references with their values. If one or more of the referenced environment variables are undefined, they are all reported in the error return
func FileSystem ¶ added in v0.10.0
FileSystem returns the current afero.Fs instance
func FlagIndicator ¶ added in v0.4.0
func FlagIndicator() string
FlagIndicator returns the current flag indicator, typically "-" or "--"
func FormatBuildDependencies ¶ added in v0.8.0
func FormatGoVersion ¶ added in v0.8.0
func GenerateAboutContent ¶ added in v0.5.0
GenerateAboutContent writes 'about' content in a pretty format
func GoVersion ¶
func GoVersion() string
GoVersion returns the version of Go used to compile the program
func InitApplicationPath ¶
InitApplicationPath ensures that the application path exists
func InitBuildData ¶
func InitBuildData(version, creation string)
InitBuildData captures information about how the program was compiled, the version of the program, and the timestamp for when the program was built.
func InitLogging ¶
InitLogging sets up logging at the default log level
func InitLoggingWithLevel ¶ added in v0.2.0
InitLoggingWithLevel initializes logging with a specific log level
func InterpretBuildData ¶ added in v0.8.0
func LogCommandStart ¶
LogCommandStart logs the beginning of command execution; if the provided map contains a "command" value, then the name parameter is ignored
func LogFileDeletionFailure ¶
LogFileDeletionFailure logs errors when a file cannot be deleted; does not write anything to the error output because that typically needs additional context
func LogUnreadableDirectory ¶
LogUnreadableDirectory logs errors when a directory cannot be read; does not write anything to the error output because that typically needs additional context
func Mkdir ¶
Mkdir makes the specified directory; succeeds if the directory already exists. Fails if a plain file exists with the specified path.
func PlainFileExists ¶
PlainFileExists returns whether the specified file exists as a plain file (i.e., not a directory)
func ProcessArgs ¶
ProcessArgs processes a slice of command line arguments and handles common errors therein
func ReadDirectory ¶
ReadDirectory returns the contents of a specified directory
func ReportDirectoryCreationFailure ¶
ReportDirectoryCreationFailure reports an error creating a directory to error output and to the log
func ReportFileCreationFailure ¶
ReportFileCreationFailure reports an error creating a file to error output and to the log
func ReportFileDeletionFailure ¶
ReportFileDeletionFailure reports an error deleting a file to error output and to the log
func ReportInvalidConfigurationData ¶
ReportInvalidConfigurationData handles errors found when attempting to parse a YAML configuration file, both logging the error and notifying the user of the error
func ReportNothingToDo ¶
ReportNothingToDo reports a user error in which a command's parameter values prevent the command from doing any work; the report is made to error output and to the log
func SecureAbsolutePath ¶
SecureAbsolutePath returns a path's absolute value
func SetAppName ¶
SetAppName sets the name of the application, returning an error if the name has already been set to a different value or if it is being set to an empty string
func SetApplicationPath ¶
SetApplicationPath is used to set applicationPath to a known value; intent is for use in tesing scenarios
func SetAuthor ¶
func SetAuthor(s string)
SetAuthor is used to override the default value of author, in case someone besides me decides to use this library
func SetDefaultConfigFileName ¶
func SetDefaultConfigFileName(s string)
SetDefaultConfigFileName sets the name of the configuration file that contains defaults for the commands
func SetFirstYear ¶
func SetFirstYear(i int)
SetFirstYear sets the first year of application development
func SetFlagIndicator ¶ added in v0.4.0
func SetFlagIndicator(val string)
SetFlagIndicator sets the flag indicator to the specified value
Types ¶
type CommandDescription ¶
type CommandDescription struct {
IsDefault bool
Initializer func(output.Bus, *Configuration, *flag.FlagSet) (CommandProcessor, bool)
}
type CommandProcessor ¶
CommandProcessor defines the functions needed to run a command
func ProcessCommand ¶
ProcessCommand selects which command to be run and returns the relevant CommandProcessor, command line arguments and ok status
type Configuration ¶
type Configuration struct {
// contains filtered or unexported fields
}
Configuration defines the data structure for configuration information.
func EmptyConfiguration ¶
func EmptyConfiguration() *Configuration
EmptyConfiguration creates an empty Configuration instance
func NewConfiguration ¶
func NewConfiguration(o output.Bus, data map[string]any) *Configuration
NewConfiguration returns a Configuration instance populated as specified by the data parameter
func ReadConfigurationFile ¶
func ReadConfigurationFile(o output.Bus) (c *Configuration, ok bool)
ReadConfigurationFile reads defaults.yaml from the specified path and returns a pointer to a cooked Configuration instance; if there is no such file, then an empty Configuration is returned and ok is true
func (*Configuration) BoolDefault ¶
func (c *Configuration) BoolDefault(key string, defaultValue bool) (b bool, err error)
BoolDefault returns a boolean value for a specified key
func (*Configuration) BooleanValue ¶
func (c *Configuration) BooleanValue(key string) (value, ok bool)
BooleanValue returns a boolean value and whether it exists
func (*Configuration) HasSubConfiguration ¶
func (c *Configuration) HasSubConfiguration(key string) bool
HasSubConfiguration returns whether the specified subConfiguration exists
func (*Configuration) IntDefault ¶
func (c *Configuration) IntDefault(key string, b *IntBounds) (i int, err error)
IntDefault returns a default value for a specified key, which may or may not be defined in the Configuration instance
func (*Configuration) IntValue ¶
func (c *Configuration) IntValue(key string) (value int, ok bool)
IntValue returns an int value and whether it exists
func (*Configuration) String ¶
func (c *Configuration) String() string
func (*Configuration) StringDefault ¶
func (c *Configuration) StringDefault(key, defaultValue string) (s string, err error)
StringDefault returns a string value for a specified key
func (*Configuration) StringValue ¶
func (c *Configuration) StringValue(key string) (value string, ok bool)
StringValue returns the definition of the specified key and ok if the value is defined
func (*Configuration) SubConfiguration ¶
func (c *Configuration) SubConfiguration(key string) *Configuration
SubConfiguration returns a specified sub-configuration
type EnvVarMemento ¶
type EnvVarMemento struct {
// contains filtered or unexported fields
}
EnvVarMemento preserves a memento of an environment variable's state
func NewEnvVarMemento ¶
func NewEnvVarMemento(name string) *EnvVarMemento
NewEnvVarMemento reads a specified environment variable and returns a memento of its state
func (*EnvVarMemento) Restore ¶
func (mem *EnvVarMemento) Restore()
Restore resets a saved environment variable to its original state
type IntBounds ¶
type IntBounds struct {
// contains filtered or unexported fields
}
IntBounds holds the bounds for an int value which has a minimum value, a maximum value, and a default that lies within those bounds
func NewIntBounds ¶
NewIntBounds creates a instance of IntBounds, sorting the provided value into reasonable fields
Source Files
Directories