PureYAML/Sources/Tagged/Tagged.Dumper.swift
Mihaela Mihaljevic 8df3f0b8d4 feat(emitting): add canonical mode, document markers, and lineWidth
Completes issue #10. Canonical mode follows libyaml's canonical layout
on both the Model and Tagged dump paths (tags explicit, scalars double
quoted, flow one entry per line, anchors and aliases preserved on the
Tagged path). explicitDocumentStart/End wrap the body in --- and ...
markers. lineWidth wraps overflowing flow collections one entry per
line and folds plain block scalars at single-space boundaries, vetoing
any fold that would manufacture syntax, so values always reparse
unchanged.

Closes #10
2026-07-12 14:13:19 +02:00

328 lines
12 KiB
Swift

public extension PureYAML.Tagged {
/// Serializes a tag-preserving node tree back to YAML, re-emitting
/// anchors as `&name`, aliases as `*name` references (not expanded
/// copies), explicit tags, and per-node presentation styles.
///
/// Per-node styles win over the document-wide policy in `options`; a
/// node with a `nil` style falls back to that policy. A requested style
/// the value cannot legally take (a plain-unsafe string asked to be
/// plain, a single-line string asked to be literal) falls back to double
/// quoting, which can represent every string.
struct Dumper: Sendable {
public var options: PureYAML.Emitting.Options
public init(options: PureYAML.Emitting.Options = .default) {
self.options = options
}
public func dump(_ node: PureYAML.Tagged.Node) -> String {
if options.canonical {
var body = canonicalDocument(node)
if options.explicitDocumentEnd {
body += "...\n"
}
return body
}
let scalarRenderer = PureYAML.Emitting.Dumper(options: options)
var body = if isFlowRendered(node) {
renderFlow(node, renderer: scalarRenderer) + "\n"
} else {
renderBlock(node, indent: 0, renderer: scalarRenderer)
.joined(separator: "\n") + "\n"
}
if options.explicitDocumentStart {
body = "---\n" + body
}
if options.explicitDocumentEnd {
body += "...\n"
}
return body
}
}
}
extension PureYAML.Tagged.Dumper {
typealias Node = PureYAML.Tagged.Node
/// The `&anchor !tag` prefix for a node, empty when the node has neither.
/// Anchor precedes tag, matching libyaml's canonical property order.
func properties(_ node: Node) -> String {
var parts: [String] = []
if let anchor = node.anchor, node.kind != .alias {
parts.append("&" + anchor)
}
if let tag = node.tag {
parts.append(renderTag(tag))
}
return parts.joined(separator: " ")
}
/// Built-in tags render in `!!suffix` shorthand; everything else renders
/// verbatim so unknown tag URIs and local tags survive unchanged.
func renderTag(_ tag: PureYAML.Tagged.Tag) -> String {
if tag.isBuiltIn {
return "!!" + tag.rawValue.dropFirst("tag:yaml.org,2002:".count)
}
return "!<" + tag.rawValue + ">"
}
func isFlowRendered(_ node: Node) -> Bool {
switch node {
case let .mapping(mapping):
(mapping.style ?? collectionPolicy) == .flow
case let .sequence(sequence):
(sequence.style ?? collectionPolicy) == .flow
case .scalar, .alias:
false
}
}
var collectionPolicy: PureYAML.Tagged.CollectionStyle {
switch options.collectionStyle {
case .block: .block
case .flow: .flow
}
}
}
// MARK: - Block rendering
extension PureYAML.Tagged.Dumper {
func renderBlock(
_ node: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
switch node {
case .alias:
return [prefix + renderInline(node, renderer: renderer)]
case .scalar:
return renderBlockScalar(node, indent: indent, renderer: renderer)
case let .sequence(sequence):
return renderBlockSequence(sequence, node: node, indent: indent, renderer: renderer)
case let .mapping(mapping):
return renderBlockMapping(mapping, node: node, indent: indent, renderer: renderer)
}
}
func renderBlockScalar(
_ node: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
let props = properties(node)
guard case let .scalar(scalar) = node else {
return [prefix + renderInline(node, renderer: renderer)]
}
if let block = renderLiteralBlock(
scalar,
props: props,
contentIndent: indent + options.indentWidth,
) {
return [prefix + block.header] + block.content
}
let rendered = renderScalarValue(scalar, flow: false, renderer: renderer)
return [prefix + (props.isEmpty ? rendered : props + " " + rendered)]
}
func renderBlockSequence(
_ sequence: PureYAML.Tagged.Sequence,
node: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
let props = properties(node)
var lines: [String] = []
if !props.isEmpty {
lines.append(prefix + props)
}
guard !sequence.values.isEmpty else {
return props.isEmpty ? [prefix + "[]"] : [prefix + props + " []"]
}
for value in sequence.values {
lines.append(contentsOf: renderBlockSequenceItem(value, indent: indent, renderer: renderer))
}
return lines
}
func renderBlockSequenceItem(
_ value: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
if let block = literalBlock(for: value, contentIndent: indent + options.indentWidth) {
return [prefix + "- " + block.header] + block.content
}
if let inline = renderInlineIfSimple(value, renderer: renderer) {
return [inline.isEmpty ? prefix + "-" : prefix + "- " + inline]
}
let childProps = properties(value)
var lines: [String] = []
if childProps.isEmpty {
lines.append(prefix + "-")
} else {
lines.append(prefix + "- " + childProps)
}
lines.append(contentsOf: renderBlockBody(value, indent: indent + options.indentWidth, renderer: renderer))
return lines
}
func renderBlockMapping(
_ mapping: PureYAML.Tagged.Mapping,
node: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
let props = properties(node)
var lines: [String] = []
if !props.isEmpty {
lines.append(prefix + props)
}
guard !mapping.pairs.isEmpty else {
return props.isEmpty ? [prefix + "{}"] : [prefix + props + " {}"]
}
for pair in mapping.pairs {
lines.append(contentsOf: renderBlockPair(pair, indent: indent, renderer: renderer))
}
return lines
}
func renderBlockPair(
_ pair: PureYAML.Tagged.Pair,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
let prefix = String(repeating: " ", count: indent)
var key = renderer.escapeKey(pair.key)
if let keyTag = pair.keyTag {
key = renderTag(keyTag) + " " + key
}
if let block = literalBlock(for: pair.value, contentIndent: indent + options.indentWidth) {
return [prefix + key + ": " + block.header] + block.content
}
if let inline = renderInlineIfSimple(pair.value, renderer: renderer) {
return [inline.isEmpty ? prefix + key + ":" : prefix + key + ": " + inline]
}
let childProps = properties(pair.value)
var lines: [String] = []
if childProps.isEmpty {
lines.append(prefix + key + ":")
} else {
lines.append(prefix + key + ": " + childProps)
}
lines.append(contentsOf: renderBlockBody(pair.value, indent: indent + options.indentWidth, renderer: renderer))
return lines
}
/// The node's content lines with its properties already emitted by the
/// caller (on the `-` or `key:` line), so collections render bare here.
func renderBlockBody(
_ node: Node,
indent: Int,
renderer: PureYAML.Emitting.Dumper,
) -> [String] {
switch node {
case let .sequence(sequence):
renderBlockSequence(
sequence,
node: .sequence(.init(values: sequence.values)),
indent: indent,
renderer: renderer,
)
case let .mapping(mapping):
renderBlockMapping(
mapping,
node: .mapping(.init(pairs: mapping.pairs)),
indent: indent,
renderer: renderer,
)
case .scalar, .alias:
renderBlock(node, indent: indent, renderer: renderer)
}
}
/// The block-scalar form for a scalar node whose style asks for one,
/// with the node's properties folded into the header; `nil` for
/// non-scalars and for scalars that render inline.
func literalBlock(
for node: Node,
contentIndent: Int,
) -> (header: String, content: [String])? {
guard case let .scalar(scalar) = node else {
return nil
}
return renderLiteralBlock(scalar, props: properties(node), contentIndent: contentIndent)
}
/// One-line rendering when the node fits on the parent's line: aliases,
/// scalars without a literal block, flow-styled collections, and empty
/// collections. Returns `nil` when the node needs its own block lines.
func renderInlineIfSimple(
_ node: Node,
renderer: PureYAML.Emitting.Dumper,
) -> String? {
let props = properties(node)
switch node {
case .alias:
return renderInline(node, renderer: renderer)
case let .scalar(scalar):
if renderLiteralBlock(scalar, props: props, contentIndent: 0) != nil {
return nil
}
let rendered = renderScalarValue(scalar, flow: false, renderer: renderer)
return props.isEmpty ? rendered : props + " " + rendered
case let .sequence(sequence):
if isFlowRendered(node) || sequence.values.isEmpty {
return renderInline(node, renderer: renderer)
}
return nil
case let .mapping(mapping):
if isFlowRendered(node) || mapping.pairs.isEmpty {
return renderInline(node, renderer: renderer)
}
return nil
}
}
}
// MARK: - Flow and inline rendering
extension PureYAML.Tagged.Dumper {
func renderInline(
_ node: Node,
renderer: PureYAML.Emitting.Dumper,
) -> String {
let props = properties(node)
let body: String
switch node {
case let .alias(anchor, _):
return "*" + anchor
case let .scalar(scalar):
body = renderScalarValue(scalar, flow: true, renderer: renderer)
case let .sequence(sequence):
body = "[" + sequence.values
.map { renderFlow($0, renderer: renderer) }
.joined(separator: ", ") + "]"
case let .mapping(mapping):
body = "{" + mapping.pairs
.map { pair in
renderer.escapeKey(pair.key) + ": " + renderFlow(pair.value, renderer: renderer)
}
.joined(separator: ", ") + "}"
}
return props.isEmpty ? body : props + " " + body
}
func renderFlow(
_ node: Node,
renderer: PureYAML.Emitting.Dumper,
) -> String {
renderInline(node, renderer: renderer)
}
}