Initial commit

Assisted-by: GLM 5.3

internal/frontmatter/frontmatter.go

@@ -0,0 +1,316 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+
+// Package frontmatter parses and writes TOML frontmatter in Markdown
+// post files.
+//
+// Post files start with a TOML table between "+++" delimiter lines. The
+// TOML is carried by an interpres Document, so a save keeps what the
+// author wrote: the key order at every level, the comments, and whether
+// a table was written as a header section or an inline table.
+package frontmatter
+
+import (
+	"bytes"
+	"fmt"
+	"maps"
+	"slices"
+	"strings"
+
+	"sourcedock.dev/petrbalvin/interpres/v2"
+)
+
+// Delimiter fences the TOML frontmatter block.
+const Delimiter = "+++"
+
+// Meta is an order-preserving TOML table. Keys iterate in written
+// order; values keep their interpres-decoded Go types (map[string]any,
+// []any, string, int64, float64, bool, interpres.LocalDate and
+// friends). A Meta parsed from a file keeps the file's comments and
+// nested table shapes through a save.
+type Meta struct {
+	doc *interpres.Document
+}
+
+// NewMeta returns an empty Meta.
+func NewMeta() *Meta {
+	// Parsing nothing always succeeds and yields a document with a
+	// root table, which is what an empty Meta needs; a nil doc (if the
+	// parser ever failed on nothing) leaves an inert Meta whose methods
+	// are all no-ops.
+	doc, _ := interpres.Parse(nil)
+	return &Meta{doc: doc}
+}
+
+// MetaFromMap builds a Meta from a plain map with keys in the given
+// order. Keys missing from order are appended sorted, so output stays
+// deterministic.
+func MetaFromMap(m map[string]any, order []string) *Meta {
+	meta := NewMeta()
+	seen := map[string]bool{}
+	for _, k := range order {
+		if v, ok := m[k]; ok {
+			meta.Set(k, v)
+			seen[k] = true
+		}
+	}
+	rest := make([]string, 0, len(m))
+	for k := range m {
+		if !seen[k] {
+			rest = append(rest, k)
+		}
+	}
+	slices.Sort(rest)
+	for _, k := range rest {
+		meta.Set(k, m[k])
+	}
+	return meta
+}
+
+// Len returns the number of keys.
+func (m *Meta) Len() int { return len(m.Keys()) }
+
+// Keys returns the keys in written order.
+func (m *Meta) Keys() []string {
+	if m.doc == nil {
+		return nil
+	}
+	return m.doc.Root().Keys()
+}
+
+// Get returns the value for key.
+func (m *Meta) Get(key string) (any, bool) {
+	if m.doc == nil {
+		return nil, false
+	}
+	entry, ok := m.doc.Get(key)
+	if !ok {
+		return nil, false
+	}
+	return entry.Value(), true
+}
+
+// Set assigns key, appending it when new so the written order is
+// stable. A []string is stored as the []any the parser produces, so a
+// set value and a parsed one leave a save in the same shape; a map
+// value becomes a sub-table whose keys are written sorted, because a
+// plain map carries no order to keep.
+func (m *Meta) Set(key string, value any) {
+	if list, ok := value.([]string); ok {
+		anyList := make([]any, len(list))
+		for i, s := range list {
+			anyList[i] = s
+		}
+		value = anyList
+	}
+	m.doc.Set(key, value)
+}
+
+// Delete removes key and its position in the order.
+func (m *Meta) Delete(key string) {
+	m.doc.Delete(key)
+}
+
+// Map returns a plain copy of the metadata.
+func (m *Meta) Map() map[string]any {
+	if m.doc == nil {
+		return nil
+	}
+	out := make(map[string]any, len(m.doc.Map()))
+	maps.Copy(out, m.doc.Map())
+	return out
+}
+
+// Clone returns a deep copy that shares no value with the original.
+// The document is re-marshalled and re-parsed, which copies every value
+// and carries the comments, the key order and the table shapes with
+// them. A Meta holding a value no parse could produce (a nil set by
+// hand) falls back to a plain value copy without comments.
+func (m *Meta) Clone() *Meta {
+	if m.doc != nil {
+		if raw, err := interpres.Marshal(m.doc); err == nil {
+			if doc, err := interpres.Parse(raw); err == nil {
+				return &Meta{doc: doc}
+			}
+		}
+	}
+	out := NewMeta()
+	for _, key := range m.Keys() {
+		value, _ := m.Get(key)
+		out.Set(key, deepCopyValue(value))
+	}
+	return out
+}
+
+// deepCopyValue copies the containers so a clone shares no mutable
+// value with its original.
+func deepCopyValue(value any) any {
+	switch v := value.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for key, item := range v {
+			out[key] = deepCopyValue(item)
+		}
+		return out
+	case []any:
+		out := make([]any, len(v))
+		for i, item := range v {
+			out[i] = deepCopyValue(item)
+		}
+		return out
+	case []map[string]any:
+		out := make([]map[string]any, len(v))
+		for i, item := range v {
+			out[i] = deepCopyValue(item).(map[string]any)
+		}
+		return out
+	case []string:
+		return slices.Clone(v)
+	}
+	return value
+}
+
+// Parse splits content into metadata and body. Without frontmatter it
+// returns empty metadata and the full content as body. Line endings are
+// normalised to \n. Invalid frontmatter TOML is an error.
+func Parse(content string) (*Meta, string, error) {
+	text := normaliseFile(content)
+	meta, bodyStart, err := ParseMetadata(text)
+	if err != nil {
+		return nil, "", err
+	}
+	if bodyStart < 0 {
+		return meta, text, nil
+	}
+	return meta, text[bodyStart:], nil
+}
+
+// normaliseFile strips a leading byte-order mark and normalises line
+// endings. A BOM before the opening delimiter would otherwise make the
+// whole frontmatter (draft and publish_at included) silently count as
+// body.
+func normaliseFile(content string) string {
+	text := strings.TrimPrefix(content, "\ufeff")
+	return strings.ReplaceAll(text, "\r\n", "\n")
+}
+
+// ParseMetadata parses only the frontmatter, returning the metadata and
+// the byte offset where the body begins, or -1 when there is no
+// frontmatter. Line endings are normalised to \n before parsing.
+// Invalid frontmatter TOML is an error.
+func ParseMetadata(content string) (*Meta, int, error) {
+	text := normaliseFile(content)
+	lines := strings.Split(text, "\n")
+	if len(lines) == 0 || !isDelimiter(lines[0]) {
+		return NewMeta(), -1, nil
+	}
+	closing := closingIndex(lines)
+	if closing < 0 {
+		return NewMeta(), -1, nil
+	}
+	tomlText := strings.Join(lines[1:closing], "\n")
+	meta := NewMeta()
+	if strings.TrimSpace(tomlText) != "" {
+		doc, err := interpres.Parse([]byte(tomlText))
+		if err != nil {
+			return nil, -1, fmt.Errorf("frontmatter: %w", err)
+		}
+		meta = &Meta{doc: doc}
+	}
+	bodyStart := 0
+	for i := 0; i <= closing; i++ {
+		bodyStart += len(lines[i]) + 1
+	}
+	// A file that ends exactly on the closing delimiter has no trailing
+	// newline; clamp so the slice below can never run past the text.
+	if bodyStart > len(text) {
+		bodyStart = len(text)
+	}
+	if bodyStart < len(text) && text[bodyStart] == '\n' {
+		bodyStart++
+	}
+	return meta, bodyStart, nil
+}
+
+// Dump serialises metadata and body back into a post file string. The
+// body is written verbatim so indented code blocks and leading blank
+// lines survive a save round-trip; only a trailing newline is added.
+// The frontmatter is written from the parsed document, so the author's
+// comments, key order and table shapes survive a save.
+func Dump(meta *Meta, body string) (string, error) {
+	var b strings.Builder
+	b.WriteString(Delimiter)
+	b.WriteByte('\n')
+	if meta.Len() > 0 {
+		tomlText, err := interpres.Marshal(meta.doc)
+		if err != nil {
+			return "", err
+		}
+		b.Write(tomlText)
+		if !bytes.HasSuffix(tomlText, []byte{'\n'}) {
+			b.WriteByte('\n')
+		}
+	}
+	b.WriteString(Delimiter)
+	b.WriteString("\n\n")
+	b.WriteString(body)
+	if !strings.HasSuffix(body, "\n") {
+		b.WriteByte('\n')
+	}
+	return b.String(), nil
+}
+
+func isDelimiter(line string) bool {
+	return strings.TrimSpace(line) == Delimiter
+}
+
+// multiline tracks whether the TOML scanner sits inside a multi-line
+// basic string (three double quotes) or a literal one (three single
+// quotes), where a line reading "+++" is content, not a delimiter, and
+// a line reading "key =" is not a key.
+type multiline struct {
+	basic   bool
+	literal bool
+}
+
+// step consumes one line and reports whether that line sits inside a
+// multi-line string.
+func (m *multiline) step(line string) bool {
+	if m.basic || m.literal {
+		closer := `"""`
+		if m.literal {
+			closer = "'''"
+		}
+		if strings.Contains(line, closer) {
+			m.basic, m.literal = false, false
+		}
+		return true
+	}
+	if eq := strings.Index(line, "="); eq > 0 {
+		rest := strings.TrimSpace(line[eq+1:])
+		switch {
+		case rest == `"""`:
+			m.basic = true
+		case rest == `'''`:
+			m.literal = true
+		case strings.HasPrefix(rest, `"""`) && len(rest) > 5 && !strings.HasSuffix(rest, `"""`):
+			m.basic = true
+		case strings.HasPrefix(rest, `'''`) && len(rest) > 5 && !strings.HasSuffix(rest, `'''`):
+			m.literal = true
+		}
+	}
+	return false
+}
+
+func closingIndex(lines []string) int {
+	var state multiline
+	for i := 1; i < len(lines); i++ {
+		if state.step(lines[i]) {
+			continue
+		}
+		if isDelimiter(lines[i]) {
+			return i
+		}
+	}
+	return -1
+}