README
¶
document
import "github.com/lucasassuncao/yedit/document"
Package document provides primitives for editing YAML files structured as a flat mapping of top-level keys ("blocks"). It is schema-agnostic — the caller supplies the canonical key order when needed for ordered inserts.
Index
- Constants
- func BlockContent(raw []byte, blocks []Block, key string) (string, error)
- func InsertBlock(raw []byte, snippet string, knownOrder []string) ([]byte, error)
- func RemoveBlock(raw []byte, blocks []Block, key string) ([]byte, error)
- func ValidateSnippet(text string) error
- type Block
- type Document
- func Load(path string, knownOrder []string) (*Document, error)
- func New(raw []byte, knownOrder []string) (*Document, error)
- func (d *Document) BlockContent(key string) (string, error)
- func (d *Document) Blocks() []Block
- func (d *Document) CanUndo() bool
- func (d *Document) Dirty() bool
- func (d *Document) Insert(snippet string) error
- func (d *Document) Path() string
- func (d *Document) Raw() []byte
- func (d *Document) Remove(key string) error
- func (d *Document) Replace(key, snippet string) error
- func (d *Document) ReplaceRaw(raw []byte) error
- func (d *Document) Save() error
- func (d *Document) Undo() bool
Constants
HistoryLimit caps the undo stack.
const HistoryLimit = 50
func BlockContent
func BlockContent(raw []byte, blocks []Block, key string) (string, error)
BlockContent returns the raw lines for a given block key.
func InsertBlock
func InsertBlock(raw []byte, snippet string, knownOrder []string) ([]byte, error)
InsertBlock inserts a YAML snippet into raw, respecting the canonical key order in knownOrder. The snippet is placed before the first existing block whose key follows the new key in knownOrder. If the new key is unknown to knownOrder, or no later block exists, the snippet is appended at the end.
func RemoveBlock
func RemoveBlock(raw []byte, blocks []Block, key string) ([]byte, error)
RemoveBlock deletes the lines belonging to key from raw YAML bytes.
func ValidateSnippet
func ValidateSnippet(text string) error
ValidateSnippet returns an error if the YAML text is not parseable.
type Block
Block represents a top-level YAML key with its line range (1-based).
type Block struct {
Key string
Line int // line of the key node
EndLine int // last line occupied by this block (exclusive of next key)
}
func ParseBlocks
func ParseBlocks(raw []byte) ([]Block, error)
ParseBlocks parses raw YAML bytes and returns top-level blocks.
type Document
Document owns the YAML editing state. All mutations are atomic and snapshot for undo automatically. Single-threaded — no concurrent use.
knownOrder defines the canonical key order used by Insert/Replace to place blocks. Pass nil for unordered append behaviour.
type Document struct {
// contains filtered or unexported fields
}
func Load
func Load(path string, knownOrder []string) (*Document, error)
Load reads a YAML file from path. A non-existent file is not an error — the returned Document is empty, dirty=false, and Save writes to path.
knownOrder is the canonical key order for ordered Insert/Replace.
func New
func New(raw []byte, knownOrder []string) (*Document, error)
New builds a Document from raw bytes. Intended for tests and in-memory use; the resulting document has no file path.
func (*Document) BlockContent
func (d *Document) BlockContent(key string) (string, error)
BlockContent returns the raw lines for a given block key.
func (*Document) Blocks
func (d *Document) Blocks() []Block
func (*Document) CanUndo
func (d *Document) CanUndo() bool
func (*Document) Dirty
func (d *Document) Dirty() bool
func (*Document) Insert
func (d *Document) Insert(snippet string) error
Insert adds snippet to the document, positioned by the canonical key order. Snapshots history and sets dirty on success.
func (*Document) Path
func (d *Document) Path() string
func (*Document) Raw
func (d *Document) Raw() []byte
func (*Document) Remove
func (d *Document) Remove(key string) error
Remove deletes the block with the given key. Returns an error if the key is not present.
func (*Document) Replace
func (d *Document) Replace(key, snippet string) error
Replace removes the block at key and inserts snippet in its schema-ordered position. Records a single history snapshot for the combined operation.
func (*Document) ReplaceRaw
func (d *Document) ReplaceRaw(raw []byte) error
ReplaceRaw replaces the document content with raw, normalising CRLF. If raw fails to parse, the document is left untouched and the error is returned. Does NOT snapshot — direct YAML editing is not tracked in the undo history; only committed block operations (Insert, Replace, Remove) are undoable.
func (*Document) Save
func (d *Document) Save() error
Save writes the current raw to disk at d.path with mode 0600 and clears dirty. Returns an error if d.path is empty.
func (*Document) Undo
func (d *Document) Undo() bool
Undo restores the previous raw from history. Returns false if history is empty. Does not push a new snapshot; dirty is set based on whether the restored raw matches the last-loaded/saved content.
Generated by gomarkdoc
Documentation
¶
Overview ¶
Package document provides primitives for editing YAML files structured as a flat mapping of top-level keys ("blocks"). It is schema-agnostic — the caller supplies the canonical key order when needed for ordered inserts.
Index ¶
- Constants
- func BlockContent(raw []byte, blocks []Block, key string) (string, error)
- func InsertBlock(raw []byte, snippet string, knownOrder []string) ([]byte, error)
- func RemoveBlock(raw []byte, blocks []Block, key string) ([]byte, error)
- func ValidateSnippet(text string) error
- type Block
- type Document
- func (d *Document) BlockContent(key string) (string, error)
- func (d *Document) Blocks() []Block
- func (d *Document) CanUndo() bool
- func (d *Document) Dirty() bool
- func (d *Document) Insert(snippet string) error
- func (d *Document) Path() string
- func (d *Document) Raw() []byte
- func (d *Document) Remove(key string) error
- func (d *Document) Replace(key, snippet string) error
- func (d *Document) ReplaceRaw(raw []byte) error
- func (d *Document) Save() error
- func (d *Document) Undo() bool
Constants ¶
const HistoryLimit = 50
HistoryLimit caps the undo stack.
Variables ¶
This section is empty.
Functions ¶
func BlockContent ¶
BlockContent returns the raw lines for a given block key.
func InsertBlock ¶
InsertBlock inserts a YAML snippet into raw, respecting the canonical key order in knownOrder. The snippet is placed before the first existing block whose key follows the new key in knownOrder. If the new key is unknown to knownOrder, or no later block exists, the snippet is appended at the end.
func RemoveBlock ¶
RemoveBlock deletes the lines belonging to key from raw YAML bytes.
func ValidateSnippet ¶
ValidateSnippet returns an error if the YAML text is not parseable.
Types ¶
type Block ¶
type Block struct {
Key string
Line int // line of the key node
EndLine int // last line occupied by this block (exclusive of next key)
}
Block represents a top-level YAML key with its line range (1-based).
func ParseBlocks ¶
ParseBlocks parses raw YAML bytes and returns top-level blocks.
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document owns the YAML editing state. All mutations are atomic and snapshot for undo automatically. Single-threaded — no concurrent use.
knownOrder defines the canonical key order used by Insert/Replace to place blocks. Pass nil for unordered append behaviour.
func Load ¶
Load reads a YAML file from path. A non-existent file is not an error — the returned Document is empty, dirty=false, and Save writes to path.
knownOrder is the canonical key order for ordered Insert/Replace.
func New ¶
New builds a Document from raw bytes. Intended for tests and in-memory use; the resulting document has no file path.
func (*Document) BlockContent ¶
BlockContent returns the raw lines for a given block key.
func (*Document) Insert ¶
Insert adds snippet to the document, positioned by the canonical key order. Snapshots history and sets dirty on success.
func (*Document) Remove ¶
Remove deletes the block with the given key. Returns an error if the key is not present.
func (*Document) Replace ¶
Replace removes the block at key and inserts snippet in its schema-ordered position. Records a single history snapshot for the combined operation.
func (*Document) ReplaceRaw ¶
ReplaceRaw replaces the document content with raw, normalising CRLF. If raw fails to parse, the document is left untouched and the error is returned. Does NOT snapshot — direct YAML editing is not tracked in the undo history; only committed block operations (Insert, Replace, Remove) are undoable.
Source Files