edit

Documentation

Overview

Package edit provides format-preserving editors for the config files that coding agents keep: JSON/JSONC, TOML and YAML. Only the requested key changes; comments, ordering and indentation are left as they are.

Index

• func Atomically(fn func() error, paths ...string) error
• func BlockList(raw string) (string, bool)
• func DelEnvFile(path string, keys ...string) error
• func DelJSON(path string, keyPaths ...string) error
• func DelJSONItem(path string, where map[string]string) error
• func DelTOMLArrayTable(path, name, key, value string) error
• func DelTOMLKey(path, name, key string) error
• func DelTOMLTable(path, name string) error
• func DelTOMLTop(path string, keys ...string) error
• func DelYAML(path string, keyPaths ...string) error
• func DelYAMLTop(path string, keys ...string) error
• func EditYAMLNode(path, keyPath string, fn func(n *yaml.Node) (changed, remove bool)) error
• func EditYAMLStrings(path string, keyPaths []string, fn func(string) string) error
• func Filtered(f func(path string, data []byte) []byte, fn func() error) error
• func GetEnvFile(path, key string) (string, bool)
• func GetJSON(path, keyPath string) (string, bool)
• func GetJSONItem(path string, where map[string]string) (string, bool)
• func GetTOMLTable(path, name string) (map[string]string, error)
• func GetTOMLTop(path, key string) (string, bool)
• func GetYAML(path, keyPath string) (string, bool)
• func GetYAMLList(path, keyPath string) []string
• func GetYAMLMap(path, keyPath string) map[string]string
• func GetYAMLText(path, keyPath string) (string, bool)
• func GetYAMLTop(path, key string) (string, bool)
• func IsLink(path string) bool
• func JSONToYAML(src, dst string) error
• func PatchJSON(raw []byte, set []KV, del []string) ([]byte, error)
• func Read(path string) ([]byte, error)
• func Remove(path string) error
• func SetEnvFile(path string, kvs ...KV) error
• func SetJSON(path string, kvs ...KV) error
• func SetJSONItem(path string, where map[string]string, value any) error
• func SetTOMLArrayTable(path, name, key, value, block string) error
• func SetTOMLKey(path, name, key string, value any) error
• func SetTOMLTable(path, name string, kvs ...KV) error
• func SetTOMLTables(path string, prefixes []string, tables []Table) error
• func SetTOMLTablesMatching(path string, names, prefixes []string, tables []Table) error
• func SetTOMLTop(path string, kvs ...KV) error
• func SetTOMLTopPreserving(path string, kvs ...KV) error
• func SetYAML(path string, kvs ...KV) error
• func SetYAMLTop(path string, kvs ...KV) error
• func SplitLines(s string) []string
• func TOMLTables(path string) ([]string, error)
• func Target(path string) (string, error)
• func TrimBOM(b []byte) []byte
• func WriteAtomic(path string, data []byte) error
• func WriteTOMLFile(path string, lines []string) error
• type Inline
• type KV
• type Raw
• type Table
• type YAMLText
  • func EditYAMLTextStrings(text YAMLText, fn func(string) string) (YAMLText, error)

Functions

func Atomically

func Atomically(fn func() error, paths ...string) error

Atomically runs fn, which may write the files at paths in several steps, and puts each of them back as it was — its bytes and mode, or its absence — when fn fails, so an edit that fails part way leaves no file half made. A file that can't be read beforehand is left to fn as it is.

func BlockList

func BlockList(raw string) (string, bool)

BlockList is raw, a file whose one document is a top-level sequence written in flow style ([ {id: a}, {id: b} ], what dsh's own writers keep a file that starts as []), with that sequence written as a block list instead: one "- " item after another, each entry's mappings and lists in block style too, its scalars quoted as they were. The lines before the sequence and the comment lines after it stay as written. ok is false, and raw is left to the caller, for anything else: a block list, a mapping, several documents, or text that isn't YAML.

func DelEnvFile

func DelEnvFile(path string, keys ...string) error

DelEnvFile removes keys from a dotenv file, and the file when they were all it held (Gemini CLI's .env, made by magpie for its key).

func DelJSON

func DelJSON(path string, keyPaths ...string) error

DelJSON removes key paths from a JSON/JSONC file, preserving everything else. Missing keys are ignored; an object left empty collapses to {}.

func DelJSONItem

func DelJSONItem(path string, where map[string]string) error

DelJSONItem removes every element of the file's top-level array that has every member of where. A file without one is left as it is.

func DelTOMLArrayTable

func DelTOMLArrayTable(path, name, key, value string) error

DelTOMLArrayTable removes just the matching entry and its child tables.

func DelTOMLKey

func DelTOMLKey(path, name, key string) error

DelTOMLKey removes one key of table `name`, and the table with it when nothing else is left in it.

func DelTOMLTable

func DelTOMLTable(path, name string) error

DelTOMLTable removes table `name` (header and body) if present. Child table and array-table blocks are outside that range and remain.

func DelTOMLTop

func DelTOMLTop(path string, keys ...string) error

DelTOMLTop removes top-level (pre-table) keys, each with every line of its value.

func DelYAML

func DelYAML(path string, keyPaths ...string) error

DelYAML removes key paths from a YAML file. A missing file stays missing.

func DelYAMLTop

func DelYAMLTop(path string, keys ...string) error

DelYAMLTop removes whole top-level entries from a single block mapping. A missing file stays missing; parse errors leave the file untouched.

func EditYAMLNode

func EditYAMLNode(path, keyPath string, fn func(n *yaml.Node) (changed, remove bool)) error

EditYAMLNode hands fn the node at a key path, nil when there is none, to change in place: a list grown by one item keeps the comments on the rest, where SetYAML would write the whole value anew. fn says whether it changed the node, and whether the key is to go instead. The file is written only on a change.

func EditYAMLStrings

func EditYAMLStrings(path string, keyPaths []string, fn func(string) string) error

EditYAMLStrings calls fn on every string under the key paths — mapping keys and values, sequence items, at any depth — and puts fn's answer in its place, comments and quoting kept. The file is written only when an answer differs, so an fn that answers what it is given only reads.

func Filtered

func Filtered(f func(path string, data []byte) []byte, fn func() error) error

Filtered runs fn with every file written through this package passed through f first: f gets the path (a link's target) and the bytes about to be written, and returns the bytes to write. Writes from elsewhere while fn runs pass through f too, so f changes only what it is sure of. One Filtered runs at a time.

func GetEnvFile

func GetEnvFile(path, key string) (string, bool)

GetEnvFile reads one key from a dotenv file.

func GetJSON

func GetJSON(path, keyPath string) (string, bool)

GetJSON reads a dot-separated key path from a JSON or JSONC file.

func GetJSONItem

func GetJSONItem(path string, where map[string]string) (string, bool)

GetJSONItem returns the raw JSON of the first element of the file's top-level array that has every member of where.

func GetTOMLTable

func GetTOMLTable(path, name string) (map[string]string, error)

GetTOMLTable returns the scalar keys of one table, or (nil, nil) when the file or table is absent. Read and parse errors are returned with the path. Strings are decoded; other scalars (booleans, numbers, dates, and times) retain their literal text. Arrays and inline tables are omitted. An array table with the requested name is a type error, not an absent table.

func GetTOMLTop

func GetTOMLTop(path, key string) (string, bool)

GetTOMLTop reads a top-level (pre-table) key from a TOML file. A string is decoded; any other value is its text as written, without a trailing comment, an array or inline table over several lines included. A file TOML's parser refuses is read line by line, as well as that goes.

func GetYAML

func GetYAML(path, keyPath string) (string, bool)

GetYAML reads a dot-separated key path to a scalar from a YAML file.

func GetYAMLList

func GetYAMLList(path, keyPath string) []string

GetYAMLList reads the scalar items of the list at a key path.

func GetYAMLMap

func GetYAMLMap(path, keyPath string) map[string]string

GetYAMLMap reads the scalar entries of the mapping at a key path.

func GetYAMLText

func GetYAMLText(path, keyPath string) (string, bool)

GetYAMLText reads the value at a key path as the YAML it is written in — a list flow ("[a, b]") or block as it is — for SetYAML to put back as a YAMLText.

func GetYAMLTop

func GetYAMLTop(path, key string) (string, bool)

GetYAMLTop reads a top-level scalar key from a YAML file. Quoted keys and string values are decoded; malformed files return ("", false).

func IsLink

func IsLink(path string) bool

IsLink reports whether path is a symlink.

func JSONToYAML

func JSONToYAML(src, dst string) error

JSONToYAML writes a JSON or JSONC file out as block-style YAML, key order kept, for agents that moved from one to the other.

func PatchJSON

func PatchJSON(raw []byte, set []KV, del []string) ([]byte, error)

PatchJSON computes a config change without writing a file. A byte order mark raw starts with is read through and kept.

func Read

func Read(path string) ([]byte, error)

Read returns the file contents, or (nil, nil) when the file does not exist. A file unchanged since it was last read is not read again (the Agents page looks at each agent's files many times over), and what is returned is the caller's own to change.

A UTF-8 byte order mark at the start is not part of what is returned: Windows tools (PowerShell's UTF8 encoding, Notepad, Claude Code channel switchers) put one in front of an agent's settings.json or config.toml, which the agent reads through while a JSON or TOML parser refuses it (#1534). WriteAtomic puts it back, see keepBOM.

func Remove

func Remove(path string) error

Remove takes away a file magpie has emptied. A symlink stays and the file it points at is emptied instead, when there is one: deleting the link would leave the old text in its target. A file with other hard links is emptied and kept for the same reason, so every name comes out empty: with AGENTS.md and CLAUDE.md one file under two names, clearing AGENTS.md empties CLAUDE.md too, where deleting the one name would leave the text magpie is taking back under the other.

func SetEnvFile

func SetEnvFile(path string, kvs ...KV) error

SetEnvFile sets keys in a dotenv file, replacing lines in place and appending new ones. Other lines are kept byte for byte.

func SetJSON

func SetJSON(path string, kvs ...KV) error

SetJSON sets one or more key paths in a JSON/JSONC file, preserving comments, key order and indentation. Missing files and parents are created.

func SetJSONItem

func SetJSONItem(path string, where map[string]string, value any) error

SetJSONItem replaces the first element that has every member of where with value, or adds value at the end of the array when none does. A missing or empty file is made an array of value alone.

func SetTOMLArrayTable

func SetTOMLArrayTable(path, name, key, value, block string) error

SetTOMLArrayTable replaces one named array entry and its child tables, or appends it. block is a complete array-table declaration, including its header. Duplicate matches, invalid input and replacements for another entry are errors.

func SetTOMLKey

func SetTOMLKey(path, name, key string, value any) error

SetTOMLKey sets one key of table `name` and leaves the table's other lines as they are. Replacing a value preserves its surrounding whitespace and trailing comment. New keys go after the last complete value; missing tables are appended, while an array table with the same name is rejected.

func SetTOMLTable

func SetTOMLTable(path, name string, kvs ...KV) error

SetTOMLTable replaces table `name` with the given keys, or appends it. An existing array table with that name is rejected.

A key whose value is an Inline table is merged into the spelling the file already has for it, rather than written inline beside it, which would define the key twice: when the file holds it as its own table ([name.key], which a replacement of [name] leaves where it is), each entry is set in that table, its other keys and comments kept; when the table holds it as dotted keys (key."x" = …), those lines are kept as written and each entry is set among them. Otherwise it is written inline.

func SetTOMLTables

func SetTOMLTables(path string, prefixes []string, tables []Table) error

SetTOMLTables replaces every ordinary or array table whose name begins with one of the prefixes by the given tables, appended at the end in one write: a set of tables magpie owns as a whole (one per model of its catalog), which would otherwise be rewritten once per table. With no tables it only removes.

func SetTOMLTablesMatching

func SetTOMLTablesMatching(path string, names, prefixes []string, tables []Table) error

SetTOMLTablesMatching replaces tables whose names are exact matches or begin with one of prefixes, then appends the given tables in one write.

func SetTOMLTop

func SetTOMLTop(path string, kvs ...KV) error

SetTOMLTop sets top-level keys in a TOML file, as strings. An existing key is replaced as a whole, its value's every line with it; new keys go right after the last existing top-level key's value, or first in the file when there is none. Every key is located in the file as it was read, so the edit is one write that either happens entirely or not at all.

func SetTOMLTopPreserving

func SetTOMLTopPreserving(path string, kvs ...KV) error

SetTOMLTopPreserving is SetTOMLTop with an existing key's spacing and trailing comment kept. New keys use the same spelling as SetTOMLTop.

func SetYAML

func SetYAML(path string, kvs ...KV) error

SetYAML sets key paths in a YAML file; a value may be a scalar, a map, a slice, a struct with yaml tags or YAMLText. Missing files and parents are created. Only the first mapping document can be edited, with empty or null trailing documents allowed; invalid input or output leaves the file untouched.

func SetYAMLTop

func SetYAMLTop(path string, kvs ...KV) error

SetYAMLTop sets top-level scalar keys without reformatting other entries. Only the first block mapping can be edited, with empty or null trailing documents allowed; invalid input or output leaves the file untouched. Missing files are created.

func SplitLines

func SplitLines(s string) []string

SplitLines splits file text into lines the way the TOML editors here do, keeping a trailing newline as an empty final element.

func TOMLTables

func TOMLTables(path string) ([]string, error)

TOMLTables lists explicit ordinary table headers in file order, excluding array-table headers. A name is the header's key path: a quoted part keeps its quotes, and whitespace around the dots is not part of it, so `[ a . b ]` is the name `a.b`. Missing files return (nil, nil); errors include the path.

func Target

func Target(path string) (string, error)

Target is the file a write to path should replace: path itself, or, when path is a symlink, the file at the end of its links — the path it names even when nothing is there yet. Renaming over the link instead would turn it into a file of its own and leave its target as it was.

func TrimBOM

func TrimBOM(b []byte) []byte

TrimBOM is b without a UTF-8 byte order mark at its start, for a config read some other way than Read.

func WriteAtomic

func WriteAtomic(path string, data []byte) error

WriteAtomic writes data to path via a temp file + rename so a crash can never leave a half-written config behind. File mode and group are preserved. When path is a symlink (a config kept in a dotfiles repo) the file it points at is written and the link stays; a file with other hard links is written in place, see writeInPlace. Once written, temp files earlier writes of path left behind go, see removeStaleTemps.

func WriteTOMLFile

func WriteTOMLFile(path string, lines []string) error

WriteTOMLFile writes lines back as a TOML file, validating the result first so an edit that would leave the document invalid is refused rather than saved. Line endings follow the file's existing ones (joinLinesLike).

Types

type Inline

type Inline []KV

Inline is an inline table, its keys in order, each written quoted. Given to SetTOMLTable it is merged into the spelling the file already has for the key (see there).

type KV

type KV struct {
	Path  string
	Value any
}

KV is one key path (dot-separated, e.g. "model.name") and its new value.

type Raw

type Raw string

Raw is a TOML value written as it is: an array or an inline table the caller has already spelled out.

type Table

type Table struct {
	Name string
	KVs  []KV
}

Table is one TOML table: its header name and its keys, in order.

type YAMLText

type YAMLText string

YAMLText, as a KV's value, is set as the YAML it reads as rather than as a string: a list read with GetYAMLText goes back written as it was.

func EditYAMLTextStrings

func EditYAMLTextStrings(text YAMLText, fn func(string) string) (YAMLText, error)

EditYAMLTextStrings is EditYAMLStrings on YAML text (a YAMLText) rather than a file: fn's answers in place of every string in it. Invalid input or output returns the original text and an error.