config

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2026 License: BSD-3-Clause Imports: 25 Imported by: 0

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

View Source 
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

View Source 
const DefaultWorkspaceFinder defaultWorkspaceFinder = iota

DefaultWorkspaceFinder provides the default logic for finding a workspace

Variables

View Source 
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 

func ContextValue(v contextValue) cli.Action

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 

func FlagsAndArgs() cli.Action

FlagsAndArgs is an action which provides the default flags to the application. Despite its name, which is conventianal, this action provides no args.

func Load added in v0.15.0 

func Load() cli.Action

Load loads the configuration, returning an error if it fails to load. Any binding that reads from the configuration store should wait until loading is completed, which ensures that the load error happens as early as possible and not in the context of a specific value being consumed.

func PrintEnv added in v0.17.0 

func PrintEnv(vars ...string) cli.Action

PrintEnv prints out the environment, optionally specifying the vars to print out. When used in the Uses pipeline, it also provides useful initialization to the command it is used on.

func Reload added in v0.15.0 

func Reload() cli.Action

Reload loads the configuration or reloads it.

func SetAdditionalFile added in v0.14.2 

func SetAdditionalFile(filename ...*cli.File) cli.Action

SetAdditionalFile sets an additional file in the configuration

func SetConfigDir added in v0.14.2 

func SetConfigDir(diropt ...string) cli.Action

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 SetEnvValue added in v0.15.0 

func SetEnvValue(nv ...*cli.NameValue) cli.Action

SetEnvValue sets an additional value in the configuration

func SetProfile added in v0.14.1 

func SetProfile(name ...string) cli.Action

SetProfile sets up the profile and provides reasonable defaults for initializing a flag.

func SetValue added in v0.15.0 

func SetValue(nv ...*cli.NameValue) cli.Action

SetValue sets a configuration value in the configuration

func SetWorkingDir 

func SetWorkingDir(diropt ...string) cli.Action

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 

func SetupWorkspace() cli.Action

SetupWorkspace provides the action that sets up the workspace, which locks in the workspace directories. 

func SetupWorkspaceLink() cli.Action

SetupWorkspaceLink ensures a link between the workspace and Config. It should be present in the initializer action of both. It is part of the default action for both.

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 

func FromContext(ctx context.Context) *Config

FromContext retrieves the configuration store from the context

func New added in v0.14.1 

func New(opts ...Option) *Config

New creates a new configuration within the context By default, adding the Config to the pipeline adds it as a context service, which is required for most use cases, adds flags, and loads the configuration.

func (*Config) Apply added in v0.14.1 

func (c *Config) Apply(opts ...Option)

Apply will apply the given options to the config

func (*Config) BigFloat added in v0.14.1 

func (c *Config) BigFloat(name any) *big.Float

BigFloat obtains the BigFloat for the specified name

func (*Config) BigInt added in v0.14.1 

func (c *Config) BigInt(name any) *big.Int

BigInt obtains the BigInt for the specified name

func (*Config) Bool added in v0.14.1 

func (c *Config) Bool(name any) bool

Bool obtains the value and converts it to a bool

func (*Config) Bytes added in v0.14.1 

func (c *Config) Bytes(name any) []byte

Bytes obtains the bytes for the specified name

func (*Config) Duration added in v0.14.1 

func (c *Config) Duration(name any) time.Duration

Duration obtains the Duration for the specified name

func (*Config) File added in v0.14.1 

func (c *Config) File(name any) *cli.File

File obtains the File for the specified name

func (*Config) FileSet added in v0.14.1 

func (c *Config) FileSet(name any) *cli.FileSet

FileSet obtains the FileSet for the specified name

func (*Config) FindProfileNames added in v0.14.1 

func (c *Config) FindProfileNames(ctx context.Context) []string

FindProfileNames detects the profiles

func (*Config) Float32 added in v0.14.1 

func (c *Config) Float32(name any) float32

Float32 obtains the float32 for the specified name

func (*Config) Float64 added in v0.14.1 

func (c *Config) Float64(name any) float64

Float64 obtains the float64 for the specified name

func (*Config) Has added in v0.14.1 

func (c *Config) Has(name any) bool

Has determines whether the configuration value exists

func (*Config) IP added in v0.14.1 

func (c *Config) IP(name any) net.IP

IP obtains the IP for the specified name

func (*Config) Int added in v0.14.1 

func (c *Config) Int(name any) int

Int obtains the int for the specified name

func (*Config) Int8 added in v0.14.1 

func (c *Config) Int8(name any) int8

Int8 obtains the int8 for the specified name

func (*Config) Int16 added in v0.14.1 

func (c *Config) Int16(name any) int16

Int16 obtains the int16 for the specified name

func (*Config) Int32 added in v0.14.1 

func (c *Config) Int32(name any) int32

Int32 obtains the int32 for the specified name

func (*Config) Int64 added in v0.14.1 

func (c *Config) Int64(name any) int64

Int64 obtains the int64 for the specified name

func (*Config) Interface added in v0.14.1 

func (c *Config) Interface(name any) (any, bool)

Interface obtains the raw value without dereferencing

func (*Config) List added in v0.14.1 

func (c *Config) List(name any) []string

List obtains the value and converts it to a string slice

func (*Config) Load added in v0.15.0 

func (c *Config) Load(ctx context.Context) (Store, error)

Load loads the configuration if it has not been loaded yet. If it has, the error returned may be a cached result from a previous failure.

func (*Config) Map added in v0.14.1 

func (c *Config) Map(name any) map[string]string

Map obtains the map for the specified name

func (*Config) NameValue added in v0.14.1 

func (c *Config) NameValue(name any) *cli.NameValue

NameValue obtains the value and converts it to a name-value pair

func (*Config) NameValues added in v0.14.1 

func (c *Config) NameValues(name any) []*cli.NameValue

NameValues obtains the value and converts it to a list of name-value pairs

func (*Config) Paths added in v0.14.1 

func (c *Config) Paths(ctx context.Context) ([]string, error)

Paths resolves the file paths for config

func (*Config) Pipeline added in v0.14.1 

func (c *Config) Pipeline() cli.Action

Pipeline retrieves the configuration action as a pipeline

func (*Config) Profile added in v0.14.1 

func (c *Config) Profile() string

Profile retrieves the profile name

func (*Config) Regexp added in v0.14.1 

func (c *Config) Regexp(name any) *regexp.Regexp

Regexp obtains the Regexp for the specified name

func (*Config) Reload added in v0.15.0 

func (c *Config) Reload(ctx context.Context) error

Reload loads the configuration or reloads it. This operation does not re-apply bindings that may have been setup.

func (*Config) Resolve added in v0.14.1 

func (c *Config) Resolve() ([]IdiomaticLocation, error)

Resolve determines the locations of config in terms of idiomaitic locations, if available

func (*Config) Store added in v0.14.1 

func (c *Config) Store() Store

Store provides the configuration store

func (*Config) String added in v0.14.1 

func (c *Config) String(name any) string

String obtains the value and converts it to a string

func (*Config) URL added in v0.14.1 

func (c *Config) URL(name any) *url.URL

URL obtains the URL for the specified name

func (*Config) Uint added in v0.14.1 

func (c *Config) Uint(name any) uint

Uint obtains the uint for the specified name

func (*Config) Uint8 added in v0.14.1 

func (c *Config) Uint8(name any) uint8

Uint8 obtains the uint8 for the specified name

func (*Config) Uint16 added in v0.14.1 

func (c *Config) Uint16(name any) uint16

Uint16 obtains the uint16 for the specified name

func (*Config) Uint32 added in v0.14.1 

func (c *Config) Uint32(name any) uint32

Uint32 obtains the uint32 for the specified name

func (*Config) Uint64 added in v0.14.1 

func (c *Config) Uint64(name any) uint64

Uint64 obtains the uint64 for the specified name

func (*Config) Value added in v0.14.1 

func (c *Config) Value(name any) any

Value obtains the value and converts it to Value

func (*Config) Workspace added in v0.15.0 

func (c *Config) Workspace() *Workspace

Workspace obtains the workspace which was encountered when a workspace was initialized. The Config and the Workspace can be initialized in either order to ensure a linkage that is returned from this method. The function SetupWorkspaceLink returns the action that ensures this link and it is available from the default action.

type EnvMap added in v0.17.0 

type EnvMap map[string]string

EnvMap provides a basic implementation of EnvProvider using a map

func (EnvMap) Environ added in v0.17.0 

func (m EnvMap) Environ() iter.Seq2[string, string]

Environ obtains the environment variables from the map

type EnvProvider added in v0.17.0 

type EnvProvider interface {

	// Environ obtains the environment variables
	Environ() iter.Seq2[string, string]
}

EnvProvider provides the environment of a workspace, which is generally a set of environment variables that the workspace either depends upon or implicitly defines for its configuration behavior.

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 

const (
	LayerUnspecified Layer = -1
	LayerIntrinsic   Layer = 0
	LayerSystem      Layer = 2
	LayerUser        Layer = 4
	LayerWorkspace   Layer = 6
	LayerProfile     Layer = 8
	LayerAdditional  Layer = 10
)

Layers where a location exists

func (Layer) String added in v0.14.0 

func (l Layer) String() string

type Loader added in v0.14.0 

type Loader interface {
	Load(context.Context) (Store, error)
}

Loader loads 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 

func ParseLocation(s string) Location

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:cache - the user cache directory for the app
  • 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 

type Option interface {
	cli.Action
	// contains filtered or unexported methods
}

Option defines an option for initialization of the configuration.

func AddAdditionalFile added in v0.14.2 

func AddAdditionalFile(filename string) Option

AddAdditionalFile adds an additional file to load

func WithAction added in v0.14.1 

func WithAction(v cli.Action) Option

WithAction sets the Action to use

func WithDefaultAction added in v0.14.1 

func WithDefaultAction() Option

WithDefaultAction sets the default action

func WithEnvValue added in v0.15.0 

func WithEnvValue(name string, envvar string) Option

WithEnvValue sets a configuration value via env var

func WithLoader added in v0.15.0 

func WithLoader(l Loader) Option

WithLoader specifies a loader that can be used to generate the store.

func WithLocation added in v0.14.1 

func WithLocation(l Location) Option

WithLocation sets the configuration location to use

func WithProfile added in v0.14.1 

func WithProfile(name string) Option

WithProfile sets the profile name

func WithStore added in v0.14.1 

func WithStore(s Store) Option

WithStore sets the configuration store to use

func WithValue added in v0.15.0 

func WithValue(name, value string) Option

WithValue sets a configuration value

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

	// Values were specified as additional values at the command line
	Values []Value
}

Options provides the options for the configuration system

type ReloadableStore added in v0.15.0 

type ReloadableStore interface {
	Store

	// Reload will reload the store in place. Generally, clients don't call
	// this method directly. Use Config.Reload which will provide the appropriate
	// services to the context.
	Reload(context.Context) error
}

ReloadableStore provides a store which can be reloaded.

type Store added in v0.14.0 

type Store interface {
	cli.Lookup
	Has(name any) bool
}

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.

func FromValues added in v0.15.0 

func FromValues(values ...Value) (Store, error)

FromValues creates a store from the specified values

func NewStore added in v0.15.0 

func NewStore(base cli.Lookup, has func(string) bool) Store

NewStore provides a store that wraps a lookup

type Value added in v0.15.0 

type Value struct {
	Name    string
	Value   string
	FromEnv bool
}

Value represents a value specified for configuration

type Values added in v0.15.0 

type Values map[string]string

Values provides a config Store which uses simple key-value pairs typed as strings. The underlying lookup automatically provides conversions.

func (Values) BigFloat added in v0.15.0 

func (v Values) BigFloat(k any) *big.Float

func (Values) BigInt added in v0.15.0 

func (v Values) BigInt(k any) *big.Int

func (Values) Bool added in v0.15.0 

func (v Values) Bool(k any) bool

func (Values) Bytes added in v0.15.0 

func (v Values) Bytes(k any) []byte

func (Values) Duration added in v0.15.0 

func (v Values) Duration(k any) time.Duration

func (Values) File added in v0.15.0 

func (v Values) File(k any) *cli.File

func (Values) FileSet added in v0.15.0 

func (v Values) FileSet(k any) *cli.FileSet

func (Values) Float32 added in v0.15.0 

func (v Values) Float32(k any) float32

func (Values) Float64 added in v0.15.0 

func (v Values) Float64(k any) float64

func (Values) Has added in v0.15.0 

func (v Values) Has(k any) bool

func (Values) IP added in v0.15.0 

func (v Values) IP(k any) net.IP

func (Values) Int added in v0.15.0 

func (v Values) Int(k any) int

func (Values) Int8 added in v0.15.0 

func (v Values) Int8(k any) int8

func (Values) Int16 added in v0.15.0 

func (v Values) Int16(k any) int16

func (Values) Int32 added in v0.15.0 

func (v Values) Int32(k any) int32

func (Values) Int64 added in v0.15.0 

func (v Values) Int64(k any) int64

func (Values) Interface added in v0.15.0 

func (v Values) Interface(k any) (any, bool)

func (Values) List added in v0.15.0 

func (v Values) List(k any) []string

func (Values) Map added in v0.15.0 

func (v Values) Map(k any) map[string]string

func (Values) NameValue added in v0.15.0 

func (v Values) NameValue(k any) *cli.NameValue

func (Values) NameValues added in v0.15.0 

func (v Values) NameValues(k any) []*cli.NameValue

func (Values) Regexp added in v0.15.0 

func (v Values) Regexp(k any) *regexp.Regexp

func (Values) String added in v0.15.0 

func (v Values) String(k any) string

func (Values) URL added in v0.15.0 

func (v Values) URL(k any) *url.URL

func (Values) Uint added in v0.15.0 

func (v Values) Uint(k any) uint

func (Values) Uint8 added in v0.15.0 

func (v Values) Uint8(k any) uint8

func (Values) Uint16 added in v0.15.0 

func (v Values) Uint16(k any) uint16

func (Values) Uint32 added in v0.15.0 

func (v Values) Uint32(k any) uint32

func (Values) Uint64 added in v0.15.0 

func (v Values) Uint64(k any) uint64

func (Values) Value added in v0.15.0 

func (v Values) Value(k any) any

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:

  1. 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.
  2. 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 

func WorkspaceFromContext(ctx context.Context) *Workspace

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 

func (w *Workspace) ConfigDir() string

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 

func (w *Workspace) Dir() string

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) Env added in v0.17.0 

func (w *Workspace) Env() iter.Seq2[string, string]

Env obtains the workspace environment

func (*Workspace) FS 

func (w *Workspace) FS() fs.FS

FS gets the file system that represents the workspace.

func (*Workspace) Files 

func (w *Workspace) Files(diropt ...string) iter.Seq2[string, fs.DirEntry]

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) FprintEnv added in v0.17.0 

func (w *Workspace) FprintEnv(out io.Writer, vars ...string) error

FprintEnv prints the environment to the specified writer. If any variable is named then just its value is printed. However, if no variables are named then all are printed out using the syntax of shell variable assignment for the operating system.

func (*Workspace) Getenv added in v0.17.0 

func (w *Workspace) Getenv(name string) string

Getenv looks up a name in the workspace Env

func (*Workspace) LoadFiles 

func (w *Workspace) LoadFiles(diropt ...string) iter.Seq[any]

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.

func (*Workspace) Pipeline added in v0.14.0 

func (w *Workspace) Pipeline() cli.Action

Pipeline obtains the pipeline for initializing the workspace

func (*Workspace) PrintEnv added in v0.17.0 

func (w *Workspace) PrintEnv(vars ...string) error

PrintEnv prints the environment. If any variable is named then just its value is printed. However, if no variables are named then all are printed out using the syntax of shell variable assignment for the operating system.

type WorkspaceFileLoaderFunc 

type WorkspaceFileLoaderFunc func(root fs.FS, name string, d fs.DirEntry) (any, error)

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

type WorkspaceOption 

type WorkspaceOption interface {
	cli.Action
	// contains filtered or unexported methods
}

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 WithEnvProvider added in v0.17.0 

func WithEnvProvider(env EnvProvider) WorkspaceOption

WithEnvProvider sets the environment provider on the workspace

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

View all Source files

Directories

Path Synopsis
Code generated by counterfeiter.
 Code generated by counterfeiter.

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.