Every feature of textdata, one row each, grouped by area. Each row names the package that provides it, the guide step that teaches it, and a runnable program under examples/ that calls it: cd examples/<area>/<name> && go run . runs it, and its main_test.go checks the output. Start from the docs index for the learning path, or from Choosing when you are deciding between options.
Packages are Go import paths under github.com/ubgo/textdata/. Most features are reachable from the library and, where a CLI verb exists, from textdatactl as well.
- Base: plugin
- Base: expand
- Base: shell
- Base: value
- Base: atomicfile, pos, path, texttest
- dotenv: read
- dotenv: syntax
- dotenv: edit
- dotenv: expand
- dotenv: plugins
- dotenv: save
- jsonc: parse
- jsonc: read
- jsonc: edit
- jsonc: lint, extends, expand, save
- jsonc tools: format, diff, generate, schema
- jsonc CLI (
textdatactl jsonc) - dotenv CLI (
dotenvctl,textdatactl dotenv) - Push providers
- clikit
- textdatactl
- Value plugins
| Feature | Package | Guide | Example |
|---|---|---|---|
| Plugin interfaces (Plugin, Lookuper, Resolver, CommandRunner, ValueTransformer, SaveGuard, ExpandObserver, Validator, Includer) | plugin |
base/plugin § Step 1 | examples/base/registry |
Capability detection (Capability, Has, Info) |
plugin |
base/plugin § Step 2 | examples/base/registry |
Plugin registry (NewRegistry, Filter, Check) |
plugin |
base/plugin § Step 3 | examples/base/registry |
Plugin errors (Error, Errorf, ErrUnavailable, ErrUnsupportedScheme, ErrDenied) |
plugin |
base/plugin § Step 4 | examples/base/registry |
Document read-only view for guards and validators |
plugin |
base/plugin § Step 1 | examples/base/registry |
| Feature | Package | Guide | Example |
|---|---|---|---|
${VAR} engine with operators (-, :-, +, :+, ?, :?), nesting, $$ |
expand |
base/expand § Step 2 | examples/base/expand-engine |
${scheme:ref} resolver hook (SplitScheme, ParseRef) |
expand |
base/expand § Step 3 | examples/base/expand-engine |
$(cmd) substitution hook (Engine.Run) |
expand |
base/expand § Step 4 | examples/base/expand-engine |
Cycle guard and depth bound (Stack, DefaultMaxDepth) |
expand |
base/expand § Step 5 | examples/base/expand-engine |
RequiredError for ${VAR:?e} |
expand |
base/expand § Step 6 | examples/base/expand-engine |
| Feature | Package | Guide | Example |
|---|---|---|---|
Run a command through the OS shell (Run, DefaultShell): sh -c, or PowerShell on Windows |
shell |
base/shell § Step 1 | examples/shell/run |
Runner options (Runner{Shell, Timeout, Env, Dir}, RunCommand) |
shell |
base/shell § Step 2 | examples/shell/run |
Failure errors (ExitError, ErrNoShell, MaxStderr), no stdout in errors, closed stdin |
shell |
base/shell § Step 5 | examples/shell/errors |
Timeouts and contexts (ErrTimeout) |
shell |
base/shell § Step 6 | examples/shell/errors |
| Feature | Package | Guide | Example |
|---|---|---|---|
Expand one value (Expand, WithEnv, WithLookup) with the formats' rules |
value |
base/value § Step 1 | examples/value/env |
Commands off by default (WithCommands, WithRunner) |
value |
base/value § Step 3 | examples/value/commands |
Value plugins in one value (WithPlugins, ErrUnsupportedPlugin) |
value |
base/value § Step 5 | examples/value/secrets |
| Feature | Package | Guide | Example |
|---|---|---|---|
Atomic write: temp file, fsync, rename, keep mode, write through symlinks (Write, Options, Resolve) |
atomicfile |
base/atomicfile § Step 1 | examples/base/atomic-write |
Positions and file:line:col errors (Pos, Index, Error, ErrorList, First) |
pos |
base/pos-and-path § Step 3 | examples/base/paths |
Paths a."b.c"[2] and JSON Pointer (Parse, ParsePointer, ParseAny, Path.String) |
path |
base/pos-and-path § Step 1 | examples/base/paths |
Round-trip and untouched-bytes property harness (RoundTrip, CheckUntouched, Untouched, DiffWindow, Seed, Corpus) |
texttest |
base/texttest § Step 2 | examples/base/property-harness |
| Feature | Package | Guide | Example |
|---|---|---|---|
Read a file to a map (Read) |
dotenv |
dotenv/reading § Step 1 | examples/dotenv/reading |
Open a file, missing file is empty (Open, Existed, Path, Mode) |
dotenv |
dotenv/reading § Step 2 | examples/dotenv/reading |
Parse a string or reader (Parse, ParseReader) |
dotenv |
dotenv/reading § Step 3 | examples/dotenv/reading |
Typed lookups (Get, Has, Count, Keys, Pairs, Map) |
dotenv |
dotenv/reading § Step 4 | examples/dotenv/reading |
Entries and kinds (Entries, Entry, Kind) |
dotenv |
dotenv/entries § Step 2 | examples/dotenv/entries |
Disabled settings (Disabled) |
dotenv |
dotenv/editing § Step 3 | examples/dotenv/editing |
Inherited (name-only) declarations (Inherited) |
dotenv |
dotenv/editing § Step 4 | examples/dotenv/editing |
| Typed configuration with the standard library | dotenv |
dotenv/typed-config § Step 2 | examples/dotenv/typed-config |
| Feature | Package | Guide | Example |
|---|---|---|---|
| Quoting rules (single, double, backtick) | dotenv |
dotenv/syntax § Step 1 | examples/dotenv/syntax |
| Multiline values | dotenv |
dotenv/syntax § Step 2 | examples/dotenv/syntax |
| Comments (full line and inline) | dotenv |
dotenv/syntax § Step 3 | examples/dotenv/syntax |
Escape sequences (WithEscapes, EscapeMode) |
dotenv |
dotenv/syntax § Step 8 | examples/dotenv/syntax |
export prefix, : delimiter, key rules, duplicates |
dotenv |
dotenv/syntax § Step 4 | examples/dotenv/syntax |
| Encrypted values left as written | dotenv |
dotenv/syntax § Step 7 | examples/dotenv/syntax |
| Feature | Package | Guide | Example |
|---|---|---|---|
Set a value in place or append (Set) |
dotenv |
dotenv/editing § Step 1 | examples/dotenv/editing |
Place a new key next to an anchor (SetAfter, SetBefore, ErrAnchorNotFound) |
dotenv |
dotenv/editing § Step 2 | examples/dotenv/editing |
Comment out or delete a key (Unset) |
dotenv |
dotenv/editing § Step 3 | examples/dotenv/editing |
Turn a disabled setting back on (Restore) |
dotenv |
dotenv/editing § Step 3 | examples/dotenv/editing |
Generate a file from entries (NewPair, NewComment, NewBlank, Append, InsertAfter, InsertBefore) |
dotenv |
dotenv/editing § Step 5 | examples/dotenv/editing |
Clone between environments (Clone) |
dotenv |
dotenv/editing § Step 7 | examples/dotenv/clone-env |
Render byte-exact (Render, Bytes) |
dotenv |
dotenv/saving § Step 3 | examples/dotenv/saving |
| Feature | Package | Guide | Example |
|---|---|---|---|
Expanded value (GetExpanded, ExpandedMap) |
dotenv |
dotenv/expansion § Step 1 | examples/dotenv/expansion |
Expansion operators, nesting, $$, self-reference rule |
dotenv |
dotenv/expansion § Step 2 | examples/dotenv/expansion |
Required variables (RequiredError) |
dotenv |
dotenv/expansion § Step 6 | examples/dotenv/expansion |
Values from outside the file (WithLookup) |
dotenv |
dotenv/plugins § Step 1 | examples/dotenv/plugin-hooks |
Command substitution, off by default (WithCommandSubstitution, WithCommandRunner) |
dotenv |
dotenv/expansion § Step 7 | examples/dotenv/expansion |
Bound command substitution (WithCommandContext) |
dotenv |
dotenv/expansion § Step 7 | examples/shell/errors |
| Feature | Package | Guide | Example |
|---|---|---|---|
Install plugins (WithPlugin, Plugins) |
dotenv |
dotenv/plugins § Step 3 | examples/dotenv/write-a-plugin |
| The seven hooks (Lookuper, Resolver, CommandRunner, ValueTransformer, SaveGuard, EntryObserver, ExpandObserver) | dotenv |
dotenv/plugins § Step 4 | examples/dotenv/plugin-hooks |
| Hooks change reads, never writes (the firewall), plugin ordering | dotenv |
dotenv/plugins § Step 6 | examples/dotenv/plugin-hooks |
Value transform on read (WithValueTransform) |
dotenv |
dotenv/plugins § Step 1 | examples/dotenv/plugin-hooks |
Veto a save (WithSaveGuard, SaveGuard) |
dotenv |
dotenv/plugins § Step 1 | examples/dotenv/plugin-hooks |
| Writing a plugin | dotenv |
dotenv/plugins § Step 3 | examples/dotenv/write-a-plugin |
| Feature | Package | Guide | Example |
|---|---|---|---|
Atomic save (Save, SaveAs), keeps mode and symlinks |
dotenv |
dotenv/saving § Step 1 | examples/dotenv/saving |
| Line endings and trailing newline preserved | dotenv |
dotenv/saving § Step 3 | examples/dotenv/saving |
| Feature | Package | Guide | Example |
|---|---|---|---|
Tolerant parse with comments attached (Parse, ParseReader, Open) |
jsonc |
jsonc/parse-and-strict § Step 1 | examples/jsonc/read-config |
Strict JSON mode (Strict, IsStrict) |
jsonc |
jsonc/parse-and-strict § Step 2 | examples/jsonc/read-config |
Positioned syntax errors (WithFileName, Err, ErrInvalid) |
jsonc |
jsonc/parse-and-strict § Step 3 | examples/jsonc/read-config |
Byte-exact render (Render, Bytes) |
jsonc |
jsonc/parse-and-strict § Step 1 | examples/jsonc/merge-layers |
| Feature | Package | Guide | Example |
|---|---|---|---|
Get values (Get, GetString, GetInt, GetFloat, GetBool) |
jsonc |
jsonc/read-and-paths § Step 1 | examples/jsonc/read-config |
Inspect structure (Has, Keys, Len, Kind) |
jsonc |
jsonc/read-and-paths § Step 2 | examples/jsonc/read-config |
Comments of a value (Comment) |
jsonc |
jsonc/read-and-paths § Step 3 | examples/jsonc/read-config |
Plain JSON out (JSON) and decode into a struct (Decode) |
jsonc |
jsonc/read-and-paths § Step 7 | examples/jsonc/read-config |
Read a file to a map (Read) |
jsonc |
jsonc/read-and-paths § Step 8 | examples/jsonc/read-config |
| Dotted paths and JSON Pointer | jsonc |
jsonc/read-and-paths § Step 4 | examples/jsonc/read-config |
Positions of values and keys (Pos, KeyPos) |
jsonc |
jsonc/read-and-paths § Step 5 | examples/jsonc/read-config |
| Feature | Package | Guide | Example |
|---|---|---|---|
Set with parent creation (Set) |
jsonc |
jsonc/edit § Step 1 | examples/jsonc/edit-config |
Place a new member (SetAfter, SetBefore) |
jsonc |
jsonc/edit § Step 2 | examples/jsonc/edit-config |
Delete a member or element (Delete) |
jsonc |
jsonc/edit § Step 3 | examples/jsonc/edit-config |
Arrays (Append, Insert, Remove) |
jsonc |
jsonc/edit § Step 4 | examples/jsonc/arrays-comments |
Comments (SetComment, RemoveComment) |
jsonc |
jsonc/edit § Step 6 | examples/jsonc/arrays-comments |
Comment out and bring back (Disable, Restore) |
jsonc |
jsonc/disable-restore § Step 1 | examples/jsonc/edit-config |
Merge and clone (Merge, Clone) |
jsonc |
jsonc/merge-clone § Step 1 | examples/jsonc/merge-layers |
| Feature | Package | Guide | Example |
|---|---|---|---|
Lint (Lint, LintRule, AllLintRules, LintOnly, ForbidTrailingCommas, Issue) |
jsonc |
jsonc/lint-validate § Step 1 | examples/jsonc/lint |
Validate through installed Validator plugins (Validate) |
jsonc |
jsonc/lint-validate § Step 4 | examples/jsonc/lint |
$extends (Extended, Extends, ExtendsKey, MaxExtendsDepth, extends errors) |
jsonc |
jsonc/extends § Step 2 | examples/jsonc/extends |
Expansion (WithExpand, Expanded, GetExpanded, ExpandRequested, WithLookup) |
jsonc |
jsonc/expansion-and-plugins § Step 1 | examples/jsonc/expand |
Command substitution, off by default (WithCommandSubstitution) |
jsonc |
jsonc/expansion-and-plugins § Step 4 | examples/jsonc/expand |
Bound command substitution (WithCommandContext) |
jsonc |
jsonc/expansion-and-plugins § Step 4 | examples/shell/errors |
Plugins (WithPlugin, Plugins) |
jsonc |
jsonc/expansion-and-plugins § Step 3 | examples/jsonc/expand |
Atomic save with SaveGuards (Save, SaveAs, SetPath) |
jsonc |
jsonc/save § Step 1 | examples/jsonc/edit-config |
| Feature | Package | Guide | Example |
|---|---|---|---|
Re-lay a file out keeping comments (format.Format, Style, DefaultStyle) |
jsonc/format |
jsonc-tools/format § Step 2 | examples/jsonc-tools/format |
Minify (format.Minify) |
jsonc/format |
jsonc-tools/format § Step 4 | examples/jsonc-tools/format |
Semantic diff by path (diff.Diff, Change, Kind) |
jsonc/diff |
jsonc-tools/diff § Step 1 | examples/jsonc-tools/diff |
Value equality (diff.Equal) |
jsonc/diff |
jsonc-tools/diff § Step 4 | examples/jsonc-tools/diff |
Build a file by hand (generate.New, Object, Array, item options) |
jsonc/generate |
jsonc-tools/generate § Step 4 | examples/jsonc-tools/generate-from-struct |
Generate from a config struct (generate.FromStruct) |
jsonc/generate |
jsonc-tools/generate § Step 2 | examples/jsonc-tools/generate-from-struct |
Generator options (Indent, Tabs, Spaces, CRLF, TrailingCommas, Comments, FinalNewline, SchemaURL) |
jsonc/generate |
jsonc-tools/generate § Step 5 | examples/jsonc-tools/generate-from-struct |
Schema from a struct (schema.FromStruct) |
jsonc/schema |
jsonc-tools/schema § Step 1 | examples/jsonc-tools/schema-plugin |
Validate a document (schema.Validate, Result, Issue, OnWarning) |
jsonc/schema |
jsonc-tools/schema § Step 2 | examples/jsonc-tools/schema-plugin |
Load or parse a schema (schema.Parse, schema.Load) |
jsonc/schema |
jsonc-tools/schema § Step 3 | examples/jsonc-tools/schema-plugin |
Schema as a Validator and SaveGuard plugin (schema.Plugin) |
jsonc/schema |
jsonc-tools/schema § Step 4 | examples/jsonc-tools/schema-plugin |
| Feature | Package | Guide | Example |
|---|---|---|---|
get |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 1 | examples/cli/embed-jsonc |
set (--json-value, --dry-run) |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 2 | examples/cli/embed-jsonc |
unset, restore, delete |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 2 | examples/cli/verb-tour |
diff |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 3 | examples/cli/verb-tour |
to-json |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 3 | examples/cli/verb-tour |
fmt (--check, --indent, --tabs, --trailing-commas) |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 4 | examples/cli/embed-jsonc |
validate (--schema, --forbid-trailing-commas) |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 4 | examples/cli/verb-tour |
--json envelope, --strict, exit codes |
jsonc/cli/jsonccmd |
cli/jsonc-cli § Step 5 | examples/cli/embed-jsonc |
Embed the verbs (Command, Execute, WithProgramName) |
jsonc/cli/jsonccmd |
cli/embedding § Step 5 | examples/cli/embed-jsonc |
| Feature | Package | Guide | Example |
|---|---|---|---|
get (--expand) |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 2 | examples/cli/embed-dotenvctl |
set (--after, --before, --dry-run) |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 3 | examples/cli/embed-dotenvctl |
unset (--delete, --dry-run) |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 3 | examples/cli/verb-tour |
restore |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 3 | examples/cli/verb-tour |
list (--expand, --disabled, --inherited), keys |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 2 | examples/cli/verb-tour |
run -- COMMAND (file values in a child process) |
dotenv/cli/dotenvcmd |
cli/dotenvctl § Step 4 | examples/cli/run-child |
envs (discover the .env family) |
dotenv/cli/dotenvcmd |
cli/multi-env § Step 1 | examples/cli/verb-tour |
matrix (--contract, --only-drift, --values, --reveal, --placeholder, --dir) |
dotenv/cli/dotenvcmd |
cli/multi-env § Step 2 | examples/cli/verb-tour |
diff (--expand, --reveal) |
dotenv/cli/dotenvcmd |
cli/multi-env § Step 5 | examples/cli/verb-tour |
Output formats (--json, `--format human |
json | html, -o`) |
dotenv/cli/dotenvcmd |
Exec plugins (dotenvctl-<name> on PATH, plugins, DOTENVCTL_* context) |
dotenv/cli/dotenvcmd |
cli/exec-plugins § Step 4 | examples/cli/exec-plugin |
Embed the CLI (dotenvcmd.Execute, WithProgramName) |
dotenv/cli/dotenvcmd |
cli/embedding § Step 1 | examples/cli/embed-dotenvctl |
Operations API: select, edit, diff (envkit.Select, SelectFile, Set, Unset, Restore, Diff, DiffMaps) |
dotenv/cli/envkit |
cli/envkit § Step 2 | examples/cli/envkit-ops |
Operations API: matrix and drift (BuildMatrix, Inventories, DriftRows, SparseColumn, DisambiguateColumns) |
dotenv/cli/envkit |
cli/envkit § Step 5 | examples/cli/envkit-ops |
Operations API: run a child (Run, ChildEnv, MergeEnv) |
dotenv/cli/envkit |
cli/envkit § Step 6 | examples/cli/envkit-ops |
Discover a .env family (discover.Scan, Classify, envkit.Discover, EnvNameForPath) |
dotenv/cli/discover |
cli/envkit § Step 1 | examples/cli/envkit-ops |
| Feature | Package | Guide | Example |
|---|---|---|---|
GitHub: push, list, prune for repo, environment and org secrets (--repo, --environment, --org) |
dotenv/cli/providers/github |
providers/github § Step 1 | examples/providers/github |
GitHub: env-create (--yes) |
dotenv/cli/providers/github |
providers/github § Step 4 | examples/providers/github |
| GitHub: authentication and token override | dotenv/cli/providers/github |
providers/github § Step 6 | examples/providers/github |
GitHub: mount in your own binary (githubplugin.New) |
dotenv/cli/providers/github |
providers/github § Step 7 | examples/providers/github |
Vercel: push, list, prune (--target, --sensitive) |
dotenv/cli/providers/vercel |
providers/vercel § Step 2 | examples/providers/vercel |
Vercel: mount in your own binary (vercelplugin.New) |
dotenv/cli/providers/vercel |
providers/vercel § Step 7 | examples/providers/vercel |
Selection flags (--prefix, --exclude-prefix, --include, --exclude, --strip-prefix, --expand, --include-placeholders, --include-empty) |
clikit/providerkit |
providers/selection § Step 2 | examples/providers/selection |
Prune stale remote secrets (--keep, --yes, --dry-run) |
clikit/providerkit |
providers/github § Step 5 | examples/providers/github |
| Feature | Package | Guide | Example |
|---|---|---|---|
Output envelope and error codes (outfmt.Printer, ErrCode) |
clikit/outfmt |
providers/output-and-reports § Step 1 | examples/providers/output-and-reports |
HTML reports (report.MatrixHTML, DiffHTML, MaskGlyph) |
clikit/report |
providers/output-and-reports § Step 5 | examples/providers/output-and-reports |
Line diff (textdiff.Lines) |
clikit/textdiff |
providers/output-and-reports § Step 4 | examples/providers/output-and-reports |
Key selection grammar and placeholders (selection.Options, Selection, PlaceholderMatcher) |
clikit/selection |
providers/selection § Step 6 | examples/providers/selection |
Build a push provider (providerkit.Plugin, NewPushCmd, NewListCmd, NewPruneCmd, Confirm, Runner) |
clikit/providerkit |
providers/write-a-provider § Step 2 | examples/providers/fake-provider |
| Feature | Package | Guide | Example |
|---|---|---|---|
textdatactl dotenv … (every dotenvctl verb) |
cmd/textdatactl |
getting-started/textdatactl § Step 2 | examples/cli/verb-tour |
textdatactl jsonc … |
cmd/textdatactl |
getting-started/textdatactl § Step 3 | examples/getting-started/embed-cli |
textdatactl version (--json) |
cmd/textdatactl |
getting-started/textdatactl § Step 1 | examples/cli/verb-tour |
Embed the umbrella (ctl.Execute, ctl.Formats) |
cmd/textdatactl/ctl |
getting-started/textdatactl § Step 4 | examples/getting-started/embed-cli |
| Feature | Package | Guide | Example |
|---|---|---|---|
gopass: ${gopass:path} resolver (gopassplugin.New, WithRunner, WithBinary, WithTimeout, WithCache) |
plugins/gopass |
plugins/gopass § Step 1 | examples/plugins/gopass-fake-runner |
gopass: ${NAME} lookups (WithPrefix, WithMapping) |
plugins/gopass |
plugins/gopass § Step 1 | examples/plugins/gopass-fake-runner |
file: ${file:path} resolver with confinement (fileplugin.New, WithRoot, Unconfined, WithMaxSize, WithTrimNewline) |
plugins/file |
plugins/file § Step 1 | examples/plugins/file-confined |
extends: disk includer (extends.New, WithRoot, AllowAbsolute, WithMaxSize) |
plugins/extends |
plugins/extends § Step 4 | examples/plugins/extends-fs |
extends: fs.FS includer (extends.NewFS) |
plugins/extends |
plugins/extends § Step 1 | examples/plugins/extends-fs |
vault: KV v1/v2 ${vault:path?version=N#field} (vault.New, WithAddress, WithToken, WithNamespace, FromEnv) |
plugins/vault |
plugins/vault § Step 1 | examples/plugins/vault-httptest |
vault: ${NAME} lookups (WithLookup, WithLookupPrefix) |
plugins/vault |
plugins/vault § Step 3 | examples/plugins/vault-httptest |
aws: Secrets Manager and SSM ${aws:sm/…}, ${aws:ssm/…} (aws.New, WithRegion, WithEndpoint) |
plugins/aws |
plugins/aws § Step 1 | examples/plugins/aws-httptest |
aws: credentials (WithCredentials, FromEnv, FromSharedCredentials, WithCredentialsSource) |
plugins/aws |
plugins/aws § Step 5 | examples/plugins/aws-httptest |
aws: ${NAME} lookups (WithLookup, WithLookupPrefix) |
plugins/aws |
plugins/aws § Step 2 | examples/plugins/aws-httptest |