Documentation
¶
Overview ¶
Package configengine implements the configuration-file resolution engine shared by the root conga package: decoder registration, search-tier probing, strict content validation, and the per-invocation Resolver that turns those pieces into loaded files.
Index ¶
- func EnvCandidates(envPrefix string, cmd *spec.Command) []string
- func EnvKeys(envPrefix string, cmd *spec.Command) []string
- func SplitList(value string, separator string) []string
- func ValidateDocument(rawMap map[string]any, cmd *spec.Command, dest *configdata.Data, ...) error
- type Decoder
- type Registry
- type Resolver
- func (r Resolver) CandidatePaths(flagPaths []string, cmd *spec.Command) []string
- func (r Resolver) ConfigExamples(candidates []string, tiers []string, extensions []string) []string
- func (r Resolver) EffectiveSearchPaths() []string
- func (r Resolver) ProbedFiles(candidate string, extensions []string) []string
- func (r Resolver) Resolve(flagTargets []string, cmd *spec.Command) ([]string, *configdata.Data, container.Source, error)
- func (r Resolver) SkippedTargets(flagTargets []string, cmd *spec.Command) []string
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnvCandidates ¶
EnvCandidates returns the expanded candidate configuration paths named by the first set configuration environment variable, split by the same rule resolution applies, or nil when none is set.
func EnvKeys ¶
EnvKeys returns the environment variables that can carry configuration file targets: the config-file flag's declared env tags, or the global `<PREFIX>_CONFIG` variable.
func SplitList ¶
SplitList splits a configuration list value (an environment variable payload or a multi-value flag entry) by the configured separator, defaulting to a comma. The "none", "off", and "-" separators disable splitting and yield the whitespace-trimmed value as a single item; blank values and empty split items are dropped.
func ValidateDocument ¶
func ValidateDocument(rawMap map[string]any, cmd *spec.Command, dest *configdata.Data, origin, scope string) error
ValidateDocument validates one programmatic configuration document entry against the Command AST and populates dest with the resolved values, exactly as a decoded file entry is validated. rawMap holds one top-level document key in the decoder output shape (a scalar, a slice, or a nested map for sections and map flags); origin labels the value's provenance in stored values and validation errors, and may be any free-form application-supplied source label. scope optionally names a region within origin.
Types ¶
type Decoder ¶
Decoder parses raw configuration bytes into the generic key-value map validated against the Command AST during configuration resolution.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds one application's locally registered configuration decoders.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry returns an empty per-application decoder registry.
func (*Registry) Decoder ¶
Decoder returns the registered decoder for a file extension, or nil if none is registered.
func (*Registry) Extensions ¶
Extensions returns the sorted decoder file extensions registered in the registry.
type Resolver ¶
type Resolver struct {
// AppName is the resolved application name used for conventional XDG probing.
AppName string
// EnvPrefix is the global environment variable prefix (including any trailing underscore).
EnvPrefix string
// Settings carries the app-level resolution mode declared via the root conga
// ConfigOptions options.
Settings spec.ConfigSettings
// Registry supplies the registered configuration decoders.
Registry *Registry
}
Resolver resolves and loads configuration files for one application invocation. It maps author settings, decoder registrations, and CLI or environment targets onto concrete files, validates their contents against the command schema, and reports where the effective values came from.
func (Resolver) CandidatePaths ¶
CandidatePaths returns the expanded candidate configuration paths evaluated for an invocation, in reported precedence order: the config-file flag paths when named, otherwise the configuration environment variable targets, otherwise the explicit option path, otherwise the search tier.
func (Resolver) ConfigExamples ¶
ConfigExamples suggests example configuration file locations the user can create for the application to see, derived from the first search-path tier (the highest-precedence tier): the in-directory candidates, plus the stem sibling when the tier path is not an existing directory, deduplicated. Returns nil when no search tier participates in the candidate list.
func (Resolver) EffectiveSearchPaths ¶
EffectiveSearchPaths returns the search paths driving configuration file resolution: the author-declared tier when present, otherwise the built-in conventional tier (${XDG_CONFIG_HOME:-~/.config}/<app-name>), or nil when the tier is unavailable — the application name cannot be resolved, or no configuration decoder is registered (config-incapable apps never touch the filesystem).
func (Resolver) ProbedFiles ¶
ProbedFiles lists the concrete configuration file locations resolution probes for one search-path tier: an existing directory probes the generic "config" stem and the application name stem (when resolvable) inside the directory, a missing path is probed as a stem sibling of the tier, and both are extended by every registered decoder extension. An existing file is resolved as a whole path and yields no probed locations. All locations are reported as full paths.
func (Resolver) Resolve ¶
func (r Resolver) Resolve(flagTargets []string, cmd *spec.Command) ([]string, *configdata.Data, container.Source, error)
Resolve resolves, loads, and validates the effective configuration files. Named targets resolve in precedence order: the config-file flag paths, then the configuration environment variable, then the explicit option. The first that names a path is used, and each path it names must exist and be readable: a named path that is missing is a fatal error. Tier paths are probed opportunistically: the first existing file wins, or — in cascading mode — every existing file is collected in precedence order (lowest to highest) for merging. Returns the loaded paths, the validated configuration data, and the value source; an empty file set yields a source of SourceNone.
func (Resolver) SkippedTargets ¶ added in v0.9.0
SkippedTargets returns the named configuration targets that were set but lost to a higher-precedence named source, as the expanded paths resolution would have loaded: the environment variable and explicit option paths when the config-file flag names paths, and the explicit option path when the environment variable does. Skipped paths are never opened. Search-path tiers are not named targets and are never reported. Returns nil when no named source lost.