Documentation
¶
Overview ¶
Package appconfig provides a small, incremental facade for parsing configuration into typed application settings.
The initial implementation is intentionally not “struct-first” in the sense of deriving layers from structs. Instead, callers explicitly register Glazed ParameterLayers and bind them to fields inside a grouped settings struct T.
See CONFIG-PARSER-001 for the design and implementation diary.
Index ¶
- type LayerSlug
- type Parser
- type ParserOption
- func WithCobra(cmd *cobra.Command, args []string) ParserOption
- func WithConfigFiles(files ...string) ParserOption
- func WithDefaults() ParserOption
- func WithEnv(prefix string) ParserOption
- func WithMiddlewares(middlewares ...cmd_middlewares.Middleware) ParserOption
- func WithProfile(appName string, opts ...ProfileOption) ParserOption
- func WithValuesForLayers(values map[string]map[string]interface{}) ParserOption
- type ProfileOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LayerSlug ¶
type LayerSlug string
LayerSlug is a distinct type to encourage declaring layer slugs as constants.
Example:
const RedisSlug appconfig.LayerSlug = "redis"
type Parser ¶
type Parser[T any] struct { // contains filtered or unexported fields }
Parser is an incremental config boundary: - callers register layers and bind them to sub-struct pointers inside T - Parse executes a configurable middleware chain and returns a populated T.
V1 hydration uses ParsedLayers.InitializeStruct, which means fields are only populated when the destination structs have explicit `glazed.parameter` tags.
func NewParser ¶
func NewParser[T any](options ...ParserOption) (*Parser[T], error)
NewParser constructs a Parser for the grouped settings struct type T.
func (*Parser[T]) Register ¶
Register associates a layer slug and ParameterLayer with a binder that returns a pointer to the corresponding sub-struct inside the grouped settings struct T.
Invariants: - slug must be non-empty and unique - layer must be non-nil - bind must be non-nil - slug must match layer.GetSlug() (to avoid mismatches between registration keys and parsed layer keys)
type ParserOption ¶
type ParserOption func(*parserOptions) error
ParserOption configures a Parser.
func WithCobra ¶
func WithCobra(cmd *cobra.Command, args []string) ParserOption
WithCobra configures the Parser to read flags and positional arguments from a Cobra command.
The caller is responsible for ensuring Cobra has parsed the args (i.e. this is used from within a cobra Run/RunE/PreRun hook, or after Execute has parsed).
func WithConfigFiles ¶
func WithConfigFiles(files ...string) ParserOption
WithConfigFiles configures config files to load (low -> high precedence).
func WithDefaults ¶
func WithDefaults() ParserOption
WithDefaults appends the defaults middleware (lowest precedence in the typical chain).
func WithEnv ¶
func WithEnv(prefix string) ParserOption
WithEnv enables parsing from environment variables using the given prefix.
func WithMiddlewares ¶
func WithMiddlewares(middlewares ...cmd_middlewares.Middleware) ParserOption
WithMiddlewares injects additional middlewares into the parse chain.
NOTE: Middleware ordering is subtle; this is an escape hatch for advanced usage.
func WithProfile ¶ added in v0.7.6
func WithProfile(appName string, opts ...ProfileOption) ParserOption
WithProfile enables profiles.yaml loading with circularity-safe bootstrap parsing of profile selection.
It does a mini "bootstrap parse" for the `profile-settings` layer to resolve: - profile-settings.profile - profile-settings.profile-file
using the sources configured on the parser (cobra/env/config) + defaults, then applies the selected profile at the correct precedence level (profiles override defaults, but are overridden by config/env/flags).
IMPORTANT: Ordering matters. Recommended option order:
appconfig.WithDefaults(),
appconfig.WithProfile(appName),
appconfig.WithConfigFiles(...),
appconfig.WithEnv("APP"),
appconfig.WithCobra(cmd, args),
Note: For Cobra flags like `--profile` / `--profile-file` to be accepted by Cobra, callers must ensure those flags exist on the command (typically by adding the ProfileSettings layer to the Cobra command elsewhere). WithProfile can still resolve selection from env/config without Cobra flags.
func WithValuesForLayers ¶
func WithValuesForLayers(values map[string]map[string]interface{}) ParserOption
WithValuesForLayers configures programmatic values for layers (optional).
type ProfileOption ¶ added in v0.7.6
type ProfileOption func(*profileOption)
ProfileOption configures WithProfile.
func WithProfileDefaultFile ¶ added in v0.7.6
func WithProfileDefaultFile(path string) ProfileOption
WithProfileDefaultFile overrides the computed "well-known default" profile file location used for error semantics (default: os.UserConfigDir() + "/<appName>/profiles.yaml").
func WithProfileDefaultName ¶ added in v0.7.6
func WithProfileDefaultName(profile string) ProfileOption
WithProfileDefaultName overrides the default profile name ("default").
func WithProfileEnvPrefix ¶ added in v0.7.6
func WithProfileEnvPrefix(prefix string) ProfileOption
WithProfileEnvPrefix overrides the env prefix used when bootstrap-parsing `profile-settings`.
If not provided, WithProfile defaults to strings.ToUpper(appName).
func WithProfileFile ¶ added in v0.7.6
func WithProfileFile(path string) ProfileOption
WithProfileFile sets a default profile file path to use when `profile-settings.profile-file` is not provided by config/env/flags.
Note: This does not change the "well-known default" path used by GatherFlagsFromProfiles' error semantics unless also paired with WithProfileDefaultFile.
Source Files