configengine

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 20 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) []string

EnvCandidates returns the expanded candidate configuration paths named by the first set configuration environment variable, or nil when none is set.

func EnvKeys

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

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

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(explicitPaths []string, cmd *spec.Command) []string

CandidatePaths returns the expanded candidate configuration paths evaluated for an invocation, in reported precedence order: explicit paths when named, otherwise the configuration environment variable targets, otherwise the search tier plus the explicit option path.

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, 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(explicitTargets []string, cmd *spec.Command) ([]string, *configdata.Data, container.Source, error)

Resolve resolves, loads, and validates the effective configuration files. Explicit targets (CLI flag values, the configuration environment variable, or the explicit option) 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.

Jump to

Keyboard shortcuts

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