Module: Coradoc::CoreModel::FrontmatterBlock::Codec

Defined in:
lib/coradoc/core_model/frontmatter/codec.rb

Overview

Single source of truth for YAML ↔ FrontmatterBlock translation.

No other code in any gem may call YAML directly for frontmatter. This isolates permitted-classes configuration and error handling in one MECE location (DRY).

The Codec emits flat YAML — values rendered with their natural YAML type. This is what Jekyll, Hugo, VitePress, VuePress, 11ty and every SSG expects: title: Foo / date: 2024-01-01. Round-trip fidelity for typed values (Date, Time, Symbol) is preserved by Psych’s permitted-classes mechanism, not by a custom discriminator scheme.

For the typed-tree representation used by the coradoc-mirror JSON pipeline, see Coradoc::Mirror::Node::FrontmatterValue and Coradoc::Mirror::Handlers::Frontmatter. The typed-tree concern lives in the mirror gem; this Codec stays focused on YAML.

Constant Summary collapse

PERMITTED_CLASSES = 
[Date, Time, DateTime, Symbol].freeze

Class Method Summary collapse

Class Method Details

.from_hash(hash) ⇒ Object

Build a FrontmatterBlock from a Ruby hash with native-typed values (String, Integer, Date, …). Returns an empty block for non-Hash input.



45
46
47
48
49
 
# File 'lib/coradoc/core_model/frontmatter/codec.rb', line 45

def from_hash(hash)
  return FrontmatterBlock.new unless hash.is_a?(Hash)

  build_from_loaded(hash)
end

.from_yaml(yaml_text) ⇒ Object

Parse YAML text into a FrontmatterBlock. Returns an empty FrontmatterBlock on malformed YAML or non-Hash payload. Logs a warning so the conversion pipeline can surface the skip rather than silently dropping user-authored content.



33
34
35
36
37
38
39
40
 
# File 'lib/coradoc/core_model/frontmatter/codec.rb', line 33

def from_yaml(yaml_text)
  return FrontmatterBlock.new if yaml_text.nil? || yaml_text.strip.empty?

  build_from_loaded(load_yaml(yaml_text))
rescue YAML::SyntaxError, Psych::DisallowedClass => e
  Coradoc::Logger.warn("frontmatter parse failed: #{e.message}")
  FrontmatterBlock.new
end

.to_hash(block) ⇒ Object

Return the frontmatter as a native-typed Ruby hash. $schema is included when present.



65
66
67
68
69
 
# File 'lib/coradoc/core_model/frontmatter/codec.rb', line 65

def to_hash(block)
  return {} unless block.is_a?(FrontmatterBlock)

  flat_tree(block)
end

.to_yaml(block) ⇒ Object

Serialize a FrontmatterBlock to canonical YAML text. Does NOT include leading/trailing --- delimiters; the caller wraps the output. Returns ” for empty blocks.



54
55
56
57
58
59
60
61
 
# File 'lib/coradoc/core_model/frontmatter/codec.rb', line 54

def to_yaml(block)
  return '' unless block.is_a?(FrontmatterBlock)

  payload = flat_tree(block)
  return '' if payload.empty?

  YAML.dump(payload).delete_prefix("---\n").delete_suffix("\n...")
end