dms-parser 0.5.0

data/lib/dms/emitter.rb

@@ -0,0 +1,674 @@
+# frozen_string_literal: true
+
+# DMS round-trip emitter (SPEC §encode).
+#
+# Re-emits a parsed `Document` as DMS source. Contract:
+#
+#     Dms.decode_document(Dms.encode(Dms.decode_document(source)))
+#
+# is data-equivalent to `Dms.decode_document(source)`, has the same
+# comments at the same attached paths, and uses the same literal forms
+# (integer base, string flavor, heredoc label + modifiers) for values
+# that recorded an `OriginalLiteral`. Float formatting is shortest-
+# round-trip; indentation is 2 spaces; lists and tables default to block
+# form.
+#
+# Round-trip stability: `encode(decode_document(encode(decode_document(src))))`
+# is byte-equal to `encode(decode_document(src))`.
+#
+# Mirrors the Python reference at dms/emitter.py and the Rust reference
+# at language/rust/crates/dms/src/lib.rs.
+
+require "dms/types"
+
+module Dms
+  INDENT_STR = "  "
+
+  # Recursive walk: returns true iff `v` (or any descendant) is an
+  # `UnorderedHash`. Used by `encode` to enforce the SPEC contract that
+  # full-mode round-trip refuses unordered documents.
+  def self._contains_unordered_table?(v)
+    case v
+    when UnorderedHash
+      true
+    when Hash
+      v.each_value { |vv| return true if _contains_unordered_table?(vv) }
+      false
+    when Array
+      v.each { |vv| return true if _contains_unordered_table?(vv) }
+      false
+    else
+      false
+    end
+  end
+
+  class Emitter
+    attr_reader :out
+
+    # ----- canonical entry points (SPEC §encode) ------------------
+
+    # Full-mode round-trip emit (SPEC §encode). Refuses Documents
+    # containing `Dms::UnorderedHash` — see SPEC §"Unordered tables".
+    def self._encode_full(doc)
+      if Dms._contains_unordered_table?(doc.body)
+        raise EncodeError,
+              "encode (full-mode round-trip) refuses Document with " \
+              "Dms::UnorderedHash; unordered tables have arbitrary " \
+              "iteration order — use Dms.encode_lite instead. " \
+              "See SPEC §\"Unordered tables\"."
+      end
+      em = new(doc)
+      em.emit_document
+      em.out.join
+    end
+
+    # Canonical-form emit (SPEC §encode). Drops comments and
+    # `original_forms` even when present in `doc`: integers go out in
+    # decimal, strings in basic-quoted form, no comments are written.
+    # Accepts both full-mode and lite-mode parsed `Document`s.
+    # Round-trip stability is **data-only** —
+    # `decode_document(encode_lite(doc))` is data-equivalent to `doc`,
+    # but lossy by design for comments and source forms.
+    def self._encode_lite(doc)
+      em = new(doc, lite: true)
+      em.emit_document
+      em.out.join
+    end
+
+    # Per-node bucket of attached comments by position.
+    NodeComments = Struct.new(:leading, :inner, :trailing, :floating) do
+      def self.empty
+        new([], [], [], [])
+      end
+    end
+
+    def initialize(doc, lite: false)
+      @doc = doc
+      @out = []
+      @lite = lite
+      @comments_by_path = {}
+      # Lite mode (canonical-form emit) leaves the comment + form
+      # lookups empty even when `doc.comments` / `doc.original_forms`
+      # are populated, so the walker emits no comments and uses
+      # canonical integer/string forms. See SPEC §encode.
+      unless @lite
+        doc.comments.each do |ac|
+          path = ac.path.is_a?(Array) ? ac.path : ac.path.to_a
+          entry = (@comments_by_path[path] ||= NodeComments.empty)
+          case ac.position
+          when :leading then entry.leading << ac.comment
+          when :inner then entry.inner << ac.comment
+          when :trailing then entry.trailing << ac.comment
+          else entry.floating << ac.comment
+          end
+        end
+      end
+      @forms_by_path = {}
+      unless @lite
+        doc.original_forms.each do |path, lit|
+          path_arr = path.is_a?(Array) ? path : path.to_a
+          @forms_by_path[path_arr] ||= lit
+        end
+      end
+      # For is_flow_safe: any descendant comment forces block form.
+      # Empty in lite mode (no comments emitted anyway).
+      @descendant_comment_paths =
+        if @lite
+          []
+        else
+          doc.comments.map do |ac|
+            ac.path.is_a?(Array) ? ac.path : ac.path.to_a
+          end
+        end
+    end
+
+    # ----- helpers -------------------------------------------------
+
+    def push(s)
+      @out << s
+    end
+
+    def push_indent(indent)
+      @out << (INDENT_STR * indent) if indent > 0
+    end
+
+    def emit_document
+      # Lite mode emits no comments, so FM comments don't force a
+      # `+++` block — only an explicit `meta = Some(...)` does.
+      has_fm_comments = !@lite && @doc.comments.any? do |ac|
+        path = ac.path.is_a?(Array) ? ac.path : ac.path.to_a
+        !path.empty? && path[0] == "__fm__"
+      end
+      fm_present = !@doc.meta.nil?
+      if fm_present || has_fm_comments
+        push("+++\n")
+        fm_path = ["__fm__"].freeze
+        if !@doc.meta.nil?
+          emit_table_block(@doc.meta, fm_path, 0)
+        else
+          emit_floating(fm_path, 0)
+        end
+        push("+++\n\n")
+      end
+
+      body = @doc.body
+      body_path = [].freeze
+      if body.is_a?(Hash)
+        emit_table_block(body, body_path, 0)
+      elsif body.is_a?(Array)
+        emit_list_block(body, body_path, 0)
+      else
+        # Scalar root.
+        entry = @comments_by_path[body_path]
+        if entry
+          entry.leading.each { |c| emit_comment_line(c, 0) }
+        end
+        emit_value_inline(body, body_path)
+        emit_trailing_for(body_path)
+        push("\n")
+        if entry
+          entry.floating.each { |c| emit_comment_line(c, 0) }
+        end
+      end
+    end
+
+    # ----- block emitters ------------------------------------------
+
+    def emit_table_block(t, path, indent)
+      # Lite-mode hot path: comments_by_path / forms_by_path are empty
+      # by construction, so child_path / lookups / flow_safe? are pure
+      # overhead. Skipping them halves emit time on bench_realistic.
+      if @lite
+        pad = INDENT_STR * indent
+        t.each do |k, v|
+          # Inline common scalar cases (string/bool/int) to avoid the
+          # emit_value_inline + emit_string/emit_integer dispatch on
+          # the per-kvpair hot path. Real-world configs are dominated
+          # by these three.
+          kf = (k.is_a?(String) && k =~ /\A[A-Za-z_][A-Za-z0-9_-]*\z/) ? k : format_key(k)
+          case v
+          when String
+            if v =~ /[\\"\x00-\x1F]/
+              @out << "#{pad}#{kf}: \"#{Emitter.escape_basic(v)}\"\n"
+            else
+              @out << "#{pad}#{kf}: \"#{v}\"\n"
+            end
+            next
+          when true
+            @out << "#{pad}#{kf}: true\n"
+            next
+          when false
+            @out << "#{pad}#{kf}: false\n"
+            next
+          when Integer
+            @out << "#{pad}#{kf}: #{v}\n"
+            next
+          end
+          can_block =
+            (v.is_a?(Hash) && !v.empty?) || (v.is_a?(Array) && !v.empty?)
+          push_indent(indent)
+          push(kf)
+          push(":")
+          if can_block
+            push("\n")
+            if v.is_a?(Hash)
+              emit_table_block(v, nil, indent + 1)
+            else
+              emit_list_block(v, nil, indent + 1)
+            end
+          else
+            push(" ")
+            emit_value_inline(v, nil)
+            push("\n")
+          end
+        end
+        return
+      end
+      t.each do |k, v|
+        child_path = (path + [k]).freeze
+        entry = @comments_by_path[child_path]
+        if entry
+          entry.leading.each { |c| emit_comment_line(c, indent) }
+        end
+        has_trailing = entry && !entry.trailing.empty?
+        has_inner = has_inner?(child_path)
+        can_block =
+          (v.is_a?(Hash) && !v.empty?) || (v.is_a?(Array) && !v.empty?)
+        needs_block = can_block && !(has_trailing && flow_safe?(v, child_path))
+        push_indent(indent)
+        push(format_key(k))
+        push(":")
+        if needs_block
+          if has_inner
+            push(" ")
+            emit_inner_for(child_path)
+            # emit_inner_for leaves a trailing space; trim it.
+            @out.pop if !@out.empty? && @out[-1] == " "
+          end
+          push("\n")
+          if v.is_a?(Hash)
+            emit_table_block(v, child_path, indent + 1)
+          else
+            emit_list_block(v, child_path, indent + 1)
+          end
+        else
+          push(" ")
+          emit_inner_for(child_path)
+          emit_value_inline(v, child_path)
+          emit_trailing_for(child_path)
+          push("\n")
+        end
+      end
+      emit_floating(path, indent)
+    end
+
+    def emit_list_block(items, path, indent)
+      if @lite
+        items.each do |v|
+          push_indent(indent)
+          push("+")
+          if v.is_a?(Hash) && !v.empty?
+            push("\n")
+            emit_table_block(v, nil, indent + 1)
+          elsif v.is_a?(Array) && !v.empty?
+            push("\n")
+            emit_list_block(v, nil, indent + 1)
+          else
+            push(" ")
+            emit_value_inline(v, nil)
+            push("\n")
+          end
+        end
+        return
+      end
+      items.each_with_index do |v, i|
+        child_path = (path + [i]).freeze
+        entry = @comments_by_path[child_path]
+        if entry
+          entry.leading.each { |c| emit_comment_line(c, indent) }
+        end
+        push_indent(indent)
+        push("+")
+        has_inner = has_inner?(child_path)
+        if v.is_a?(Hash) && !v.empty?
+          if has_inner
+            push(" ")
+            emit_inner_for(child_path)
+            @out.pop if !@out.empty? && @out[-1] == " "
+          end
+          emit_trailing_for(child_path)
+          push("\n")
+          emit_table_block(v, child_path, indent + 1)
+        elsif v.is_a?(Array) && !v.empty?
+          if has_inner
+            push(" ")
+            emit_inner_for(child_path)
+            @out.pop if !@out.empty? && @out[-1] == " "
+          end
+          emit_trailing_for(child_path)
+          push("\n")
+          emit_list_block(v, child_path, indent + 1)
+        else
+          push(" ")
+          emit_inner_for(child_path)
+          emit_value_inline(v, child_path)
+          emit_trailing_for(child_path)
+          push("\n")
+        end
+      end
+      emit_floating(path, indent)
+    end
+
+    # ----- value / scalar emitters --------------------------------
+
+    def emit_value_inline(v, path)
+      case v
+      when true
+        push("true")
+      when false
+        push("false")
+      when Integer
+        emit_integer(v, path)
+      when Float
+        emit_float(v)
+      when LocalDate, LocalTime, LocalDateTime, OffsetDateTime
+        push(v.value)
+      when String
+        emit_string(v, path)
+      when Array
+        if v.empty?
+          push("[]")
+        else
+          push("[")
+          if @lite
+            v.each_with_index do |item, i|
+              push(", ") if i > 0
+              emit_value_inline(item, nil)
+            end
+          else
+            v.each_with_index do |item, i|
+              push(", ") if i > 0
+              emit_value_inline(item, (path + [i]).freeze)
+            end
+          end
+          push("]")
+        end
+      when Hash
+        if v.empty?
+          push("{}")
+        else
+          push("{")
+          first = true
+          if @lite
+            v.each do |k, vv|
+              push(", ") unless first
+              first = false
+              push(format_key(k))
+              push(": ")
+              emit_value_inline(vv, nil)
+            end
+          else
+            v.each do |k, vv|
+              push(", ") unless first
+              first = false
+              push(format_key(k))
+              push(": ")
+              emit_value_inline(vv, (path + [k]).freeze)
+            end
+          end
+          push("}")
+        end
+      else
+        raise EncodeError, "encode: cannot emit #{v.class.name}"
+      end
+    end
+
+    def emit_integer(n, path)
+      if @lite
+        push(n.to_s)
+        return
+      end
+      lit = @forms_by_path[path]
+      if lit && lit.kind == :integer
+        push(lit.integer_lit)
+        return
+      end
+      push(n.to_s)
+    end
+
+    def emit_float(f)
+      if f.nan?
+        push("nan")
+      elsif f.infinite?
+        push(f > 0 ? "inf" : "-inf")
+      else
+        push(Emitter.format_float_ryu_shape(f))
+      end
+    end
+
+    def emit_string(s, path)
+      if @lite
+        push('"')
+        push(Emitter.escape_basic(s))
+        push('"')
+        return
+      end
+      lit = @forms_by_path[path]
+      form = nil
+      form = lit.string_form if lit && lit.kind == :string
+      if form.nil? || form.kind == :basic
+        push('"')
+        push(Emitter.escape_basic(s))
+        push('"')
+        return
+      end
+      if form.kind == :literal
+        push("'")
+        push(s)
+        push("'")
+        return
+      end
+      # Heredoc: stored body is post-modifier. Mirror Python emitter:
+      # for `_fold_paragraphs`, replace each `\n` with `\n\n` so on
+      # re-parse the fold collapses paragraphs back to single lines.
+      body = s
+      if form.modifiers && form.modifiers.any? { |m| m.name == "_fold_paragraphs" }
+        body = body.gsub("\n", "\n\n")
+      end
+      emit_heredoc(body, form.flavor, form.label, form.modifiers || [])
+    end
+
+    def emit_heredoc(body, flavor, label, modifiers)
+      # Compute kvpair indent dynamically from the buffer: count the
+      # leading spaces on the line we're currently writing.
+      joined = @out.join
+      nl = joined.rindex("\n")
+      line_start = nl ? nl + 1 : 0
+      kv_indent = 0
+      i = line_start
+      while i < joined.length && joined[i] == " "
+        kv_indent += 1
+        i += 1
+      end
+      body_indent = " " * (kv_indent + INDENT_STR.length)
+      term_indent = body_indent
+
+      opener = (flavor == :basic_triple) ? '"""' : "'''"
+      push(opener)
+      push(label) if label
+      modifiers.each do |m|
+        push(" ")
+        push(m.name)
+        push("(")
+        m.args.each_with_index do |a, j|
+          push(", ") if j > 0
+          emit_modifier_arg(a)
+        end
+        push(")")
+      end
+      push("\n")
+      unless body.empty?
+        # Mirror Python's `body.split("\n")` (no limit): this keeps
+        # trailing empty fields, matching Ruby `split("\n", -1)`.
+        body.split("\n", -1).each do |line|
+          if line == ""
+            push("\n")
+          else
+            push(body_indent)
+            push(line)
+            push("\n")
+          end
+        end
+      end
+      push(term_indent)
+      if label
+        push(label)
+      else
+        push(opener)
+      end
+    end
+
+    def emit_modifier_arg(v)
+      case v
+      when true
+        push("true")
+      when false
+        push("false")
+      when Integer
+        push(v.to_s)
+      when Float
+        emit_float(v)
+      when String
+        push('"')
+        push(Emitter.escape_basic(v))
+        push('"')
+      when LocalDate, LocalTime, LocalDateTime, OffsetDateTime
+        push(v.value)
+      when Array
+        push("[]")
+      when Hash
+        push("{}")
+      else
+        raise EncodeError, "encode: cannot emit modifier arg #{v.class.name}"
+      end
+    end
+
+    # ----- comment emitters ----------------------------------------
+
+    def emit_comment_line(c, indent)
+      text = c.content
+      prefix = INDENT_STR * indent
+      unless text.include?("\n")
+        push(prefix)
+        push(text)
+        push("\n")
+        return
+      end
+      lines = text.split("\n", -1)
+      lines.each_with_index do |line, j|
+        if j > 0
+          push("\n")
+        else
+          push(prefix)
+        end
+        push(line)
+      end
+      push("\n")
+    end
+
+    def emit_trailing_for(path)
+      return if @lite
+      entry = @comments_by_path[path]
+      return unless entry
+      first = true
+      entry.trailing.each do |c|
+        if first
+          push("  ")
+          first = false
+        else
+          push(" ")
+        end
+        push(c.content)
+      end
+    end
+
+    def emit_inner_for(path)
+      return if @lite
+      entry = @comments_by_path[path]
+      return unless entry
+      entry.inner.each do |c|
+        push(c.content)
+        push(" ")
+      end
+    end
+
+    def has_inner?(path)
+      return false if @lite
+      entry = @comments_by_path[path]
+      entry && !entry.inner.empty?
+    end
+
+    def emit_floating(path, indent)
+      return if @lite
+      entry = @comments_by_path[path]
+      return unless entry
+      entry.floating.each { |c| emit_comment_line(c, indent) }
+    end
+
+    # ----- flow-safety check ---------------------------------------
+
+    def flow_safe?(v, path)
+      plen = path.length
+      @descendant_comment_paths.each do |cpath|
+        return false if cpath.length > plen && cpath[0, plen] == path
+      end
+      case v
+      when String
+        lit = @forms_by_path[path]
+        if lit && lit.kind == :string && lit.string_form &&
+            lit.string_form.kind == :heredoc
+          return false
+        end
+        return true
+      when Array
+        v.each_with_index do |item, i|
+          return false unless flow_safe?(item, (path + [i]).freeze)
+        end
+        return true
+      when Hash
+        v.each do |k, vv|
+          return false unless flow_safe?(vv, (path + [k]).freeze)
+        end
+        return true
+      else
+        true
+      end
+    end
+
+    # ----- module-level helpers ------------------------------------
+
+    # Bare-key chars: `_`, `-`, ASCII alnum, or non-ASCII Unicode L/N.
+    def self.bare_key_char?(c)
+      return true if c == "_" || c == "-"
+      cp = c.ord
+      if cp < 128
+        return (cp >= 0x30 && cp <= 0x39) ||
+               (cp >= 0x41 && cp <= 0x5A) ||
+               (cp >= 0x61 && cp <= 0x7A)
+      end
+      c.match?(/\p{L}|\p{N}/)
+    end
+
+    def self.format_float_ryu_shape(v)
+      s = v.to_s
+      if s.include?("e")
+        mantissa, exp = s.split("e", 2)
+        exp = exp[1..] if exp.start_with?("+")
+        # Drop trailing `.0` from the mantissa so e.g. `1.0e100` -> `1e100`,
+        # matching the Python ryu-shape (Python's `repr(1e100)` -> `1e+100`).
+        mantissa = mantissa[0..-3] if mantissa.end_with?(".0") && mantissa.length > 2
+        return "#{mantissa}e#{exp}"
+      end
+      return s + ".0" unless s.include?(".")
+      s
+    end
+
+    def self.escape_basic(s)
+      out = String.new
+      s.each_char do |c|
+        case c
+        when "\\" then out << "\\\\"
+        when "\"" then out << "\\\""
+        when "\n" then out << "\\n"
+        when "\r" then out << "\\r"
+        when "\t" then out << "\\t"
+        when "\b" then out << "\\b"
+        when "\f" then out << "\\f"
+        else
+          cp = c.ord
+          if cp < 0x20
+            out << format("\\u%04X", cp)
+          else
+            out << c
+          end
+        end
+      end
+      out
+    end
+
+    def self.format_key(k)
+      return k if !k.empty? && k.each_char.all? { |c| bare_key_char?(c) }
+      if !k.include?("'") && !k.include?("\n") && !k.include?("\r")
+        return "'#{k}'"
+      end
+      "\"#{escape_basic(k)}\""
+    end
+  end
+
+  class Emitter
+    # Instance forwarder so `format_key(k)` inside emit_* works.
+    def format_key(k)
+      Emitter.format_key(k)
+    end
+  end
+end