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 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 EditYAMLStrings(path string, keyPaths []string, fn func(string) string) error
• func GetEnvFile(path, key string) (string, bool)
• func GetJSON(path, keyPath 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 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 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 SetTOMLTop(path string, kvs ...KV) error
• func SetYAML(path string, kvs ...KV) error
• func SetYAMLTop(path string, kvs ...KV) error
• func TOMLTables(path string) ([]string, error)
• func Target(path string) (string, error)
• func WriteAtomic(path string, data []byte) error
• 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.

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 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 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 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 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 Read

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

Read returns the file contents, or (nil, nil) when the file does not exist.

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 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.

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 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 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.

func SetYAMLTop

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

SetYAMLTop sets top-level scalar keys without reformatting other entries. Only a single block mapping can be edited; invalid input or output leaves the file untouched. Missing files are created.

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 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 is 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.

Types

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.