config

Documentation

Overview

Package config is dstow's four-level configuration chain (DESIGN.md §3 + A8): the legality matrix over the one key vocabulary, use-time path expansion, warnings-as-data for unknown and misplaced keys, stow compatibility (stowrc discovery, slotting, option mapping, and supplement diffing via gostow's public stowrc package), content-sniff routing for a renamed rc, DSTOW_PATH parsing, and the metadata-location accessor.

The package returns data, never output (A4): every diagnostic comes back as a Warning value or a typed error, and the caller decides how to render it. Loading is per level — LoadGlobal, LoadRepoLevel, LoadPackageLevel — so a broken level scopes exactly to what that level governs (C8, C21); Effective composes loaded levels into one per-package view, nearest level winning per knob except the additive ignore chain (REQUIREMENTS §4.1).

Index

• func GlobalConfigDir() string
• func GlobalConfigFile() string
• func LoadGlobal() (*GlobalLevel, []Warning, error)
• func LoadPackageLevel(pkgRoot string) (*PackageLevel, []Warning, error)
• func LoadRepoLevel(repoRoot string) (*RepoLevel, []Warning, error)
• func MetadataDir(scopeRoot string) string
• func RegistryFile() string
• func UserThemesDir() string
• type Effective
  • func (e Effective) ExcludeFromBulk() bool
  • func (e Effective) FoldTrees() bool
  • func (e Effective) Ignores() []IgnorePattern
  • func (e Effective) Target() (string, error)
  • func (e Effective) TranslateDotPrefixes() bool
• type ExpandError
  • func (e *ExpandError) Error() string
• type GlobalLevel
  • func (g *GlobalLevel) ColorTable() map[string]string
  • func (g *GlobalLevel) SessionRepoDir() string
  • func (g *GlobalLevel) Theme() (string, error)
• type IgnorePattern
• type Language
  • func (l Language) String() string
• type Level
  • func (l Level) String() string
• type PackageLevel
• type PatternError
  • func (e *PatternError) Error() string
• type RepoLevel
  • func (r *RepoLevel) CompatFoldTrees() (value bool, file string, set bool)
  • func (r *RepoLevel) PackagesDir() string
• type Warning
  • func ParseDSTOWPath(raw string) ([]string, []Warning, error)

Functions

func GlobalConfigDir

func GlobalConfigDir() string

GlobalConfigDir returns the global level's metadata directory, $XDG_CONFIG_HOME/dstow (§3.1, XDG paths via adrg/xdg).

func GlobalConfigFile

func GlobalConfigFile() string

GlobalConfigFile returns the global config file path (§3.1).

func LoadGlobal

func LoadGlobal() (*GlobalLevel, []Warning, error)

LoadGlobal loads the global level: $XDG_CONFIG_HOME/dstow/config.toml supplemented by ~/.stowrc (slotted global, C20), plus the reserved- territory scan of the global config dir (M5: claimed entries are config.toml, repos.toml, themes/, hooks/).

func LoadPackageLevel

func LoadPackageLevel(pkgRoot string) (*PackageLevel, []Warning, error)

LoadPackageLevel loads one package's level: <package>/.dstow/config.toml (there is no package-level rc slot — stow has none) plus the metadata dir's reserved-territory scan.

func LoadRepoLevel

func LoadRepoLevel(repoRoot string) (*RepoLevel, []Warning, error)

LoadRepoLevel loads one repo's level: <repo>/.dstow/config.toml supplemented by <repo>/.stowrc — discovered via the repo, never cwd (C20) — plus the metadata dir's reserved-territory scan (M5: claimed entries are config.toml and hooks/).

func MetadataDir

func MetadataDir(scopeRoot string) string

MetadataDir returns the metadata directory of a repo or package root — the same rule at both levels (M1). This is the one accessor hiding the metadata location (A8).

func RegistryFile

func RegistryFile() string

RegistryFile returns the repo registry path (C3). The registry is config, not state — dstow-written, never declared in config.toml — and the repo package owns reading and writing it (A9); config only knows where it is.

func UserThemesDir

func UserThemesDir() string

UserThemesDir returns the user theme presets directory (§3.1); ui's theme loader consumes it (C4).

Types

type Effective

type Effective struct {
	Global  *GlobalLevel
	Repo    *RepoLevel
	Package *PackageLevel
}

Effective is one package's view of the chain: nearest level wins per knob, ignores compose additively (REQUIREMENTS §4.1), and the built-in floor closes every fall-through (§4.4). Nil levels are simply absent — a package with no config is the common case, not an error.

func (Effective) ExcludeFromBulk

func (e Effective) ExcludeFromBulk() bool

ExcludeFromBulk resolves bulk exclusion: package over repo (nearer wins, even when nearer says false); the built-in default is off. Explicit naming overriding bulk exclusion is the caller's law, not a config fact.

func (Effective) FoldTrees

func (e Effective) FoldTrees() bool

FoldTrees resolves folding: a migrated repo rc's contribution is honored for this repo (REQUIREMENTS §3.3), else the global setting, else the built-in off (REQUIREMENTS §3.3: predictable link topology). The cross-repo contradiction guard composes in ops from CompatFoldTrees.

func (Effective) Ignores

func (e Effective) Ignores() []IgnorePattern

Ignores returns the additive ignore chain in level order — global, repo, package — each entry carrying its carrier language and provenance (§3.4). The engine's always-on metadata auto-ignore (M8) and stow's built-in ignores ride the engine seam, not this chain.

func (Effective) Target

func (e Effective) Target() (string, error)

Target resolves the effective target: package → repo → global → the built-in $HOME floor, expanded at use time per C8 (unset variable and non-absolute results error with full provenance, scoping to the views that select the offending value).

func (Effective) TranslateDotPrefixes

func (e Effective) TranslateDotPrefixes() bool

TranslateDotPrefixes resolves dot-translation: nearest level wins; the built-in default is on (REQUIREMENTS §3.4).

type ExpandError

type ExpandError struct {
	File   string // provenance; "built-in default" for the floor
	Key    string // the key as spelled where it was set ("target", "--target option", …)
	Value  string
	Reason string
}

ExpandError is a C8 failure: a path-valued key whose use-time expansion hit an unset variable, or whose expanded result is not absolute. It names variable-or-result + file + key, and scopes per package — only effective views that select the offending value error.

func (*ExpandError) Error

func (e *ExpandError) Error() string

type GlobalLevel

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

GlobalLevel is the loaded global level (§3.1): the shared knobs plus the global-only territory — folding, theming, and the session-repo contribution a migrated ~/.stowrc --dir makes.

func (*GlobalLevel) ColorTable

func (g *GlobalLevel) ColorTable() map[string]string

ColorTable returns the raw [color] table values (§3.3) for ui to parse — config carries the strings, ui owns the slot vocabulary and the value grammar. Nil when no table was set.

func (*GlobalLevel) SessionRepoDir

func (g *GlobalLevel) SessionRepoDir() string

SessionRepoDir returns the session-repo contribution of a migrated ~/.stowrc --dir (C19), or "" when there is none.

func (*GlobalLevel) Theme

func (g *GlobalLevel) Theme() (string, error)

Theme returns the theme reference (C13): a bare name verbatim, or — for the path form per the operand rule — the C8-expanded absolute path. Empty when unset.

type IgnorePattern

type IgnorePattern struct {
	Pattern  string
	Language Language
	Level    Level
	Source   string // the file that declared it
}

IgnorePattern is one entry of the additive ignore chain (§3.4): a level adds to, never silences, inherited ignores, so entries carry provenance instead of overriding each other.

type Language

type Language int

Language is the pattern language of an ignore carrier (C17): native carriers speak gitignore-glob, compat carriers speak stow regex; never mixed in one file.

const (
	LangGlob      Language = iota // native gitignore-glob (C16)
	LangStowRegex                 // compat stow regex (.stowrc --ignore)
)

func (Language) String

func (l Language) String() string

type Level

type Level int

Level identifies one level of the chain (§3.1). The built-in floor is a level too: it is where the out-of-the-box defaults live (REQUIREMENTS §4.4).

const (
	LevelBuiltin Level = iota
	LevelGlobal
	LevelRepo
	LevelPackage
)

func (Level) String

func (l Level) String() string

type PackageLevel

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

PackageLevel is one package's level: the package knob set (§3.2).

type PatternError

type PatternError struct {
	File    string
	Pattern string // empty when the pattern is only known inside Reason
	Reason  string
}

PatternError refuses an ignore pattern: a native refused-and-reserved form (C16: leading '!' or '//') or a non-RE2 compat pattern (C21). The refusal scopes to the level the pattern governs — the loader for that level returns it, and the run continues past whatever that level covered.

func (*PatternError) Error

func (e *PatternError) Error() string

type RepoLevel

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

RepoLevel is one repo's level: the shared knobs, the package-level knob set acting as defaults for the repo's packages (REQUIREMENTS §4.1), plus the repo-only packages_dir (M3) and the compat fold contribution a migrated repo .stowrc makes (REQUIREMENTS §3.3).

func (*RepoLevel) CompatFoldTrees

func (r *RepoLevel) CompatFoldTrees() (value bool, file string, set bool)

CompatFoldTrees reports the fold contribution of a migrated repo-level .stowrc (REQUIREMENTS §3.3: honored, the compat exception to fold-is-global-only). ops composes the cross-repo contradiction guard from these per-repo values.

func (*RepoLevel) PackagesDir

func (r *RepoLevel) PackagesDir() string

PackagesDir returns the raw repo-root-relative packages directory (M3) — deliberately outside C8's expand-to-absolute grammar — or "" when unset (packages at the repo root; stow compat binds the default).

type Warning

type Warning struct {
	Source string // where it came from: a file path, "DSTOW_PATH", …
	Detail string // complete prose: what is wrong and that the rest applies
	Fix    string // optional remedy, e.g. the native spelling to migrate to
}

Warning is a diagnostic as data (A4): loaders return warnings, the caller decides when and how to print them. Config warnings are surprise-class announcements (§3.5) — they survive --quiet. Detail is complete prose; Fix, when set, is the remedy line (O2's fix severity) the caller renders after it.

func ParseDSTOWPath

func ParseDSTOWPath(raw string) ([]string, []Warning, error)

ParseDSTOWPath parses a DSTOW_PATH value (C23): separator-joined absolute local directory paths, PATH convention — the platform's list separator, colon on Unix. No qualified sources, no dstow-side expansion. Empty entries warn-and-skip; relative entries are refused loudly, every bad entry named with its remedy (§1.4). The caller reads the environment at point of use (A2) and hands the raw value in; existence of the directories is the repo set's concern, not the grammar's.