contour

package module
v0.0.0-...-a1869fc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 20, 2017 License: MIT Imports: 16 Imported by: 9

README

contour

GoDocBuild Status

Contour is a configuration handling package supporting files (JSON, YAML, TOML), environment variables, and flags.

About

Contour attempts to be a simple to use package that can be used for key value pairs or configuration information and whose behavior can be modified to suit your application's need. Contour can work with or without a configuration file, use environment variables, and supports flags.

Each key value pair is saved as a setting, which also contains information about that pair that enables Contour to figure out what it can do with each setting. Groups of settings are stored in a Settings struct, which also contains information about that group, including its name, and how it should behave. For convenience, Contour provides a standard Settings with its name set to the executable name. All Contour functions operate on this Settings. For your own Settings, use NewSettings.

Settings can be used concurrently.

Setting

A setting is a key value pair.

Application Setting

An application setting is any setting that cannot be modified by a configuration file, environment variable, or flag. A Core setting cannot be updated once added. Any attempt to modify a Core setting will result in an error. A regular application setting can only be updated using an Update method; a configuration file, environment variable, or flag cannot modify an application setting, they are not exposed outside of the application. These settings are added to a setting via Add methods. Settings, whose values can be modified, are changed using an Update method.

Configuration Settings

Configuration settings are any settings that can be modified by a configuration file, environment variable, or flag, in that order of precedence. These settings are Registered using Register methods. They have a default value that can be set by one or more of the above methods, depending on what is allowed to update them.

The update rules for a configuration setting is at a per setting level. Setting Foo can be registered as a ConfFileVar, which means it can only be updated by a configuration file, while Bar can be registered as a Flag, which means it can be updated by a configuration file, environment variable, or flag. What is allowed up update a configuration setting can be set per setting, e.g. flag Biz can be set to be updateable by a configuration file or a flag but not an environment variable.

Flags can be registered with a short flag, or alias.

Configuration files

Contour supports various formats for configuration files:

  • JSON (default)
  • TOML
  • YAML

If a configuration file has not been explicitly set, the settings will use its name as the filename and the format it has been set to use as the file's extension. Contour will search for the configuration file using the filename, using any additional paths and environment variables it has been given along with the working directory, executable directory, and $PATH. The search behavior is fully configurable.

Currently, only the top level keys of the configuration file are parsed with keys whose values are not bool, int, int64, or a string being saved as an interface{}.

If the configuration file is optional, settings can be set to not emit an error when it can't find it.

Easy to use:

Import contour

To use in a basic application, import the package:

import "github.com/mohae/contour"
Register settings

Configuration variables must be registered for Contour to recognize them. Registering a setting lets Contour know what that setting's datatype is, if it can be modified, and if so, by what.

contour.AddString(key, value)
contour.RegisterStringConfFileVar("foo", "bar")
contour.RegisterBoolFlag("log", "l", false, "false", "enable/disable logging")
Initialize the configuration

Once all settings have been registered, Set needs to be run to update the settings with all available configuration file settings and environment variables.

err := contour.Set()
Parse flags

If flags are used, the command-line args need to be parsed for flags. The standard logger uses os.Args[1:]:

args, err := contour.ParseFlags()

All other settings must have the args passed:

	s := NewSettings("foo")
	args, eerr := s.ParseFlags(args)

Any args that are left over, after parsing, are returned. A list of all flags parsed is maintained and either the whole list can be retrieved:

flgs := contour.Visited()

or a specific flag can be checked:

was := contour.WasVisited("foo")
supported datatypes

Currently, only the following datatypes are supported: * bool * int * int64 * interface{} * string

Documentation

Overview

Package contour: a package for storing settings. These settings may be configuration settings or application settings.

Application settings are either Core or Basic settings. Core settings cannot be modified once Added with AddCore functions. Basic settings are set by Add functions and can be updated with Update functions. These settings are not exposed as configuration file variables, environment variables, or flags. They cannot be modified by any of them.

Configuration settings are settings that are updateable by one or more of the following, depending on what type of configuration setting they are, in order of override precedence: configuration file variable, environment variable, and flag. Configuration settings are registered. They are registered with default values and are overridable according to their configuration setting type. For custom override properties, e.g. can be set by either a configuration file or a flag but not by an environment variable, use the Register function.

Registering a configuration setting will result in settings being configured to use that setting type's source, along with any lower precedence sources during the Set process, e.g. registering a ConfFileVar will result in settings being configured to use a configuration file and registering a Flag will result in settings being configured to use a configuration file and check environment variables.

After registration, settings can be set to ignore certain configuration sources using the SetUseConfFile and SetUseEnvVars methods. Flag parsing is always explicitly done by the caller with the ParseFlags method.

The configuration file can be explicitly set, in which case the configuration file format will be inferred from the extension with unknown extensions resulting in an UnsupportedFormatError. If there are configuration settings registered, of any type, and the configuration file has not been set, it will be assumed to be SettingsName.Format where SettingsName is the name of the settings and Format is the configuration file format that settings is set to use, which defaults to JSON. The format can be set using the SetFormat method. This only needs to be done if the configuration file is not explictly set using the SetConfFilename method. The supported configuration formats are: JSON, TOML, and YAML. A settings can also be configured to search for the configuration file until it is found. Where it looks depends on how it has been configured and what additional information the settings has been provided: 

configuration filename
paths set with SetConfFilePaths
paths extracted from env vars set by SetConfFilePathEnvVars*
working directory
executable directory
paths extracted from the PATH*

* the env vars may contain multiple paths; each path will be checked

By default, a missing configuration file results in an os.PathError with a list of all paths that were checked along with an os.IsNotExist error. A settings can be set to not return an error when the configuration file cannot be found by using the SetErrOnMissingConfFile method.

Contour only saves the top level keys of configuration files as settings. For configuration file settings that are arrays, maps, or objects, their values will be saved as an interface{}.

Environment variables are UPPER CASE and use a NAME_KEY as the variable name, where NAME is the name of the Settings, the executable name for the package global Settings, and KEY is the name, or key, of the setting.

Flags can be registered with either a short flag or alias using the short parameter of Register Flag functions.

All operations are thread-safe.

The workflow for application configurations is: 

Register all configuration settings.
Call the Set() function.
Call the ParseFlags() function.

Non-configuration application settings, Core and Basic, can be added at anytime.

For convenience, there's a predefined 'standard' Settings, whose name is the executable's name.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrFlagsParsed   = errors.New("flags have already been parsed")
	ErrUseFlagsFalse = errors.New("not set to use flags")
)
View Source 
var ErrNoSettingName = errors.New("no setting name provided")
View Source 
var (
	Exe = appname.Get() // Exe is the name of the running executable.

)

Functions

func AddBool 

func AddBool(k string, v bool) error

AddBool adds a bool setting to the standard settings with the key k and value f. This can be only be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func AddBoolCore 

func AddBoolCore(k string, v bool) error

AddBoolCore adds a Core bool setting to the standard settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func AddInt 

func AddInt(k string, v int) error

AddInt adds an int setting to the standard settings with the key k and value f. This can be only be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func AddInt64 

func AddInt64(k string, v int64) error

AddInt64 adds an int64 setting to the standard settings with the key k and value f. This can be only updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func AddInt64Core 

func AddInt64Core(k string, v int64) error

AddInt64Core adds a Core int64 setting to the standard settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func AddIntCore 

func AddIntCore(k string, v int) error

AddIntCore adds a Core int setting to the standard settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func AddInterface 

func AddInterface(k string, v interface{}) error

AddInterface adds an interface setting to the standard settings with the key k and value f. This can be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func AddInterfaceCore 

func AddInterfaceCore(k string, v interface{}) error

AddInterfaceCore adds a Core interface setting to the standard settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func AddString 

func AddString(k, v string) error

AddString adds a string setting to the standard settings with the key k and value f. This can be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func AddStringCore 

func AddStringCore(k, v string) error

AddStringCore adds a Core string setting to the standard settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func Bool 

func Bool(k string) bool

Bool returns the standard settings' value for k as a bool. A false will be returned if k doesn't exist or if its value is not a bool.

func BoolE 

func BoolE(k string) (bool, error)

BoolE returns the standard settings' value for k as a bool. A vSettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not bool.

func CheckExeDir 

func CheckExeDir() bool

CheckExeDir returns if Settings should check the executable directory for the configuration file.

func CheckWD 

func CheckWD() bool

CheckWD returns if settings should check the working directory for the configuration file.

func ConfFilePathEnvVars 

func ConfFilePathEnvVars() []string

ConfFilePathEnvVars returns the names of the environment variables that have paths that the standard settings should check when looking for the configuration file.

func ConfFilePaths 

func ConfFilePaths() []string

ConfFilePaths returns the paths that the standard settings should check when looking for the configuration file.

func ConfFilename 

func ConfFilename() string

ConfFilename returns the standard settings' configuration filename.

func EnvVarName 

func EnvVarName(k string) string

EnvVarName returns the environment variable name for k. This will be NAME_K, where K is k and NAME is the standard settings' name (executable name).

func ErrOnMissingConfFile 

func ErrOnMissingConfFile() bool

ErrOnMissingConfFile returns if the standard settings is configured to return an error if the configuration file cannot be located.

func Exists 

func Exists(k string) bool

Exists returns if setting k exists. A false will be be returned if k doesn't exist in the standard settings.

func Get 

func Get(k string) interface{}

Get returns the standard settings' value for k as an interface{}. A nil is returned if k doesn't exist.

func GetE 

func GetE(k string) (interface{}, error)

GetE returns the standard settings' value for k as an interface{}. A SettingNotFoundError is returned if k doesn't exist.

func GetEnvVarPaths 

func GetEnvVarPaths(key string) []string

GetEnvVarPaths gets the value of an environment variable, that is assumed to have path info, splits it into its path elements, and expands them, returning a list of paths.

If key is empty, a nil is returned. If the environment variable for the key is either not set or is empty, an empty slice will be returned.

func GetFormatString 

func GetFormatString() string

GetFormatString returns the standard settings' format to use if the ConfFilename hasn't been explicitly set as a string

func Int 

func Int(k string) int

Int returns the standard settings' value for k as an int. A 0 will be returned if k doesn't exist or if its value is not an int.

func Int64 

func Int64(k string) int64

Int64 returns the standard settings' value for k as an int64. A 0 will be returned if k doesn't exist or if its value is neither an int64 nor an int setting.

func Int64E 

func Int64E(k string) (int64, error)

Int64E returns the standard settings' value for k as an int64. A SettingNotFoundError is returned if k doesn't exist in. A DataTypeError will be returned if the value is neither an int64 nor an int.

func IntE 

func IntE(k string) (int, error)

IntE returns the standard settings' value for k as an int. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not an int.

func Interface 

func Interface(k string) interface{}

Interface returns the standard settings' value for k as an interface{}. A nil will be returned if k doesn't exist.

func InterfaceE 

func InterfaceE(k string) (interface{}, error)

InterfaceE returns the standard settings' value for k as an interface{}. A SettingNotFoundError is returned if k doesn't exist.

func IsConfFileVar 

func IsConfFileVar(k string) bool

IsConfFileVar returns if setting k is a ConfFileVar setting. A false will be returned if k doesn't exist in the standard settings.

func IsConfFileVarE 

func IsConfFileVarE(k string) (bool, error)

IsConfFileVarE returns if setting k is a ConfFileVar setting. A SettingNotFoundErr will be returned if k doesn't exist in the standard settings.

func IsCore 

func IsCore(k string) bool

IsCore returns if setting k is a Core setting. False will be returned if k doesn't exist in settings.

func IsCoreE 

func IsCoreE(k string) (bool, error)

IsCoreE returns if setting k is a Core setting. A SettingNotFoundErr will be returned if k doesn't exist in the standard settings.

func IsEnvVar 

func IsEnvVar(k string) bool

IsEnvVar returns if setting k is an EnvVar setting. A false will be returned if k doesn't exist in the standard settings.

func IsEnvVarE 

func IsEnvVarE(k string) (bool, error)

IsEnvVarE returns if setting k is an EnvVar setting. A SettingNotFoundErr will be returned if k doesn't exist in the standard settings.

func IsFlag 

func IsFlag(k string) bool

IsFlag returns if setting k is a Flag setting. A false will be returned if k doesn't exist in the standard settings.

func IsFlagE 

func IsFlagE(k string) (bool, error)

IsFlagE returns if setting k is a Flag setting. A SettingNotFoundErr will be returned if k doesn't exist in the standard settings.

func IsSet 

func IsSet() bool

IsSet returns if the standard settings' configuration settings have been set from all of its configured sources.

func Name 

func Name() string

Name returns the standard settings' name.

func ParseFlags 

func ParseFlags() ([]string, error)

ParseFlags parses the command-line args from os.Args[1:]. Only settings of type Flag can be set via ParseFlags. Flags have the highest precedence. After parsing, any non-flag args are returned to the caller and a list of flags in the args is cached.

If the standard settings has already parsed the flags or standard settings is set to not use flags, nothing will be done and nothing will be returned.

All of standard settings' flags must be registered prior to calling.

func PathsFromEnvVar 

func PathsFromEnvVar(s string) []string

PathsFromEnvVars returns a list of expanded paths found in the environemnt variable s. If nothing was found, or the environment variable was empty, a nil will be returned.

func RegisterBoolConfFileVar 

func RegisterBoolConfFileVar(k string, v bool) error

RegisterBoolConfFileVar registers a bool setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterBoolEnvVar 

func RegisterBoolEnvVar(k string, v bool) error

RegisterBoolEnvVar registers a bool setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterBoolFlag 

func RegisterBoolFlag(k, short string, v bool, dflt, usage string) error

RegisterBoolFlag registers a bool setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterInt64ConfFileVar 

func RegisterInt64ConfFileVar(k string, v int64) error

RegisterInt64ConfFileVar registers an int64 setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterInt64EnvVar 

func RegisterInt64EnvVar(k string, v int64) error

RegisterInt64EnvVar registers an int64 setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterInt64Flag 

func RegisterInt64Flag(k, short string, v int64, dflt, usage string) error

RegisterInt64Flag registers an int64 setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterIntConfFileVar 

func RegisterIntConfFileVar(k string, v int) error

RegisterIntConfFileVar registers an int setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterIntEnvVar 

func RegisterIntEnvVar(k string, v int) error

RegisterIntEnvVar registers an int setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterIntFlag 

func RegisterIntFlag(k, short string, v int, dflt, usage string) error

RegisterIntFlag registers an int setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterInterfaceConfFileVar 

func RegisterInterfaceConfFileVar(k string, v interface{}) error

RegisterInterfaceConfFileVar registers an int setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterSetting 

func RegisterSetting(typ, name, short string, value interface{}, dflt, usage string, IsCore, IsConfFileVar, IsEnv, IsFlag bool) error

RegisterSetting registers a setting with the standard settings. For most settings, the data and setting type specific registration and add functions should be used. The exception would be when more granular control over what can update a registered setting is needed. This method allows Is[ConfFileVar|EnvVar|Flag] bools to be set independently.

If a setting with the key k already exists, a SettingExistsError will be returned. If k is an empty string an ErrNoSettingName will be returned.

The short, dflt, and usage parms only apply to settings whose IsFlag bool is true.

For non-Core settings, IsCore must be false. If IsCore is true, k's value cannot be changed after registration, regardless of the truthiness of Is[ConfFileVar|IsEnvVar|IsFlag]. For Core settings, AddCore methods should be used.

If the setting can be updated by a configuration file, environment variable or a flag, the Is[ConfFileVar|IsEnv|IsFlag] bools should be set to true as appropriate. These conditionals are independent; e.g. a setting can have both IsConfFileVar and IsFlag set to true if the setting is not to be updateable from an environment variable.

If Is[Core|ConfFileVar|Env|Flag] are all false, the setting will only be updateable by using the Update methods. For these kind of settings, the usage of Add functions should be preferred. These setting will not be exposed to the configuration file, as an environment variable, or as a flag.

For non string, bool, int, and int64 types, the type must be "interface{}"

func RegisterStringConfFileVar 

func RegisterStringConfFileVar(k, v string) error

RegisterStringConfFileVar registers a string setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterStringEnvVar 

func RegisterStringEnvVar(k, v string) error

RegisterStringEnvVar registers a string setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func RegisterStringFlag 

func RegisterStringFlag(k, short, v, dflt, usage string) error

RegisterStringFlag registers a string setting with the standard settings using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func SearchPATH 

func SearchPATH() bool

SearchPATH returns if the standard settings should use the user's PATH environment variable to check for the configuratiom file.

func Set 

func Set() error

Set updates the standard settings' configuration from a configuration file and environment variables. This is only run once; subsequent calls will result in no changes. Only settings that are of type ConfFileVar or EnvVar will be affected. This does not handle flags.

Once the standard settings has been set, updated, it will not update again; subsequent calls will result in nothing being done.

All ConfFileVar, EnvVar, and Flag settings must be registered before calling Set.

func SetCheckExeDir 

func SetCheckExeDir(b bool)

SetCheckExeDir sets if the standard settings should check the executable directory for the configuration file.

func SetCheckWD 

func SetCheckWD(b bool)

SetCheckWD sets if settings should check the working directory for the configuration file.

func SetConfFilePathEnvVars 

func SetConfFilePathEnvVars(envVars []string)

SetConfFilePathEnvVars sets the names of the environment variables that have paths that the standard settings should check when looking for the configuration file. The environment variables will be checked in the order provided. The environment variables may contain multiple paths.

func SetConfFilePaths 

func SetConfFilePaths(paths []string)

SetConfFilePaths sets the paths that the standard settings should check when looking for the configuration file. The paths will be checked in the order provided.

func SetConfFilename 

func SetConfFilename(v string)

SetConfFilename sets the standard settings' configuration filename and configures settings to use a configuration file. If the filename is empty, an error is returned. If the filename's extension isn't parsable to a supported configuration format, an UnsupportedFormatError is returned.

func SetErrOnMissingConfFile 

func SetErrOnMissingConfFile(b bool)

SetErrOnMissingConfFile sets if the standard settings should return an error if the confiugration file cannot be located.

func SetFormat 

func SetFormat(f Format)

SetFormat sets the standard settings' format to use for the conffile if the ConfFilename hasn't been explicitly set.

func SetFormatString 

func SetFormatString(v string) error

SetFormatString sets the standard settings' format, using a string, to use for the configuration file if the ConfFilename hasn't been explicitly set. If the string isn't parsable to a supported Format, an UnsupportedFormatError will be returned.

func SetFromConfFile 

func SetFromConfFile() error

SetFromConfFile updates the settings' configuration from the configuration file. If the configuration filename was not set using the SetConfFilename method, settings will look for the configuration file using the settings' name and it's format: name.format.

The format, in full, is used as the extension, i.e. JSON's extension will be 'json', TOML's extension will be 'toml', and YAML's extension will be 'yaml'.

Once the settings has been set, updated from the configuration file, they will not be updated again from the configuration file; subsequent calls will result in nothing being done.

The settings will look for the configuration file according to how it's been configured. 

filename
confFilePaths + filename
confFileEnvVars + filename (each env var may have multiple path elements)
working directory + filename
executable directory + filename
$PATH element + filename (PATH may have multiple path elements)

Any of the above elements that are either empty or false are skipped.

If the file cannot be found, an os.PathError with an os.ErrNotExist and a list of all paths checked is returned.

func SetFromEnvVars 

func SetFromEnvVars() error

SetFromEnvVars updates the standard settings' configuration from environment variables.

Once the standard settings has been set, updated, from environment variables they, will not be updated again from environment variables; subsequent calls will result in nothing being done.

A setting's env name is a concatonation of the settings' name, an underscore (_), and the setting's key, e.g. given a settings with the name 'foo', a setting whose key is 'bar' will be updateable with the environment variable FOO_BAR.

func SetSearchPATH 

func SetSearchPATH(b bool)

SetSearchPATH sets if the standard settings should use the user's PATH environment variable to check for the configuratiom file.

func SetUsage 

func SetUsage(f func())

SetUsage sets the standard settings' Usage func.

func String 

func String(k string) string

String returns the standard settings' value for k as a string. An empty string, "", will be returned if k doesn't exist or if its value is not a string.

func StringE 

func StringE(k string) (string, error)

StringE returns the standard settings' value for k as a string. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not a string.

func UpdateBool 

func UpdateBool(k string, v bool) error

UpdateBool updates k with a boo, v. If the standard settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func UpdateInt 

func UpdateInt(k string, v int) error

UpdateInt updates k with aan int, v. If the standard settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func UpdateInt64 

func UpdateInt64(k string, v int64) error

UpdateInt64 updates k with an int64, v. If the standard settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func UpdateInterface 

func UpdateInterface(k string, v interface{}) error

UpdateInterface updates k with aan int, v. If the standard settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func UpdateString 

func UpdateString(k string, v string) error

UpdateString updates a string setting. If the standard setting k doesn't exist, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func UseConfFile 

func UseConfFile() bool

UseConfFile returns if the standard settings will update its configuration settings from a configuration file.

func UseEnvVars 

func UseEnvVars() bool

UseEnvVars returns if the standard settings will update its configuration settings from environment variables.

func UseFlags 

func UseFlags() bool

UseFlags returns if the standard settings has any flags that can be updated by ParseFlags.

func Visited 

func Visited() []string

Visited returns the names of all standard settings' flags that were set during flag parsing, in lexical order.

func WasVisited 

func WasVisited(k string) bool

WasVisited returns if a standard settings flag k was parsed in the processing of args.

Types

type CoreUpdateError 

type CoreUpdateError struct {
	// contains filtered or unexported fields
}

CoreUpdateError happens when there's an attempt to update a Core setting.

func (CoreUpdateError) Error 

func (e CoreUpdateError) Error() string

type DataTypeError 

type DataTypeError struct {
	// contains filtered or unexported fields
}

DataTypeError occurs when the requested setting's data type is different than the type requested.

func (DataTypeError) Error 

func (e DataTypeError) Error() string

type Format 

type Format int

Format is the type of esupported encoding for configuration files. 

const (
	// Unsupported configuration encoding format.
	Unsupported Format = iota
	// JSON encoding format.
	JSON
	// TOML encoding format.
	TOML
	// YAML encoding format
	YAML
)

func GetFormat 

func GetFormat() Format

GetFormat returns the standard settings' format to use if the ConfFilename hasn't been explicitly set.

func ParseFilenameFormat 

func ParseFilenameFormat(s string) (Format, error)

ParseFilenameFormat takes a string that represents a filename and returns the files format based on its extension. If the filename either doesn't have an extension or the extension is not one of a supported file format an UnsupportedFormatError will be returned.

func ParseFormat 

func ParseFormat(s string) (Format, error)

ParseFormat takes a string and returns the Format it represents or an UnsupportedFormatError if it can't be matched to a supported format. The string is normalized to lower case before matching.

func (Format) String 

func (f Format) String() string

type SettingExistsError 

type SettingExistsError struct {
	// contains filtered or unexported fields
}

SettingExistsError occurs when a setting being Added or Registered already exists under the same name (k).

func (SettingExistsError) Error 

func (e SettingExistsError) Error() string

type SettingNotFoundError 

type SettingNotFoundError struct {
	// contains filtered or unexported fields
}

SettingNotFoundError occurs when a setting isn't found.

func (SettingNotFoundError) Error 

func (e SettingNotFoundError) Error() string

type SettingType 

type SettingType int

SettingType is type of setting. 

const (
	// Basic settings are settings that are none of the below. These are often
	// referred to as application settings: settings that can only be updated
	// within an application and not by configuration files, environment
	// variables, or flags. These settings do not have to be registered.
	Basic SettingType = iota + 1
	// Core settings are immutable once registered.
	Core
	// ConFileVar settings can be set from a configuration file.
	ConfFileVar
	// EnvVar settings can be set from a configuration file and an environment
	// variable; unless it has been explicitly set to not be updateable from a
	// configuration file.
	EnvVar
	// Flag settings can be set from a configuration file, an environment
	// variable, and a flag; unless it has been explicitly set to not be
	// updateable from either a configuration file or an environment variable.
	Flag
)

These settings are in order of precedence. Each setting type can be set by any of the types with higher precedence if contour is configured to use that type.

func (SettingType) String 

func (t SettingType) String() string

type Settings 

type Settings struct {
	// contains filtered or unexported fields
}

Settings is a named group of settings and information related to that set.

The name of the Settings is used for environment variable naming, if applicable.

Configuration settings, settings that can be set from a configuration file, an environment variable, or a flag are registered with their default value. Settings will then update them with the anything it finds using the Set and ParseFlags methods. Configuration settings are updated according to the type that the are registered as; with higher precedence types being updatable from a lower precedence source, e.g. a Flag setting can be updated from a configuration file, an environment variable, or a flag, while a ConfFileVar setting can only be updated by a configuration file. The order of precedence is: 

ConfFileVar
EnvVar
Flag

In addition to configuration settings there are settings and Core settings. Core settings cannot be changed once they are set; any attempt to update a core setting will result in an error. Core settings are added using addCore methods. Regular settings cannot be updated by an external source, e.g. a configuration file, an environment variable, or a flag, but can be updated using an Update method.

If the configuration filename was set using the SetConfFilename method or a setting was registered, an attempt will be made to laod setting information from a configuration file. If the configuration filename wasn't explicitly set, settings will build it using it's name and configured format, which defaults to JSON. The extension of the configuration file will be the format, i.i. JSON's extension will be 'json', TOML's extension will be 'toml', and YAML's extension will be 'yaml'.

Settings will look for the configuration file according to the information it has and how it has been configured, e.g. look in additional paths provided to it, look in environment variables for paths, look in the executable directory, search the $PATH, etc. Settings defaults to returning an os.ErrNotExist os.PathError but it can be configured to not return an error if the configuration file is not found. New Settings are configured to search for the confiugration file in the $PATH.

If any configuration settings were registered as a Flag or EnvVar setting, Settings will check the setting's corresponding environment variable. A setting's environment variable is a concatonation of the Settings' name and the setting's key, in UPPER_SNAKE_CASE, e.g. the environmnet variable name for a Settings with the name foo and a setting with the key bar would be FOO_BAR.

Registering a ConfFileVar setting will set settings to look for a configuration file during the set process. Registering either an EnvVar or a Flag will set settings to look for a configuration file during the set process and check environment variables. After registering all configuration settings, the settings can be explicitly set to not use a configuration file or environment variables using the SetUseConfFile and SetUseEnvVars methods.

Once a Settings has been updated from a configuration file and environment variables, configuration settings cannot be updated again from those sources, subsequent attempts will result in no error and nothing being done.

If any configuration settings were registered as a Flag, ParseFlags should be called. Once the flags have been parsed, subsequent calls to ParseFlags will return an ErrFlagsParsed error. If settings is not configured to use flags, ParseFlags will return an ErrUSeFlagsFalse error.

Settings are safe for concurrent use.

func New 

func New(name string) *Settings

New provides an initialized Settings named name.

func (*Settings) AddBool 

func (s *Settings) AddBool(k string, v bool) error

AddBool adds a bool setting to the settings with the key k and value f. This can be only be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) AddBoolCore 

func (s *Settings) AddBoolCore(k string, v bool) error

AddBoolCore adds a Core bool setting to the settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) AddInt 

func (s *Settings) AddInt(k string, v int) error

AddInt adds an int setting to the settings with the key k and value f. This can be only be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) AddInt64 

func (s *Settings) AddInt64(k string, v int64) error

AddInt64 adds an int64 setting to the settings with the key k and value f. This can be only updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) AddInt64Core 

func (s *Settings) AddInt64Core(k string, v int64) error

AddInt64Core adds a Core int64 setting to the settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) AddIntCore 

func (s *Settings) AddIntCore(k string, v int) error

AddIntCore adds a Core int setting to the settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) AddInterface 

func (s *Settings) AddInterface(k string, v interface{}) error

AddInterface adds an interface{} setting to the settings with the key k and value v. This can be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) AddInterfaceCore 

func (s *Settings) AddInterfaceCore(k string, v interface{}) error

AddInterfaceCore adds a Core interface{} setting to the settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) AddString 

func (s *Settings) AddString(k, v string) error

AddString adds a string setting to the settings with the key k and value f. This can be updated using the Update functions. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) AddStringCore 

func (s *Settings) AddStringCore(k, v string) error

AddStringCore adds a Core string setting to the settings with the key k and value v. The value of this setting cannot be changed once it is added. If a setting with the same name, k, exists, a SettingExistsErr will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) Bool 

func (s *Settings) Bool(k string) bool

Bool returns the settings' value for k as a bool. A false will be returned if k either doesn't exist or if its value is not a bool.

func (*Settings) BoolE 

func (s *Settings) BoolE(k string) (bool, error)

BoolE returns the settings' value for k as a bool. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not a bool.

func (*Settings) CheckExeDir 

func (s *Settings) CheckExeDir() bool

CheckExeDir returns if Settings should check the executable directory for the configuration file.

func (*Settings) CheckWD 

func (s *Settings) CheckWD() bool

CheckWD returns if settings should check the working directory for the configuration file.

func (*Settings) ConfFilePathEnvVars 

func (s *Settings) ConfFilePathEnvVars() []string

ConfFilePathEnvVars retyrbs the names of the environment variables that have paths that settings should check when looking for the configuration file.

func (*Settings) ConfFilePaths 

func (s *Settings) ConfFilePaths() []string

ConfFilePaths returns the paths that settings should check when looking for the configuration file.

func (*Settings) ConfFilename 

func (s *Settings) ConfFilename() string

ConfFilename returns the settings' configuration filename.

func (*Settings) EnvVarName 

func (s *Settings) EnvVarName(k string) string

EnvVarName returns the environment variable name for k. This will be NAME_K, where K is k and NAME is settings' name.

func (*Settings) ErrOnMissingConfFile 

func (s *Settings) ErrOnMissingConfFile() bool

ErrOnMissingConfFile returns if settings is configured to return an error if the configuration file cannot be located.

func (*Settings) Exists 

func (s *Settings) Exists(k string) bool

Exists returns if settings has a setting k.

func (*Settings) Get 

func (s *Settings) Get(k string) interface{}

Get returns the settings' value for k as an interface{}. A nil is returned if k doesn't exist.

func (*Settings) GetE 

func (s *Settings) GetE(k string) (interface{}, error)

GetE returns settings' value for k as an interface{}. A SettingNotFoundError is returned if k doesn't exist.

func (*Settings) GetFormat 

func (s *Settings) GetFormat() Format

GetFormat returns the format to use if the ConfFilename hasn't been explicitly set.

func (*Settings) GetFormatString 

func (s *Settings) GetFormatString() string

GetFormatString returns the format to use if the ConfFilename hasn't been explicitly set as a string

func (*Settings) Int 

func (s *Settings) Int(k string) int

Int returns the settings' value for k as an int. A 0 will be returned if k either doesn't exist or if its value is nat an int.

func (*Settings) Int64 

func (s *Settings) Int64(k string) int64

Int64 returns the settings value for k as an int64. A 0 will be returned if k doesn't exist or if its value is neither an int64 nor an int.

func (*Settings) Int64E 

func (s *Settings) Int64E(k string) (int64, error)

Int64E returns the settings value for k as an int64. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is neither an int64 nor an int.

func (*Settings) IntE 

func (s *Settings) IntE(k string) (int, error)

IntE returns the settings' value for k as an int. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not an int.

func (*Settings) Interface 

func (s *Settings) Interface(k string) interface{}

Interface returns the settings' value for k as an interface{}. A nil will be returned if k doesn't exist.

func (*Settings) InterfaceE 

func (s *Settings) InterfaceE(k string) (interface{}, error)

InterfaceE returns the settings' value for k as an interface{}. A SettingNotFoundError is returned if k doesn't exist.

func (*Settings) IsConfFileVar 

func (s *Settings) IsConfFileVar(k string) bool

IsConfFileVar returns if setting k is a ConfFileVar setting. False will be returned if k doesn't exist in settings.

func (*Settings) IsConfFileVarE 

func (s *Settings) IsConfFileVarE(k string) (bool, error)

IsConfFileVarE returns if setting k is a ConfFileVar setting. A SettingNotFoundErr will be returned if k doesn't exist in settings.

func (*Settings) IsCore 

func (s *Settings) IsCore(k string) bool

IsCore returns if setting k is a Core setting. False will be returned if k doesn't exist in settings.

func (*Settings) IsCoreE 

func (s *Settings) IsCoreE(k string) (bool, error)

IsCoreE returns if setting k is a Core setting. A SettingNotFoundErr will be returned if k doesn't exist in settings.

func (*Settings) IsEnvVar 

func (s *Settings) IsEnvVar(k string) bool

IsEnvVar returns if setting k is an EnvVar setting. False will be returned if k doesn't exist in settings.

func (*Settings) IsEnvVarE 

func (s *Settings) IsEnvVarE(k string) (bool, error)

IsEnvVarE returns if setting k is an EnvVar setting. A SettingNotFoundErr will be returned if k doesn't exist in settings.

func (*Settings) IsFlag 

func (s *Settings) IsFlag(k string) bool

IsFlag returns if setting k is a Flag setting. False will be returned if k doesn't exist in settings.

func (*Settings) IsFlagE 

func (s *Settings) IsFlagE(k string) (bool, error)

IsFlagE returns if setting k is a Flag setting. A SettingNotFoundErr will be returned if k doesn't exist in settings.

func (*Settings) IsSet 

func (s *Settings) IsSet() bool

IsSet returns if settings' configuration settings have been set from all of its configured sources.

func (*Settings) Name 

func (s *Settings) Name() string

Name returns settings' name.

func (*Settings) ParseFlags 

func (s *Settings) ParseFlags(args []string) ([]string, error)

ParseFlags parses the args for the settings. Only settings of type Flag can be set via ParseFlags. Flags have the highest precedence. After parsing, any non-flag args are returned to the caller and a list of flags in the args is cached.

If settings is not set to use flags, the args will be returned along with an ErrUseFlagsFalse. If settings has already parsed flags, the args are returned along with an ErrFlagsParsed.

All of settings' flags must be registered prior to calling ParseFlags.

func (*Settings) RegisterBoolConfFileVar 

func (s *Settings) RegisterBoolConfFileVar(k string, v bool) error

RegisterBoolConfFileVar registers a bool setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterBoolEnvVar 

func (s *Settings) RegisterBoolEnvVar(k string, v bool) error

RegisterBoolEnvVar registers a bool setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterBoolFlag 

func (s *Settings) RegisterBoolFlag(k, short string, v bool, dflt, usage string) error

RegisterBoolFlag registers a bool setting using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterInt64ConfFileVar 

func (s *Settings) RegisterInt64ConfFileVar(k string, v int64) error

RegisterInt64ConfFileVar registers an int64 setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterInt64EnvVar 

func (s *Settings) RegisterInt64EnvVar(k string, v int64) error

RegisterInt64EnvVar registers an int64 setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterInt64Flag 

func (s *Settings) RegisterInt64Flag(k, short string, v int64, dflt, usage string) error

RegisterInt64Flag registers an int64 setting using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) RegisterIntConfFileVar 

func (s *Settings) RegisterIntConfFileVar(k string, v int) error

RegisterIntConfFileVar registers an int setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterIntEnvVar 

func (s *Settings) RegisterIntEnvVar(k string, v int) error

RegisterIntEnvVar registers an int setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterIntFlag 

func (s *Settings) RegisterIntFlag(k, short string, v int, dflt, usage string) error

RegisterIntFlag registers an int setting using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) RegisterInterfaceConfFileVar 

func (s *Settings) RegisterInterfaceConfFileVar(k string, v interface{}) error

RegisterInterfaceConfFileVar registers an int setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterSetting 

func (s *Settings) RegisterSetting(typ, name, short string, value interface{}, dflt, usage string, IsCore, IsConfFileVar, IsEnvVar, IsFlag bool) error

RegisterSetting registers a setting. For most settings, the data and setting type specific registration and add functions should be used. The exception would be when more granular control over what can update a registered setting is needed. This method allows Is[ConfFileVar|EnvVar|Flag] bools to be set independently.

If a setting with the key k already exists, a SettingExistsError will be returned. If k is an empty string an ErrNoSettingName will be returned.

The short, dflt, and usage parms only apply to settings whose IsFlag bool is true.

For non-Core settings, IsCore must be false. If IsCore is true, k's value cannot be changed after registration, regardless of the truthiness of Is[ConfFileVar|IsEnvVar|IsFlag]. For Core settings, AddCore methods should be used.

If the setting can be updated by a configuration file, environment variable or a flag, the Is[ConfFileVar|IsEnv|IsFlag] bools should be set to true as appropriate. These conditionals are independent; e.g. a setting can have both IsConfFileVar and IsFlag set to true if the setting is not to be updateable from an environment variable.

If Is[Core|ConfFileVar|Env|Flag] are all false, the setting will only be updateable by using the Update methods. For these kind of settings, the usage of Add functions should be preferred. These setting will not be exposed to the configuration file, as an environment variable, or as a flag.

For non string, bool, int, and int64 types, the type must be "interface{}"

func (*Settings) RegisterStringConfFileVar 

func (s *Settings) RegisterStringConfFileVar(k, v string) error

RegisterStringConfFileVar registers a string setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterStringEnvVar 

func (s *Settings) RegisterStringEnvVar(k, v string) error

RegisterStringEnvVar registers a string setting using k for its key and v for its value. Once registered, the value of this setting can only be updated from a configuration file or an environment variable. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned.

func (*Settings) RegisterStringFlag 

func (s *Settings) RegisterStringFlag(k, short, v, dflt, usage string) error

RegisterStringFlag registers a string setting using k for its key and v for its value. Once registered, the value of this setting can be updated from a configuration file, an environment variable, or a flag. If k already exists a SettingExistsError will be returned. If k is empty, an ErrNoSettingName will be returned

func (*Settings) SearchPATH 

func (s *Settings) SearchPATH() bool

SearchPATH returns if settings should use the user's PATH environment variable to check for the configuratiom file.

func (*Settings) Set 

func (s *Settings) Set() error

Set updates the settings' configuration from a configuration file and environment variables. This is only run once; subsequent calls will result in no changes. Only settings that are of type ConfFileVar or EnvVar will be affected. This does not handle flags.

Once the standard settings has been set, updated, it will not update again; subsequent calls will result in nothing being done.

All ConfFileVar, EnvVar, and Flag settings must be registered before calling

func (*Settings) SetCheckExeDir 

func (s *Settings) SetCheckExeDir(b bool)

SetCheckExeDir sets if Settings should check the executable directory for the configuration file.

func (*Settings) SetCheckWD 

func (s *Settings) SetCheckWD(b bool)

SetCheckWD sets if settings should check the working directory for the configuration file.

func (*Settings) SetConfFilePathEnvVars 

func (s *Settings) SetConfFilePathEnvVars(envVars []string)

SetConfFilePathEnvVars sets the names of the environment variables that have paths that settings should check when looking for the configuration file. The environment variables will be checked in the order provided. The environment variables may contain multiple paths.

func (*Settings) SetConfFilePaths 

func (s *Settings) SetConfFilePaths(paths []string)

SetConfFilePaths sets the paths that settings should check when looking for the configuration file. The paths will be checked in the order provided.

func (*Settings) SetConfFilename 

func (s *Settings) SetConfFilename(v string) error

SetConfFilename sets the settings' configuration filename and configures settings to use a configuration file. If the filename is empty, an error is returned. If the filename's extension isn't parsable to a supported configuration format, an UnsupportedFormatError is returned.

func (*Settings) SetErrOnMissingConfFile 

func (s *Settings) SetErrOnMissingConfFile(b bool)

SetErrOnMissingConfFile sets if settings should return an error if the confiugration file cannot be located.

func (*Settings) SetFormat 

func (s *Settings) SetFormat(f Format)

SetFormat sets the format to use for the conffile if the ConfFilename hasn't been explicitly set.

func (*Settings) SetFormatString 

func (s *Settings) SetFormatString(v string) error

SetFormatString sets the format, using a string, to use for the configuration file if the ConfFilename hasn't been explicitly set. If the string isn't parsable to a supported Format, an UnsupportedFormatError will be returned.

func (*Settings) SetFromConfFile 

func (s *Settings) SetFromConfFile() error

SetFromConfFile updates the settings' configuration from the configuration file. If the configuration filename was not set using the SetConfFilename method, settings will look for the configuration file using the settings' name and it's format: name.format.

The format, in full, is used as the extension, i.e. JSON's extension will be 'json', TOML's extension will be 'toml', and YAML's extension will be 'yaml'.

Once the settings has been set, updated from the configuration file, they will not be updated again from the configuration file; subsequent calls will result in nothing being done.

The settings will look for the configuration file according to how it's been configured. 

filename
confFilePaths + filename
confFileEnvVars + filename (each env var may have multiple path elements)
working directory + filename
executable directory + filename
$PATH element + filename (PATH may have multiple path elements)

Any of the above elements that are either empty or false are skipped.

If the file cannot be found, an os.PathError with an os.ErrNotExist and a list of all paths checked is returned.

func (*Settings) SetFromEnvVars 

func (s *Settings) SetFromEnvVars() error

SetFromEnvVars updates the settings' configuration from environment variables.

Once the standard settings has been set, updated, from environment variables, they will not be updated again from environment variables; subsequent calls will result in nothing being done.

A setting's env name is a concatonation of the settings' name, an underscore (_), and the setting's key, e.g. given a settings with the name 'foo', a setting whose key is 'bar' will be updateable with the environment variable FOO_BAR.

func (*Settings) SetSearchPATH 

func (s *Settings) SetSearchPATH(b bool)

SetSearchPATH sets if settings should use the user's PATH environment variable to check for the configuratiom file.

func (*Settings) SetUsage 

func (s *Settings) SetUsage(f func())

SetUsage sets settings' Usage func.

func (*Settings) String 

func (s *Settings) String(k string) string

String returns the settings value for k as a string. An empty string, "", will be returned if k either doesn't exist or if its value is not a string.

func (*Settings) StringE 

func (s *Settings) StringE(k string) (string, error)

StringE returns the settings value for k as a string. A SettingNotFoundError is returned if k doesn't exist. A DataTypeError will be returned if the value is not a string.

func (*Settings) UpdateBool 

func (s *Settings) UpdateBool(k string, v bool) error

UpdateBool updates k with a boo, v. If settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func (*Settings) UpdateInt 

func (s *Settings) UpdateInt(k string, v int) error

UpdateInt updates k with an int, v. If settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func (*Settings) UpdateInt64 

func (s *Settings) UpdateInt64(k string, v int64) error

UpdateInt64 updates k with an int64, v. If settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func (*Settings) UpdateInterface 

func (s *Settings) UpdateInterface(k string, v interface{}) error

UpdateInterface updates k with an interface, v. If settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func (*Settings) UpdateString 

func (s *Settings) UpdateString(k, v string) error

UpdateString updates k with a string, v. If settings does not have a setting k, both a false and a SettingNotFoundError will be returned. If the setting k is not updateable, both a false and either a CoreUpdateError or an UpdateError will be returned.

func (*Settings) UseConfFile 

func (s *Settings) UseConfFile() bool

UseConfFile returns if settings will update its configuration settings from a configuration file.

func (*Settings) UseEnvVars 

func (s *Settings) UseEnvVars() bool

UseEnvVars returns if settings will update its configuration settings from environment variables.

func (*Settings) UseFlags 

func (s *Settings) UseFlags() bool

UseFlags returns if settings has any flags that can be updated using ParseFlags.

func (*Settings) Visited 

func (s *Settings) Visited() []string

Visited returns the names of all settings' flags that were set during flag parsing, in lexical order.

func (*Settings) WasVisited 

func (s *Settings) WasVisited(k string) bool

WasVisited returns if settings' flag k was processed during flag parsing.

type ShortFlagExistsError 

type ShortFlagExistsError struct {
	// contains filtered or unexported fields
}

ShortFlagExistsError occurs when registering a flag whose short flag already exists/

func (ShortFlagExistsError) Error 

func (e ShortFlagExistsError) Error() string

type UnsupportedFormatError 

type UnsupportedFormatError struct {
	// contains filtered or unexported fields
}

UnsupportedFormatError occurs when the string cannot be matched to a supported configuration format.

func NewUnsupportedFormatError 

func NewUnsupportedFormatError(s string) UnsupportedFormatError

NewUnsupportedFormatError returns an UnsupportedFormatError using the provided s.

func (UnsupportedFormatError) Error 

func (e UnsupportedFormatError) Error() string

type UpdateError 

type UpdateError struct {
	// contains filtered or unexported fields
}

UpdateError records information about an Update operation that results in an error that isn't neither a SettingNotFoundError nor a CoreUpdateError.

func (UpdateError) Error 

func (e UpdateError) Error() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.