Documentation
¶
Overview ¶
Package config provides a configuration system that registers a global service similar to the provider extension's context services. The config store is based on the Lookup interface and can retrieve values by qualified names delimited by periods, using a "dig" algorithm to traverse hierarchical names.
Index ¶
- Constants
- Variables
- func ContextValue(v contextValue) cli.Action
- func FlagsAndArgs() cli.Action
- func SetAdditionalFile(filename ...*cli.File) cli.Action
- func SetConfigDir(diropt ...string) cli.Action
- func SetProfile(name ...string) cli.Action
- func SetWorkingDir(diropt ...string) cli.Action
- func SetupWorkspace() cli.Action
- type Config
- func (c *Config) Apply(opts ...Option)
- func (c *Config) BigFloat(name any) *big.Float
- func (c *Config) BigInt(name any) *big.Int
- func (c *Config) Bool(name any) bool
- func (c *Config) Bytes(name any) []byte
- func (c *Config) Duration(name any) time.Duration
- func (c *Config) File(name any) *cli.File
- func (c *Config) FileSet(name any) *cli.FileSet
- func (c *Config) FindProfileNames(ctx context.Context) []string
- func (c *Config) Float32(name any) float32
- func (c *Config) Float64(name any) float64
- func (c *Config) Has(name any) bool
- func (c *Config) IP(name any) net.IP
- func (c *Config) Int(name any) int
- func (c *Config) Int8(name any) int8
- func (c *Config) Int16(name any) int16
- func (c *Config) Int32(name any) int32
- func (c *Config) Int64(name any) int64
- func (c *Config) Interface(name any) (any, bool)
- func (c *Config) List(name any) []string
- func (c *Config) Map(name any) map[string]string
- func (c *Config) NameValue(name any) *cli.NameValue
- func (c *Config) NameValues(name any) []*cli.NameValue
- func (c *Config) Paths(ctx context.Context) ([]string, error)
- func (c *Config) Pipeline() cli.Action
- func (c *Config) Profile() string
- func (c *Config) Regexp(name any) *regexp.Regexp
- func (c *Config) Resolve(opts Options) ([]IdiomaticLocation, error)
- func (c *Config) Store() Store
- func (c *Config) String(name any) string
- func (c *Config) URL(name any) *url.URL
- func (c *Config) Uint(name any) uint
- func (c *Config) Uint8(name any) uint8
- func (c *Config) Uint16(name any) uint16
- func (c *Config) Uint32(name any) uint32
- func (c *Config) Uint64(name any) uint64
- func (c *Config) Value(name any) any
- type IdiomaticLocation
- type IdiomaticLocationProvider
- type Layer
- type Loader
- type Location
- type Option
- type Options
- type Store
- type Workspace
- func (w *Workspace) Apply(opts ...WorkspaceOption)
- func (w *Workspace) ConfigDir() string
- func (w *Workspace) Dir() string
- func (w *Workspace) FS() fs.FS
- func (w *Workspace) Files(diropt ...string) iter.Seq2[string, fs.DirEntry]
- func (w *Workspace) LoadFiles(diropt ...string) iter.Seq[any]
- func (w *Workspace) Pipeline() cli.Action
- type WorkspaceFileLoaderFunc
- type WorkspaceFinder
- type WorkspaceOption
Constants ¶
const ( BigFloat = marshal.BigFloat BigInt = marshal.BigInt Bool = marshal.Bool Bytes = marshal.Bytes Duration = marshal.Duration File = marshal.File FileSet = marshal.FileSet Float32 = marshal.Float32 Float64 = marshal.Float64 Int = marshal.Int Int16 = marshal.Int16 Int32 = marshal.Int32 Int64 = marshal.Int64 Int8 = marshal.Int8 IP = marshal.IP List = marshal.List Map = marshal.Map NameValue = marshal.NameValue NameValues = marshal.NameValues Regexp = marshal.Regexp String = marshal.String Uint = marshal.Uint Uint16 = marshal.Uint16 Uint32 = marshal.Uint32 Uint64 = marshal.Uint64 Uint8 = marshal.Uint8 URL = marshal.URL )
The various types that the configuration system supports
Variables ¶
var SkipFile = errors.New("skip this file")
SkipFile is returned by the walker function to indicate a file should not be returned during the workspace scan
Functions ¶
func ContextValue ¶
ContextValue provides an action that sets the given value into the context. The only supported type is *Workspace.
func FlagsAndArgs ¶ added in v0.14.1
FlagsAndArgs is an action which provides the default flags to the application. Despite its name, which is conventianal, this action provides no args.
func SetAdditionalFile ¶ added in v0.14.2
SetAdditionalFile sets an additional file in the configuration
func SetConfigDir ¶ added in v0.14.2
SetConfigDir sets the workspace config directory as an action. When it is used within the Uses pipeline, it initializes reasonable defaults for a flag and will set the directory within the workspace in the Before timing. The flag will either use the directory specified by diropt or its own value if diropt is not specified.
func SetProfile ¶ added in v0.14.1
SetProfile sets up the profile and provides reasonable defaults for initializing a flag.
func SetWorkingDir ¶
SetWorkingDir sets the current directory. It is typical within apps that work with workspaces to allow the user to set the current directory. \
func SetupWorkspace ¶
SetupWorkspace provides the action that sets up the workspace, which locks in the workspace directories.
Types ¶
type Config ¶ added in v0.14.1
type Config struct {
// Action specifies the action which defines the action to run when this value
// is added to a pipeline. Typically, this is an initializer set via WithDefaultAction
cli.Action
// contains filtered or unexported fields
}
Config provides the configuration system, typically retrieved from the context.
func FromContext ¶ added in v0.14.1
FromContext retrieves the configuration store from the context
func (*Config) FindProfileNames ¶ added in v0.14.1
FindProfileNames detects the profiles
func (*Config) NameValue ¶ added in v0.14.1
NameValue obtains the value and converts it to a name-value pair
func (*Config) NameValues ¶ added in v0.14.1
NameValues obtains the value and converts it to a list of name-value pairs
func (*Config) Pipeline ¶ added in v0.14.1
Pipeline retrieves the configuration action as a pipeline
func (*Config) Resolve ¶ added in v0.14.1
func (c *Config) Resolve(opts Options) ([]IdiomaticLocation, error)
Resolve determines the locations of config in terms of idiomaitic locations, if available
type IdiomaticLocation ¶ added in v0.14.0
type IdiomaticLocation interface {
Location
// Layer gets the layer where the location is found
Layer() Layer
// OS gets the operating system the location supports
OS() string
// Arch gets the architecture the location supports
Arch() string
}
IdiomaticLocation defines a location which exists in a particular layer
type IdiomaticLocationProvider ¶ added in v0.14.1
type IdiomaticLocationProvider interface {
Location
// Resolve determines the locations
Resolve(Options) ([]IdiomaticLocation, error)
// FindProfileNames locates available profile names
FindProfileNames(context.Context) []string
}
IdiomaticLocationProvider provides an interface for how idiomatic locations are detected
type Layer ¶ added in v0.14.0
type Layer int
Layer identifies layers in the configuration system
type Location ¶ added in v0.14.0
type Location interface {
// Paths resolves the file paths for this location
Paths(context.Context) ([]string, error)
}
Location defines a representation of configuration file locations
func ParseLocation ¶ added in v0.14.2
ParseLocation parses a location string and returns the corresponding Location implementation. The location type is determined by the suffix of the input string:
- Ending with "/" indicates a directory location (enumerates files in the directory)
- Ending with "/..." indicates a directory tree location (walks entire hierarchy)
- No special suffix indicates a file location
All locations support environment variable expansion. In addition to OS env vars, these special variables are supported:
- cli:app - the app name
- cli:workspace - the workspace directory
- cli:workspace.config - the workspace ConfigDir directory
- GOOS - populated from runtime.GOOS
- GOARCH - populated from runtime.GOARCH
If a variable cannot be resolved (e.g., no workspace in context), the path will not be yielded from Paths.
type Option ¶ added in v0.14.1
Option defines an option for initialization of the configuration.
func AddAdditionalFile ¶ added in v0.14.2
AddAdditionalFile adds an additional file to load
func WithAction ¶ added in v0.14.1
WithAction sets the Action to use
func WithDefaultAction ¶ added in v0.14.1
func WithDefaultAction() Option
WithDefaultAction sets the default action
func WithLocation ¶ added in v0.14.1
WithLocation sets the configuration location to use
func WithProfile ¶ added in v0.14.1
WithProfile sets the profile name
type Options ¶ added in v0.14.1
type Options struct {
// Profile names the profile to load
Profile string
// AdditionalFiles specifies additional configuration files to load
AdditionalFiles []string
}
Options provides the options for the configuration system
type Store ¶ added in v0.14.0
Store provides configuration storage based on the Lookup interface. It retrieves values by qualified names delimited by periods, using a "dig" algorithm to traverse hierarchical names.
type Workspace ¶
type Workspace struct {
// Action provides the action to provide when the workspace is
// added to a pipeline.
cli.Action
// contains filtered or unexported fields
}
Workspace provides the root directory of a project-specific workspace. The workspace provides two capabilities:
- The workspace finder locates the root directory of a project. By default, the workspace is found by searching up the directory hierarchy until it finds a directory which contains a configuration sentinel, typically a directory which the same name as the app with a leading period. For example, this is what Git does when it finds the .git directory.
- The workspace can load files. These files could be application files or configuration files.
func NewWorkspace ¶
func NewWorkspace(opts ...WorkspaceOption) *Workspace
NewWorkspace creates a workspace with the default action, which registers the flags and adds the workspace to the context.
func WorkspaceFromContext ¶
WorkspaceFromContext gets the Workspace from the context otherwise panics
func (*Workspace) Apply ¶
func (w *Workspace) Apply(opts ...WorkspaceOption)
Apply applies options to the workspace
func (*Workspace) ConfigDir ¶
ConfigDir gets the directory where configuration is stored. Typically, this has the same name as the app with a leading dot, e.g. $WORKSPACE_DIR/.app.
func (*Workspace) Dir ¶
Dir gets the workspace directory, which is the root of all content in the workspace. The directory is set to the current working directory at the time the app starts, sometime in the Before pipeline.
func (*Workspace) Files ¶
Files enumerates all files in the workspace which match the filters. The result contains the name of the file and a io/fs.DirEntry.
func (*Workspace) LoadFiles ¶
LoadFiles loads all files in the workspace which match the filters. This method is good for a single pass, not dynamic workspaces where files are expected to change while the app is running. The type of the items returned from this depend upon what was set as the loader. When no loader is set, the result will be fs.File.
type WorkspaceFileLoaderFunc ¶
WorkspaceFileLoaderFunc defines the function for loading files in a workspace.
type WorkspaceFinder ¶
type WorkspaceFinder interface {
// FindWorkspacePath locates the workspace. Param cwd represents the
// the current working directory
FindWorkspacePath(c context.Context, f fs.FS, cwd string) (string, error)
}
WorkspaceFinder locates the workspace
var DefaultWorkspaceFinder WorkspaceFinder = new(defaultWorkspaceFinder)
DefaultWorkspaceFinder provides the default logic for finding a workspace
type WorkspaceOption ¶
WorkspaceOption provides an option for setting up the Workspace. This is also a cli.Action, which means it can be used within pipelines. Typically, when used within the Action pipeline, it sets the option on the workspace. When used within the Uses pipeline, it may also configure a flag or other behavior.
func WithConfigDir ¶
func WithConfigDir(dir string) WorkspaceOption
WithConfigDir sets the workspace config directory. This can be used as an option to NewWorkspace or Workspace.Apply, but when it is, the diropt must be specified. It can also be used as an Action.
func WithFS ¶
func WithFS(f fs.FS) WorkspaceOption
WithFS specifies the file system to use for the workspace. By default, the workspace with use os.DirFS corresponding to the workspace directory.
func WithFileLoader ¶
func WithFileLoader(loader WorkspaceFileLoaderFunc) WorkspaceOption
WithFileLoader is an option that determines how to read files in a workspace.
func WithFinder ¶
func WithFinder(finder WorkspaceFinder) WorkspaceOption
WithFinder is an option that determines how to finder the workspace
func WithWalkDirFunc ¶
func WithWalkDirFunc(fn fs.WalkDirFunc) WorkspaceOption
WithWalkDirFunc specifies the function that walks the directory for files. The function is used in a call to io/fs.WalkDir, where it can return io/fs.SkipDir and io/fs.SkipAll, with the same behavior. It can also return SkipFile introduced by this package to indicate that a file is skipped in the result of the Workspace.Files and Workspace.LoadFiles methods.
Source Files