document

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 ReplaceBlock(raw []byte, blocks []Block, key, snippet string) ([]byte, error)
• func ValidateSnippet(text string) error
• type Block
  • func ParseBlocks(raw []byte) ([]Block, error)
• 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) CanRedo() bool
  • func (d Document) CanUndo() bool
  • func (d Document) Dirty() bool
  • func (d Document) ExternallyChanged() bool
  • func (d Document) Insert(snippet string) (Document, error)
  • func (d Document) MarkSaved(saved Document) Document
  • func (d Document) Path() string
  • func (d Document) Raw() []byte
  • func (d Document) Redo() (Document, bool)
  • func (d Document) Reload() (Document, error)
  • func (d Document) Remove(key string) (Document, error)
  • func (d Document) Replace(key, snippet string) (Document, error)
  • func (d Document) ReplaceRaw(raw []byte) (Document, error)
  • func (d Document) Save() (Document, error)
  • func (d Document) SetPath(path string) Document
  • func (d Document) Undo() (Document, 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. The content always ends with a single trailing newline: a literal scalar parsed without its final line break would silently lose it.

func InsertBlock

func InsertBlock(raw []byte, snippet string, knownOrder []string) ([]byte, error)

InsertBlock places snippet before the first existing block whose key follows the new key in knownOrder. A key unknown to knownOrder, or the absence of a later block, appends 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, together with the comment lines that document it (see leadingCommentStart).

func ReplaceBlock

func ReplaceBlock(raw []byte, blocks []Block, key, snippet string) ([]byte, error)

ReplaceBlock substitutes the lines belonging to key with snippet, in place. Unlike RemoveBlock+InsertBlock, only the block's own line range changes.

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 returns the top-level blocks of raw. Multi-document input and flow-style root mappings are rejected: their line ranges cannot be edited block-wise without corrupting the file. An explicit empty document ("---") is treated like an empty file.

type Document

Document owns the YAML editing state. Mutations are atomic and snapshot for undo automatically. Single-threaded - no concurrent use.

knownOrder is the canonical key order Insert/Replace place blocks by; nil means append.

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 and clean, and Save creates the file.

func New

func New(raw []byte, knownOrder []string) (Document, error)

New builds a Document from raw bytes, with no file path. For tests and in-memory use.

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) CanRedo

func (d Document) CanRedo() bool

func (Document) CanUndo

func (d Document) CanUndo() bool

func (Document) Dirty

func (d Document) Dirty() bool

Dirty reports whether the content differs from what was last loaded or saved. Computed, not stored: reverting an edit reads as clean and no mutation path can forget to update a flag.

func (Document) ExternallyChanged

func (d Document) ExternallyChanged() bool

ExternallyChanged reports whether the file on disk was modified since this Document last loaded or saved it. False when there is no path or the file is absent: a save would create it, clobbering nothing. Callers should confirm with the user before overwriting.

func (Document) Insert

func (d Document) Insert(snippet string) (Document, error)

Insert adds snippet, positioned by the canonical key order, and snapshots history. Rolls back with an error when the round-trip check finds the stored block diverging from the snippet.

func (Document) MarkSaved

func (d Document) MarkSaved(saved Document) Document

MarkSaved applies a completed Save onto d. Save runs on a snapshot, so by the time its result arrives d may carry newer edits; replacing d wholesale would drop them. Only the persistence state (loaded, mtime/size) is copied, and Dirty() follows from the current content.

func (Document) Path

func (d Document) Path() string

func (Document) Raw

func (d Document) Raw() []byte

func (Document) Redo

func (d Document) Redo() (Document, bool)

Redo re-applies the most recently undone change, pushing the current state onto the undo history so the redo itself can be undone. Returns false when there is nothing to redo or the snapshot no longer parses. Copy-on-write, mirroring Undo.

func (Document) Reload

func (d Document) Reload() (Document, error)

Reload re-reads the source file, resetting raw, blocks, dirty, and the undo/redo history as if the document had just been loaded. The source is the load path even when SetPath pointed Save elsewhere; the save destination survives. A missing file reloads as empty, mirroring Load. On error the in-memory state is left untouched.

func (Document) Remove

func (d Document) Remove(key string) (Document, 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) (Document, error)

Replace substitutes the block at key in place, leaving its position and the surrounding blank lines and comments untouched, and records one history snapshot. Rolls back with an error when the round-trip check finds the stored block diverging from the snippet.

func (Document) ReplaceRaw

func (d Document) ReplaceRaw(raw []byte) (Document, error)

ReplaceRaw swaps the whole document content, normalising CRLF, and leaves it untouched when raw fails to parse. Does not snapshot: only committed block operations (Insert, Replace, Remove) are undoable.

func (Document) Save

func (d Document) Save() (Document, error)

Save atomically writes the current content to d.path and clears dirty. The file's existing mode is preserved (new files get 0600) and CRLF line endings are restored when the loaded file used them. Errors when d.path is empty.

func (Document) SetPath

func (d Document) SetPath(path string) Document

SetPath overrides the path used by Save; Reload keeps re-reading the original load path. The new path's on-disk state is recorded so ExternallyChanged compares against the save destination instead of reporting a false positive.

func (Document) Undo

func (d Document) Undo() (Document, bool)

Undo restores the previous raw and pushes the undone state onto the redo stack. Returns false when history is empty or the snapshot no longer parses, keeping the current consistent state. The pop is copy-on-write: sibling Document copies share the stack's backing array.

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 ReplaceBlock(raw []byte, blocks []Block, key, snippet string) ([]byte, error)
• func ValidateSnippet(text string) error
• type Block
  • func ParseBlocks(raw []byte) ([]Block, error)
• 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) CanRedo() bool
  • func (d Document) CanUndo() bool
  • func (d Document) Dirty() bool
  • func (d Document) ExternallyChanged() bool
  • func (d Document) Insert(snippet string) (Document, error)
  • func (d Document) MarkSaved(saved Document) Document
  • func (d Document) Path() string
  • func (d Document) Raw() []byte
  • func (d Document) Redo() (Document, bool)
  • func (d Document) Reload() (Document, error)
  • func (d Document) Remove(key string) (Document, error)
  • func (d Document) Replace(key, snippet string) (Document, error)
  • func (d Document) ReplaceRaw(raw []byte) (Document, error)
  • func (d Document) Save() (Document, error)
  • func (d Document) SetPath(path string) Document
  • func (d Document) Undo() (Document, bool)

Constants

const HistoryLimit = 50

HistoryLimit caps the undo stack.

Functions

func BlockContent

func BlockContent(raw []byte, blocks []Block, key string) (string, error)

BlockContent returns the raw lines for a given block key. The content always ends with a single trailing newline: a literal scalar parsed without its final line break would silently lose it.

func InsertBlock

func InsertBlock(raw []byte, snippet string, knownOrder []string) ([]byte, error)

InsertBlock places snippet before the first existing block whose key follows the new key in knownOrder. A key unknown to knownOrder, or the absence of a later block, appends 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, together with the comment lines that document it (see leadingCommentStart).

func ReplaceBlock

func ReplaceBlock(raw []byte, blocks []Block, key, snippet string) ([]byte, error)

ReplaceBlock substitutes the lines belonging to key with snippet, in place. Unlike RemoveBlock+InsertBlock, only the block's own line range changes.

func ValidateSnippet

func ValidateSnippet(text string) error

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

func ParseBlocks(raw []byte) ([]Block, error)

ParseBlocks returns the top-level blocks of raw. Multi-document input and flow-style root mappings are rejected: their line ranges cannot be edited block-wise without corrupting the file. An explicit empty document ("---") is treated like an empty file.

type Document

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

Document owns the YAML editing state. Mutations are atomic and snapshot for undo automatically. Single-threaded - no concurrent use.

knownOrder is the canonical key order Insert/Replace place blocks by; nil means append.

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 and clean, and Save creates the file.

func New

func New(raw []byte, knownOrder []string) (Document, error)

New builds a Document from raw bytes, with no file path. For tests and in-memory use.

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) CanRedo

func (d Document) CanRedo() bool

func (Document) CanUndo

func (d Document) CanUndo() bool

func (Document) Dirty

func (d Document) Dirty() bool

Dirty reports whether the content differs from what was last loaded or saved. Computed, not stored: reverting an edit reads as clean and no mutation path can forget to update a flag.

func (Document) ExternallyChanged

func (d Document) ExternallyChanged() bool

ExternallyChanged reports whether the file on disk was modified since this Document last loaded or saved it. False when there is no path or the file is absent: a save would create it, clobbering nothing. Callers should confirm with the user before overwriting.

func (Document) Insert

func (d Document) Insert(snippet string) (Document, error)

Insert adds snippet, positioned by the canonical key order, and snapshots history. Rolls back with an error when the round-trip check finds the stored block diverging from the snippet.

func (Document) MarkSaved

func (d Document) MarkSaved(saved Document) Document

MarkSaved applies a completed Save onto d. Save runs on a snapshot, so by the time its result arrives d may carry newer edits; replacing d wholesale would drop them. Only the persistence state (loaded, mtime/size) is copied, and Dirty() follows from the current content.

func (Document) Path

func (d Document) Path() string

func (Document) Raw

func (d Document) Raw() []byte

func (Document) Redo

func (d Document) Redo() (Document, bool)

Redo re-applies the most recently undone change, pushing the current state onto the undo history so the redo itself can be undone. Returns false when there is nothing to redo or the snapshot no longer parses. Copy-on-write, mirroring Undo.

func (Document) Reload

func (d Document) Reload() (Document, error)

Reload re-reads the source file, resetting raw, blocks, dirty, and the undo/redo history as if the document had just been loaded. The source is the load path even when SetPath pointed Save elsewhere; the save destination survives. A missing file reloads as empty, mirroring Load. On error the in-memory state is left untouched.

func (Document) Remove

func (d Document) Remove(key string) (Document, 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) (Document, error)

Replace substitutes the block at key in place, leaving its position and the surrounding blank lines and comments untouched, and records one history snapshot. Rolls back with an error when the round-trip check finds the stored block diverging from the snippet.

func (Document) ReplaceRaw

func (d Document) ReplaceRaw(raw []byte) (Document, error)

ReplaceRaw swaps the whole document content, normalising CRLF, and leaves it untouched when raw fails to parse. Does not snapshot: only committed block operations (Insert, Replace, Remove) are undoable.

func (Document) Save

func (d Document) Save() (Document, error)

Save atomically writes the current content to d.path and clears dirty. The file's existing mode is preserved (new files get 0600) and CRLF line endings are restored when the loaded file used them. Errors when d.path is empty.

func (Document) SetPath

func (d Document) SetPath(path string) Document

SetPath overrides the path used by Save; Reload keeps re-reading the original load path. The new path's on-disk state is recorded so ExternallyChanged compares against the save destination instead of reporting a false positive.

func (Document) Undo

func (d Document) Undo() (Document, bool)

Undo restores the previous raw and pushes the undone state onto the redo stack. Returns false when history is empty or the snapshot no longer parses, keeping the current consistent state. The pop is copy-on-write: sibling Document copies share the stack's backing array.