configengine

package
v0.12.0 Latest Latest
Warning

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

Go to latest
Published: Nov 20, 2026 License: MIT Imports: 19 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func EnvCandidates

func EnvCandidates(envPrefix string, cmd *spec.Command, decoderRegistered bool) []string

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

func EnvKeys(envPrefix string, cmd *spec.Command, decoderRegistered bool) []string

EnvKeys returns the environment variables that can carry configuration file targets (spec.ConfigEnvVars): the ConfigFile's own variables when one is declared, otherwise <PREFIX>_CONFIG for an app with a registered decoder (decoderRegistered), otherwise none.

func SplitList

func SplitList(value string, separator string) []string

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

type Decoder func(data []byte) (map[string]any, error)

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

func (r *Registry) Decoder(extension string) Decoder

Decoder returns the registered decoder for a file extension, or nil if none is registered.

func (*Registry) Extensions

func (r *Registry) Extensions() []string

Extensions returns the sorted decoder file extensions registered in the registry.

func (*Registry) Register

func (r *Registry) Register(extension string, decoder Decoder)

Register adds or replaces the decoder for a file extension (e.g. ".json", ".toml").

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

func (r Resolver) CandidatePaths(flagPaths []string, cmd *spec.Command) []string

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

func (r Resolver) ConfigExamples(candidates []string, tiers []string, extensions []string) []string

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

func (r Resolver) EffectiveSearchPaths() []string

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

func (r Resolver) ProbedFiles(candidate string, extensions []string) []string

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

func (r Resolver) SkippedTargets(flagTargets []string, cmd *spec.Command) []string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL