Documentation
¶
Overview ¶
Package configbind loads Bind-style config from defaults, TOML, env, and CLI into structs.
Index ¶
- func Bind[T any](prefix string) *T
- func EnvName(longOpt string) string
- func ReadEnv(defs []cliparser.Def, environ []string) map[string]string
- func RegisterBinding[T any](prefix, typeName string, m Meta)
- func RegisterMeta(m Meta)
- func RegisterScaffold(fragment ScaffoldFragment)
- func RegisterType[T any](typeName string, m Meta)
- func ResetScaffolds()
- func ResetTargets()
- func ScaffoldEnv() (string, error)
- func ScaffoldTOML() (string, error)
- func WriteScaffoldEnv(w io.Writer) error
- func WriteScaffoldTOML(w io.Writer) error
- type ApplyFunc
- type Entry
- type LoadOptions
- type LoadResult
- type Meta
- type Overlay
- func (o *Overlay) Delete(key string)
- func (o *Overlay) Get(key string) (Entry, bool)
- func (o *Overlay) GetMulti(key string) ([]string, bool)
- func (o *Overlay) GetString(key string) (string, bool)
- func (o *Overlay) Keys() []string
- func (o *Overlay) MergeMap(m map[string]string, place Place)
- func (o *Overlay) MergeMultiMap(m map[string][]string, place Place)
- func (o *Overlay) Set(key, raw string, place Place)
- func (o *Overlay) SetMulti(key string, values []string, place Place)
- type Place
- type ScaffoldField
- type ScaffoldFragment
- type ScaffoldKind
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bind ¶
Bind allocates *T, registers it for the next Load, and returns the pointer. Code generation must RegisterBinding[T] before Bind is used.
func EnvName ¶
EnvName converts a CLI long option name (without leading dashes) to an env var name. Hyphens become underscores; the result is uppercased.
"port" -> "PORT" "webserver-host" -> "WEBSERVER_HOST" "webserver-tls-cert_path" -> "WEBSERVER_TLS_CERT_PATH"
func ReadEnv ¶
ReadEnv maps present environment variables onto stable config keys using CLI long names. For each def, the first Longs entry determines the env var via EnvName; the value is stored under def.ConfigKey. Unset vars are absent from the result. environ is "KEY=value" lines as from os.Environ(); if nil, os.Environ() is used.
func RegisterBinding ¶ added in v0.1.11
RegisterBinding associates T and one generated Bind prefix with metadata. Unlike RegisterType, it supports using the same type with multiple prefixes.
func RegisterMeta ¶
func RegisterMeta(m Meta)
RegisterMeta registers legacy metadata by a caller-supplied identity. New generated code uses RegisterBinding so package and prefix identity cannot collide.
func RegisterScaffold ¶ added in v0.1.11
func RegisterScaffold(fragment ScaffoldFragment)
RegisterScaffold registers generated metadata for later aggregate rendering.
func RegisterType ¶
RegisterType associates T with prefix-independent legacy metadata. New generated code uses RegisterBinding.
func ResetScaffolds ¶ added in v0.1.11
func ResetScaffolds()
ResetScaffolds clears generated scaffold registrations. It is intended for tests.
func ScaffoldEnv ¶ added in v0.1.11
ScaffoldEnv renders all registered Bind fragments as one deterministic .env scaffold.
func ScaffoldTOML ¶ added in v0.1.11
ScaffoldTOML renders all registered Bind fragments as one deterministic TOML scaffold.
func WriteScaffoldEnv ¶ added in v0.1.11
WriteScaffoldEnv writes the combined .env scaffold to w.
func WriteScaffoldTOML ¶ added in v0.1.11
WriteScaffoldTOML writes the combined TOML scaffold to w.
Types ¶
type LoadOptions ¶
type LoadOptions struct {
// Vendor is the configdir vendor name (required when resolving via configdir).
Vendor string
// Tool is the application/tool name (required when resolving via configdir).
Tool string
// FileName is the config basename (default "config.toml").
FileName string
// Args are CLI args without the program name (default os.Args[1:]).
Args []string
// Environ is KEY=value lines (default os.Environ()).
Environ []string
// ExplicitConfigPath forces a config file path (overrides --config-path when set).
// Prefer leaving empty and passing --config-path via Args in production.
ExplicitConfigPath string
}
LoadOptions configures multi-source Bind load.
type LoadResult ¶
LoadResult holds the overlay after load (for tests/provenance).
func Load ¶
func Load(opts LoadOptions) (*LoadResult, error)
Load merges default → TOML → env → CLI into Bind targets and applies without reflection.
type Meta ¶
type Meta struct {
// TypeName is the package-qualified Go type identity used for diagnostics.
TypeName string
// KnownKeys lists stable config keys for env and provenance.
KnownKeys []string
// FlagMetas builds cliparser defs for this type's fields.
FlagMetas []cliparser.FieldMeta
// Defaults maps stable keys to default raw strings applied when absent.
Defaults map[string]string
// Apply writes overlay values into *T (dst must be *T).
Apply ApplyFunc
}
Meta describes generated key tables and flags for one Bind target type.
type Overlay ¶
type Overlay struct {
// contains filtered or unexported fields
}
Overlay is a key-wise multi-source merge buffer (later Set wins).
func (*Overlay) GetMulti ¶
GetMulti returns multi values when present; otherwise splits Raw by comma if needed.
func (*Overlay) MergeMultiMap ¶
MergeMultiMap merges multi-value maps with the given place.
type ScaffoldField ¶ added in v0.1.11
type ScaffoldField struct {
Key string
Kind ScaffoldKind
Default string
Opt string
Env string
Help string
}
ScaffoldField is generated metadata for one leaf configuration field.
type ScaffoldFragment ¶ added in v0.1.11
type ScaffoldFragment struct {
ID string
Prefix string
Fields []ScaffoldField
}
ScaffoldFragment is the generated scaffold metadata for one Bind type and prefix. ID must be stable and package-qualified.
type ScaffoldKind ¶ added in v0.1.11
type ScaffoldKind uint8
ScaffoldKind is the value kind needed to render a configuration example.
const ( ScaffoldString ScaffoldKind = iota ScaffoldBool ScaffoldInt ScaffoldStringSlice )
Source Files
Directories