configbind

type ApplyFunc func(dst any, o *Overlay) error

type Definition struct {
	// TypeName is the package-qualified Go type identity used for diagnostics.
	TypeName string
	// Prefix is the configuration key prefix passed to Bind.
	Prefix string
	// Doc is the config struct's godoc text, rendered above the scaffold table.
	Doc 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
	// DependsOn maps a stable key to every condition it answers to: its own
	// dependon tag plus the tags of the structs it sits under. One failed
	// condition is enough to hide the key from provenance output; nothing else.
	DependsOn map[string][]Dependency
	// Falsy maps a stable key to the choice from its falsy tag. The key resolves
	// to that value when nothing sets it and it has no default, and the value
	// counts as empty when other keys depend on this one.
	Falsy map[string]string
	// Secrets maps a stable key to its secret tag: hide, mask, or show. A key
	// with no entry follows the key-name policy in displayValue.
	Secrets map[string]string
	// Summary maps a stable key to its summary tag, which today is only "omit".
	// It rates the key as detail, so a caller rendering a short surface may drop
	// it once nothing has set it; see ProvenanceEntry.Omittable. Unlike Secrets
	// and DependsOn it removes nothing on its own.
	Summary map[string]string
	// Apply writes overlay values into *T (dst must be *T).
	Apply ApplyFunc
	// Scaffold contains the leaf fields used to render example configuration.
	Scaffold []ScaffoldField
}

type Dependency struct {
	// Key is the parent's absolute config key, already resolved from any
	// dot-prefixed relative form at generation time.
	Key string
	// Op is "", "=", or "!=".
	Op string
	// Values are the choices the operator compares against, in tag order.
	Values []string
}

type Entry struct {
	Raw     string
	Multi   []string
	IsMulti bool
	// Tables holds one overlay per [[key]] element when IsTables is true. Their
	// keys are relative to the table-array key. Only the TOML layer produces
	// them: env and CLI have no repeated-table form.
	Tables   []*Overlay
	IsTables bool
	Place    Place
}

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
	// ExtraConfigReadPaths are optional config files searched in slice order
	// after ExplicitConfigPath/--config-path and before user/system config dirs.
	// Missing or unreadable entries are skipped; only the first found file is read.
	ExtraConfigReadPaths []string
}

type LoadResult struct {
	Overlay    *Overlay
	ConfigPath string
	FoundFile  bool
	// contains filtered or unexported fields
}

type Overlay struct {
	// contains filtered or unexported fields
}

type Place string

type Positional struct {
	ConfigKey string
	Name      string
	Help      string
	Role      PositionalRole
	// Enum is the allowlist the argument accepts, already split and trimmed at
	// generation time, and listed in the usage text beside Help.
	Enum []string
}

type PositionalRole uint8

type ProvenanceEntry struct {
	// Key is the stable config key (e.g. "webserver.port"), or the indexed form
	// for a field of an array-of-tables element (e.g. "rdb.connections[0].dsn").
	Key string
	// Value is the display form after redaction, never the raw secret.
	Value string
	// Place is the source layer that won for this key.
	Place Place
	// Masked reports that Value is the redaction placeholder rather than the
	// configured value, so a caller re-rendering these entries can tell the two
	// apart without comparing against the mask text.
	Masked bool
	// Omittable reports that a short surface may leave this entry out: the key is
	// rated as detail by a summary tag and nothing but the default layer set it.
	// Both halves are already applied, so two callers cannot read the rule
	// differently, and unlike the dependon and secret policies this one removes
	// nothing on its own.
	Omittable bool
	// ArrayKey is the array of tables this entry is an element field of, with
	// the indices of any enclosing arrays already in place. It is empty for an
	// ordinary key, so a caller groups a tree by it and orders by Index without
	// parsing Key apart at its brackets.
	ArrayKey string
	// Index is the element's position within ArrayKey, and 0 when ArrayKey is
	// empty.
	Index int
}

type ScaffoldField struct {
	Key     string
	Kind    ScaffoldKind
	Default string
	Opt     string
	Env     string
	Help    string
	// Enum is the allowlist the field accepts, already split and trimmed at
	// generation time. It is rendered as a comment beside the example value so a
	// reader sees the choices where the typo would otherwise be made; the value
	// check itself lives in the generated apply code.
	Enum []string
	// Nested holds the element fields when Kind is ScaffoldTableArray. Their
	// keys are relative to Key.
	Nested []ScaffoldField
}

type ScaffoldKind uint8

type SubCommandDefinition struct {
	TypeName    string
	Name        string
	Help        string
	FlagMetas   []cliparser.FieldMeta
	Defaults    map[string]string
	Positionals []Positional
	Apply       ApplyFunc
}

type UsageError struct {
	Message string
	Usage   string
}