okfyaml

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package okfyaml patches an OKF document's YAML frontmatter in place. A patch rewrites only the bytes of the one value it targets, so key order, inline comments, blank lines, quoting and flow/block styles all survive verbatim — re-encoding a mutated yaml.Node tree does not (it collapses comment padding and drops blank lines), and an editor must never reformat a hand-authored document as a side effect of changing one field.

Index

Constants

This section is empty.

Variables

View Source
var ErrUnknownKey = errors.New("okfyaml: unknown frontmatter key")

ErrUnknownKey reports a patch aimed at a key the frontmatter does not define.

Functions

This section is empty.

Types

type Doc

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

Doc is a parsed OKF document: the raw frontmatter YAML, the node tree that locates each value within it, and the body verbatim.

func Parse

func Parse(content []byte) (Doc, bool, error)

Parse splits content into frontmatter and body and decodes the frontmatter into a node tree. ok is false when content is not in the canonical "---\n...\n---\n" form this codebase's writers produce, when the frontmatter is not a plain mapping, or when it uses anchors, aliases or a multi-document stream: a caller that gets ok=false must fall back to read-only rather than risk a corrupting rewrite. err is returned only for frontmatter that is genuinely malformed YAML.

func (Doc) Body

func (d Doc) Body() []byte

Body returns the document body, verbatim and excluding the frontmatter block.

func (Doc) Fields

func (d Doc) Fields() []Field

Fields returns the top-level frontmatter keys in file order.

func (Doc) PatchScalar

func (d Doc) PatchScalar(key, value string) ([]byte, error)

PatchScalar returns the document with key's scalar value replaced by value. It errors when key is absent, when its value is not a single-line scalar, or when the located span does not re-parse to the value it replaced.

func (Doc) PatchTags

func (d Doc) PatchTags(key string, items []string) ([]byte, error)

PatchTags returns the document with key's sequence replaced by items. v1 retypes the whole list rather than editing individual entries. A key whose current value is null is rewritten as a flow sequence; an empty items on a block sequence clears the entries, leaving the key null.

func (Doc) ReplaceBody

func (d Doc) ReplaceBody(body []byte) []byte

ReplaceBody returns the document with body swapped in and the frontmatter block carried over byte for byte.

func (Doc) SetScalar added in v0.4.0

func (d Doc) SetScalar(key, value string) ([]byte, error)

SetScalar returns the document with key set to the scalar value. A key the frontmatter already defines is patched exactly as PatchScalar does, including its refusal of a non-scalar or multi-line value. An absent key is added as a single "key: value" line at the end of the frontmatter block, just before the closing delimiter, with key and value quoted where YAML requires it. Every other key, comment and blank line and the body are kept byte for byte. The result is re-parsed and must read key back as value, or SetScalar errors and returns no bytes.

type Field

type Field struct {
	Key    string
	Value  string
	IsList bool
	IsNull bool
}

Field is one top-level frontmatter key as an editor displays it. Value is the scalar text, or the ", "-joined items of a sequence; it is empty for a nested mapping (a shape v1 does not edit). IsNull marks a YAML null (empty, ~, null), whose Value keeps the spelling as written.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址