mdom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 46b3e2018949cf138e98983729796223a7388a612d3b8a7257a55abd9f1bcb53
+  data.tar.gz: df13bcf4a9d0aac9a9e7150a80a9cdf82ba6081a02cfeb1d1d43b63bb467cbbb
+SHA512:
+  metadata.gz: 8662a2697905070ec926e79d9b47dfc9753747dc43437a9498304db9f353d848f13b4cd73113663826c4e9bffb887204fb274ca39c6a0c984f368f95696c6a3f
+  data.tar.gz: 0e4e44ba65089ab2562715fba447ecc5cc0ae1211e700424692c13a8ed98fc5e94bc8145f46a7c9566b26e1d8d4ca594a1c77862c54a7937677c6a09a8373a74

data/lib/mdom/inline_parser.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module MDOM
+  # Tokenizes a run of inline text into inline nodes: Text, Emphasis, Strong,
+  # Code, Link, Image, Softbreak, Hardbreak and escaped characters.
+  #
+  # This is a pragmatic subset of CommonMark inline syntax. Code spans and
+  # links/images are matched textually; emphasis/strong is resolved by finding
+  # the next matching delimiter and recursing into the enclosed text. Delimiter
+  # runs and exact flanking rules are intentionally simplified.
+  module InlineParser
+    ESCAPABLE = /[\x00`*_{}\[\]()#+\-.!>]/.freeze
+    SPECIAL = /[\\`!*_\[\n]/.freeze
+
+    module_function
+
+    def parse(source)
+      Scanner.new(source.to_s).read_nodes
+    end
+
+    class Scanner
+      def initialize(text)
+        @text = text
+        @len = text.length
+        @pos = 0
+      end
+
+      def read_nodes
+        nodes = []
+        while @pos < @len
+          node = read_node
+          nodes << node if node
+        end
+        nodes
+      end
+
+      private
+
+      def read_node
+        case @text[@pos]
+        when "\\" then read_escape
+        when "`" then read_code_span
+        when "!" then read_link_or_image
+        when "[" then read_link_or_image
+        when "\n" then read_break
+        when "*" then read_emphasis
+        when "_" then read_emphasis
+        else read_plain_run
+        end
+      end
+
+      def read_escape
+        nxt = @text[@pos + 1]
+        if nxt && ESCAPABLE.match?(nxt)
+          @pos += 2
+          Text.new(nxt)
+        else
+          @pos += 1
+          Text.new("\\")
+        end
+      end
+
+      def read_code_span
+        count = 1
+        count += 1 while @text[@pos + count] == "`"
+        closer = "`" * count
+        @pos += count
+        closing = @text.index(closer, @pos)
+        if closing.nil?
+          @pos -= count
+          read_plain_run
+        else
+          content = @text[@pos...closing].gsub(/\A +| +\z/, "").gsub(/\n/, " ")
+          @pos = closing + count
+          Code.new(content)
+        end
+      end
+
+      def read_link_or_image
+        image = @text[@pos] == "!"
+        @pos += 1 if image
+        return read_plain_run unless @text[@pos] == "["
+
+        label_start = @pos + 1
+        closing = @text.index("]", label_start)
+        return read_plain_run unless closing
+
+        label = @text[label_start...closing]
+        return read_plain_run unless @text[closing + 1] == "("
+
+        dest_end = @text.index(")", closing + 1)
+        return read_plain_run unless dest_end
+
+        dest, title = split_destination(@text[(closing + 2)...dest_end])
+        @pos = dest_end + 1
+        if image
+          Image.new(dest, alt: label, title: title)
+        else
+          Link.new(dest, title: title, children: InlineParser.parse(label))
+        end
+      end
+
+      def split_destination(raw)
+        raw = raw.strip
+        raw = raw[1..-2] if raw.start_with?("<") && raw.end_with?(">")
+        body = raw
+        title = nil
+        if (m = /\A(.+?)\s+(?:"([^"]*)"|'([^']*)'|\(([^)]*)\))\z/.match(raw))
+          body = m[1]
+          title = m[2] || m[3] || m[4]
+        end
+        [body, title]
+      end
+
+      # A newline preceded by two spaces is a hard break; otherwise soft break.
+      def read_break
+        # Two spaces immediately before the newline => hard break.
+        before = @text[0...@pos]
+        hard = before.end_with?("  ")
+        @pos += 1
+        hard ? Hardbreak.new : Softbreak.new
+      end
+
+      def read_emphasis
+        # Double marker -> strong, single -> emphasis.
+        if @text[@pos, 2] == "**" || @text[@pos, 2] == "__"
+          open = @text[@pos, 2]
+          idx = @pos + 2
+          closer = find_closer(idx, open[0], open.length)
+          if closer
+            inner = @text[idx...closer]
+            @pos = closer + open.length
+            Strong.new(children: InlineParser.parse(inner))
+          else
+            read_plain_run
+          end
+        else
+          open_ch = @text[@pos]
+          idx = @pos + 1
+          # A single marker must close on a lone delimiter, not part of "**".
+          closer = find_closer(idx, open_ch, 1, skip_double: true)
+          if closer
+            inner = @text[idx...closer]
+            @pos = closer + 1
+            Emphasis.new(children: InlineParser.parse(inner))
+          else
+            read_plain_run
+          end
+        end
+      end
+
+      # Find the index of a closing delimiter, scanning from +from+. With
+      # +skip_double+, a doubled delimiter is skipped (so "*a **b** c*" resolves
+      # the outer emphasis to the final lone '*', recursing into the strong).
+      def find_closer(from, ch, width, skip_double: false)
+        i = from
+        while i < @len
+          if @text[i] == ch
+            if width > 1
+              return i if @text[i, width] == ch * width
+            elsif @text[i, 2] == ch * 2
+              i += 2 # skip doubled marker entirely
+              next
+            elsif @text[i, width] == ch * width
+              return i
+            end
+          end
+          i += 1
+        end
+        nil
+      end
+
+      def read_plain_run
+        start = @pos
+        while @pos < @len && !SPECIAL.match?(@text[@pos])
+          @pos += 1
+        end
+        # Guarantee forward progress so a special char that couldn't be parsed
+        # as its own construct is treated as literal text.
+        @pos += 1 if @pos == start
+        Text.new(@text[start...@pos])
+      end
+    end
+  end
+end

data/lib/mdom/node.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module MDOM
+  # Base class for every node in the Markdown tree.
+  #
+  # A node carries a +type+ (a Symbol), an ordered list of +children+, and
+  # optional +attributes+ (a Hash). The +parent+ of a node is maintained
+  # automatically whenever a child is appended or removed.
+  class Node
+    attr_reader :type, :children, :attributes
+    attr_accessor :parent
+
+    # -- construction -------------------------------------------------------
+
+    def initialize(type, attributes: {}, children: [])
+      @type = type
+      @attributes = attributes
+      @children = []
+      @parent = nil
+      children.each { |child| append(child) }
+    end
+
+    # -- children -----------------------------------------------------------
+
+    # Append +child+ to the end of this node's children. Reparents +child+
+    # away from any previous parent. Returns +self+ so it can be chained.
+    def append(child)
+      return self if child.nil?
+
+      child.remove if child.parent
+      child.parent = self
+      @children << child
+      self
+    end
+    alias << append
+
+    # Yield each child in order. Returns an Enumerator when no block is given.
+    def each_child(&block)
+      return enum_for(:each_child) unless block
+
+      @children.each(&block)
+      self
+    end
+    alias each each_child
+
+    def children?
+      !@children.empty?
+    end
+
+    # Remove this node from its current parent, if any. Returns +self+.
+    def remove
+      @parent&.children&.delete(self)
+      @parent = nil
+      self
+    end
+
+    # -- tree navigation ----------------------------------------------------
+
+    # The topmost ancestor (a node whose parent is nil).
+    def root
+      node = self
+      node = node.parent while node.parent
+      node
+    end
+
+    # Depth in the tree: 0 at the root, 1 for its direct children, etc.
+    def depth
+      return 0 if @parent.nil?
+
+      @parent.depth + 1
+    end
+
+    # The chain of ancestors, closest first. Returns [] for a root node.
+    def ancestors
+      list = []
+      node = @parent
+      while node
+        list << node
+        node = node.parent
+      end
+      list
+    end
+
+    # -- traversal and query -------------------------------------------------
+
+    # Depth-first (preorder) traversal that yields this node then its
+    # descendants, depth-first. Returns an Enumerator when no block is given.
+    def walk(&block)
+      return enum_for(:walk) unless block
+
+      block.call(self)
+      @children.each { |child| child.walk(&block) }
+      self
+    end
+
+    # Yield each descendant (including self) whose type matches +type+, or all
+    # nodes when no type is given. With a block given, also yields when the
+    # block returns truthy.
+    def find_all(type = nil)
+      results = []
+      walk do |node|
+        next unless type.nil? || node.type == type
+        next if block_given? && !yield(node)
+
+        results << node
+      end
+      results
+    end
+
+    # The first matching descendant (or self); +type+ may be a Symbol or a
+    # callable, or a block may be supplied.
+    def find(type = nil, &block)
+      predicate =
+        if block
+          block
+        elsif type.is_a?(Symbol)
+          ->(n) { n.type == type }
+        elsif type.respond_to?(:call)
+          type
+        else
+          nil
+        end
+      walk { |node| return node if predicate && predicate.call(node) }
+      nil
+    end
+
+    # Query by one or more types (Symbol or array of Symbols). Returns an array
+    # of matching nodes (including self if it matches) in document order.
+    def [](*types)
+      types = types.flatten
+      find_all.select { |n| types.include?(n.type) }
+    end
+
+    # -- mutation -----------------------------------------------------------
+
+    # Insert +node+ as the sibling immediately before this node.
+    def insert_before(node)
+      parent = @parent
+      raise "cannot insert before a root node" if parent.nil?
+
+      node.remove if node.parent
+      idx = parent.children.index(self)
+      parent.children.insert(idx, node)
+      node.parent = parent
+      self
+    end
+
+    # Insert +node+ as the sibling immediately after this node.
+    def insert_after(node)
+      parent = @parent
+      raise "cannot insert after a root node" if parent.nil?
+
+      node.remove if node.parent
+      idx = parent.children.index(self)
+      parent.children.insert(idx + 1, node)
+      node.parent = parent
+      self
+    end
+
+    # Replace this node in its parent with +node+. Returns +node+.
+    def replace(node)
+      parent = @parent
+      raise "cannot replace a root node" if parent.nil?
+
+      node.remove if node.parent
+      idx = parent.children.index(self)
+      parent.children[idx] = node
+      node.parent = parent
+      @parent = nil
+      node
+    end
+
+    # -- misc ---------------------------------------------------------------
+
+    def text?
+      @type == :text
+    end
+
+    # Concatenate the literal string content of this subtree. Leaves that carry
+    # text expose it via +to_s+ (Text, Code); container nodes recurse.
+    def plain_text
+      return "\n" if @type == :softbreak || @type == :hardbreak
+      return to_s.to_s if @children.empty?
+
+      @children.map(&:plain_text).join
+    end
+
+    # Serialize this node (and its subtree) back to Markdown.
+    def to_markdown
+      MDOM::Serializer.serialize(self)
+    end
+    alias markdown to_markdown
+
+    def empty?
+      @children.empty?
+    end
+
+    # A compact, single-line summary of this node (its own type/attributes only,
+    # without recursing into children).
+    def to_s
+      "#<#{short_class}#{detail}>"
+    end
+
+    # A human-readable tree rendering of this node and its descendants.
+    def inspect
+      pretty_print
+    end
+
+    # Render this node plus its subtree as an indented, printable tree.
+    def pretty_print(level = 0)
+      indent = "  " * level
+      children = @children.empty? ? "" : "\n" + @children.map { |c| c.pretty_print(level + 1) }.join("\n")
+      "#{indent}#<#{short_class}#{detail}>#{children}"
+    end
+
+    private
+
+    # The short class name (e.g. "MDOM::Paragraph" -> "Paragraph"), falling back
+    # to the type symbol for plain nodes.
+    def short_class
+      name = self.class.name
+      name ? name.split("::").last : type.inspect
+    end
+
+    # A short description of this node's own salient data, e.g. ' level=2' for a
+    # heading, ' "text"' for a text node.
+    def detail
+      case type
+      when Types::TEXT, Types::CODE
+        " #{value.inspect}"
+      when Types::CODE_BLOCK
+        lang = attributes[:lang] ? "lang=#{attributes[:lang].inspect} " : ""
+        " #{lang}literal=#{literal.inspect}"
+      when Types::HEADING
+        " level=#{level}"
+      when Types::LIST
+        ordered = attributes[:ordered] ? "ordered" : "unordered"
+        start = attributes[:start] ? ", start=#{attributes[:start]}" : ""
+        " #{ordered}#{start}"
+      when Types::LIST_ITEM
+        task = attributes[:task] ? ", task" : ""
+        checked = attributes[:checked] ? "=checked" : ""
+        task.empty? ? "" : " (#{task.sub(', ', '')}#{checked})"
+      when Types::LINK
+        title = attributes[:title] ? " title=#{attributes[:title].inspect}" : ""
+        " #{attributes[:destination].inspect}#{title}"
+      when Types::IMAGE
+        title = attributes[:title] ? " title=#{attributes[:title].inspect}" : ""
+        " #{attributes[:destination].inspect} alt=#{attributes[:alt].inspect}#{title}"
+      else
+        attributes.empty? ? "" : " #{attributes.inspect}"
+      end
+    end
+  end
+end

data/lib/mdom/nodes.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module MDOM
+  # Node type constants, shared across the code base.
+  module Types
+    DOCUMENT   = :document
+    HEADING    = :heading
+    PARAGRAPH  = :paragraph
+    LIST       = :list
+    LIST_ITEM  = :list_item
+    LIST_ITEM_LINE = :list_item_line
+    BLOCKQUOTE = :blockquote
+    CODE_BLOCK = :code_block
+    HRULE      = :hrule
+
+    TEXT       = :text
+    EMPHASIS   = :emphasis
+    STRONG     = :strong
+    CODE       = :code
+    LINK       = :link
+    IMAGE      = :image
+    SOFTBREAK  = :softbreak
+    HARDBREAK  = :hardbreak
+  end
+
+  # -- Block nodes ----------------------------------------------------------
+
+  # Each concrete node class fixes its +type+ and declares which children it
+  # accepts. Subclassing Node keeps everything a Node so traversal is uniform.
+  class BlockNode < Node
+  end
+
+  class Document < BlockNode
+    def initialize(children: [])
+      super(Types::DOCUMENT, children: children)
+    end
+  end
+
+  class Heading < BlockNode
+    attr_reader :level
+
+    def initialize(level, children: [], attributes: {})
+      @level = level.to_i
+      super(Types::HEADING, attributes: attributes.merge(level: @level), children: children)
+    end
+  end
+
+  class Paragraph < BlockNode
+    def initialize(children: [])
+      super(Types::PARAGRAPH, children: children)
+    end
+  end
+
+  class List < BlockNode
+    # ordered: true/false, tight: true/false, start: integer for ordered lists
+    def initialize(ordered: false, tight: true, start: nil, children: [], attributes: {})
+      attrs = { ordered: ordered, tight: tight }.merge(attributes)
+      attrs[:start] = start unless start.nil?
+      super(Types::LIST, attributes: attrs, children: children)
+    end
+
+    def ordered?
+      attributes[:ordered]
+    end
+  end
+
+  class ListItem < BlockNode
+    def initialize(children: [])
+      super(Types::LIST_ITEM, children: children)
+    end
+  end
+
+  class Blockquote < BlockNode
+    def initialize(children: [])
+      super(Types::BLOCKQUOTE, children: children)
+    end
+  end
+
+  class CodeBlock < BlockNode
+    # lang: language string (may be nil), fenced: true/false, literal: source text
+    def initialize(literal, lang: nil, fenced: true, attributes: {})
+      attrs = { fenced: fenced }.merge(attributes)
+      attrs[:lang] = lang unless lang.nil?
+      super(Types::CODE_BLOCK, attributes: attrs)
+      # Code block text is kept as a raw string, not child nodes.
+      @literal = literal
+    end
+
+    attr_reader :literal
+
+    def lang
+      attributes[:lang]
+    end
+
+    def fenced?
+      attributes[:fenced]
+    end
+
+    def to_s
+      "#<MDOM::CodeBlock fenced=#{fenced?} lang=#{lang.inspect}>"
+    end
+  end
+
+  class Hrule < BlockNode
+    def initialize(attributes: {})
+      super(Types::HRULE, attributes: attributes)
+    end
+  end
+
+  def self.allocate_node(type, **attrs)
+    case type
+    when Types::HEADING then Heading.new(attrs.fetch(:level, 1), attributes: attrs[:attributes])
+    when Types::PARAGRAPH then Paragraph.new
+    when Types::LIST then List.new(**attrs)
+    when Types::LIST_ITEM then ListItem.new
+    when Types::BLOCKQUOTE then Blockquote.new
+    when Types::HRULE then Hrule.new
+    else
+      BlockNode.new(type, attributes: attrs)
+    end
+  end
+
+  # -- Inline nodes ---------------------------------------------------------
+
+  class InlineNode < Node
+  end
+
+  class Text < InlineNode
+    def initialize(value)
+      @value = value
+      super(Types::TEXT)
+    end
+
+    attr_reader :value
+
+    def to_s
+      @value
+    end
+  end
+
+  class Emphasis < InlineNode
+    def initialize(children: [])
+      super(Types::EMPHASIS, children: children)
+    end
+  end
+
+  class Strong < InlineNode
+    def initialize(children: [])
+      super(Types::STRONG, children: children)
+    end
+  end
+
+  class Code < InlineNode
+    def initialize(value)
+      @value = value
+      super(Types::CODE)
+    end
+
+    attr_reader :value
+
+    def to_s
+      @value
+    end
+  end
+
+  class Link < InlineNode
+    def initialize(dest, title: nil, children: [])
+      attrs = { destination: dest }
+      attrs[:title] = title unless title.nil?
+      super(Types::LINK, attributes: attrs, children: children)
+    end
+
+    def destination
+      attributes[:destination]
+    end
+
+    def title
+      attributes[:title]
+    end
+  end
+
+  class Image < InlineNode
+    def initialize(dest, alt: nil, title: nil)
+      attrs = { destination: dest }
+      attrs[:alt] = alt unless alt.nil?
+      attrs[:title] = title unless title.nil?
+      super(Types::IMAGE, attributes: attrs)
+    end
+
+    def destination
+      attributes[:destination]
+    end
+
+    def alt
+      attributes[:alt]
+    end
+
+    def title
+      attributes[:title]
+    end
+  end
+
+  class Softbreak < InlineNode
+    def initialize
+      super(Types::SOFTBREAK)
+    end
+  end
+
+  class Hardbreak < InlineNode
+    def initialize
+      super(Types::HARDBREAK)
+    end
+  end
+end

data/lib/mdom/parser.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module MDOM
+  module Parser
+    extend self
+
+    HEADING_RE = /\A(\#{1,6})[ \t]+(.*?)[ \t]*\z/.freeze
+    SETEXT_RE = /\A\s*([=-]+)\s*\z/.freeze
+    FENCE_RE = /\A([ ]{0,3})(`{3,}|~{3,})(.*)\z/.freeze
+    HRULE_RE = /\A\s*((\*\s*){3,}|(-\s*){3,}|(_\s*){3,})\z/.freeze
+    QUOTE_RE = /\A[ ]{0,3}>[ \t]?(.*)\z/.freeze
+    LIST_RE = /\A([ ]*)([-*+])([ \t]+)(.*)\z/.freeze
+    ORDERED_RE = /\A([ ]*)(\d{1,9})([.)])([ \t]+)(.*)\z/.freeze
+    TASK_RE = /\A\[([ xX])\][ \t]+(.*)\z/.freeze
+
+    def read(source)
+      Reader.new(normalize(source)).parse
+    end
+
+    def normalize(source)
+      s = source.to_s
+      s = s.gsub(/\r\n?/, "\n").sub(/\A\n+/, "").chomp
+      return [] if s.empty?
+
+      s.split("\n", -1).map { |line| expand_leading_tabs(line) }
+    end
+
+    # Expand leading tab characters in +line+ into spaces at 4-column tab
+    # stops. This normalizes list/quote indentation so the block parser can
+    # reason about column widths, while leaving the non-indentation content
+    # (including tabs inside code or text) untouched. A tab stop positions the
+    # next character at the next multiple of 4.
+    def expand_leading_tabs(line)
+      i = 0
+      col = 0
+      out = +""
+      while i < line.length
+        ch = line[i]
+        case ch
+        when " "
+          out << " "
+          col += 1
+          i += 1
+        when "\t"
+          target = (col / 4 + 1) * 4
+          out << " " * (target - col)
+          col = target
+          i += 1
+        else
+          out << line[i..]
+          break
+        end
+      end
+      out
+    end
+
+    # Line-oriented block scanner. parse_blocks returns a flat array of sibmling
+    # block nodes (and nothing else), so callers don't juggle an index.
+    class Reader
+      def initialize(lines)
+        @lines = lines
+        @pos = 0
+      end
+
+      def parse
+        Document.new(children: parse_blocks)
+      end
+
+      def self.parse_lines(lines)
+        new(lines).send(:parse_blocks)
+      end
+
+      private
+
+      def eof?
+        @pos >= @lines.length
+      end
+
+      def current
+        @lines[@pos]
+      end
+
+      def peek(offset = 1)
+        @lines[@pos + offset]
+      end
+
+      def blank?(line)
+        line.nil? || line.strip.empty?
+      end
+
+      def parse_blocks
+        blocks = []
+        while !eof?
+          if blank?(current)
+            @pos += 1
+            next
+          end
+
+          block = parse_block
+          blocks << block if block
+        end
+        blocks
+      end
+
+      def parse_block
+        line = current
+
+        if (m = FENCE_RE.match(line))
+          return parse_fenced_code(m) if fence_safe?(m)
+        end
+
+        if (om = ORDERED_RE.match(line))
+          return parse_list(om, ordered: true)
+        end
+        if (um = LIST_RE.match(line))
+          return parse_list(um, ordered: false)
+        end
+
+        if HRULE_RE.match(line)
+          @pos += 1
+          return Hrule.new
+        end
+
+        if (q = QUOTE_RE.match(line))
+          return parse_blockquote(q)
+        end
+
+        if (h = HEADING_RE.match(line))
+          text = h[2].sub(/[ \t]+#+[ \t]*\z/, "").strip
+          @pos += 1
+          return Heading.new(h[1].length, children: inline_children(text))
+        end
+
+        if setext_heading?
+          return parse_setext_heading
+        end
+
+        parse_paragraph
+      end
+
+      def fence_safe?(m)
+        return true unless m[2].start_with?("`")
+
+        !m[3].include?("`")
+      end
+
+      def parse_fenced_code(m)
+        indent = m[1].length
+        marker = m[2][0]
+        fence_len = m[2].length
+        info = m[3].strip
+        lang = info.empty? ? nil : info.split(/\s+/).first
+
+        @pos += 1
+        content = []
+        while !eof?
+          line = current
+          if (cm = FENCE_RE.match(line)) && cm[2][0] == marker && cm[2].length >= fence_len && cm[1].length <= 3
+            @pos += 1
+            break
+          end
+          content << line[indent..].to_s
+          @pos += 1
+        end
+        CodeBlock.new(content.join("\n"), lang: lang, fenced: true)
+      end
+
+      def setext_heading?
+        !blank?(current) && !HRULE_RE.match(current) && SETEXT_RE.match(peek(1).to_s)
+      end
+
+      def parse_setext_heading
+        text = current.strip
+        level = SETEXT_RE.match(peek(1))[1].start_with?("=") ? 1 : 2
+        @pos += 2
+        Heading.new(level, children: inline_children(text))
+      end
+
+      def parse_blockquote(quote)
+        quote_lines = []
+        while !eof? && (m = QUOTE_RE.match(current))
+          quote_lines << m[1]
+          @pos += 1
+        end
+        Blockquote.new(children: Reader.parse_lines(quote_lines))
+      end
+
+      def parse_list(marker, ordered:)
+        start = ordered ? marker[2].to_i : nil
+        items = []
+        while !eof?
+          line = current
+          lm = ORDERED_RE.match(line) || LIST_RE.match(line)
+          break if lm.nil?
+          break if (ORDERED_RE.match(line).nil?) == ordered
+
+          marker_len = marker_width(lm)
+          content = lm[5] || lm[4]
+          task = false
+          checked = false
+          if (tm = TASK_RE.match(content))
+            task = true
+            checked = tm[1].downcase == "x"
+            content = tm[2]
+          end
+          @pos += 1
+
+          item_lines = [content]
+          while !eof? && !blank?(current)
+            l = current
+            child = ORDERED_RE.match(l) || LIST_RE.match(l)
+            break if child && marker_width(child) <= marker_len
+
+            item_lines << l
+            @pos += 1
+          end
+
+          li = ListItem.new
+          Reader.parse_lines(item_lines).each { |n| li.append(n) }
+          li.attributes[:task] = true if task
+          li.attributes[:checked] = checked if task
+          items << li
+        end
+
+        list = List.new(ordered: ordered, tight: true, start: start)
+        items.each { |li| list.append(li) }
+        list
+      end
+
+      # Width in columns of a list marker prefix (indent + bullet/number + space).
+      def marker_width(m)
+        content = m[5] || m[4]
+        m[0].length - content.length
+      end
+
+      def parse_paragraph
+        collected = []
+        while !eof? && !blank?(current) && !block_start?(current)
+          collected << current.strip
+          @pos += 1
+        end
+        Paragraph.new(children: inline_children(collected.join("\n")))
+      end
+
+      def block_start?(line)
+        return true if FENCE_RE.match(line)
+        return true if LIST_RE.match(line) || ORDERED_RE.match(line)
+        return true if HRULE_RE.match(line)
+        return true if QUOTE_RE.match(line)
+        return true if HEADING_RE.match(line)
+
+        false
+      end
+
+      # Parse a run of inline text into inline nodes.
+      def inline_children(text)
+        return [] if text.to_s.empty?
+
+        nodes = InlineParser.parse(text)
+        trim_hardbreak_text(nodes)
+      end
+
+      # A hard break is represented by two trailing spaces before the newline.
+      # The text node emitted before it still carries those spaces; trim them so
+      # the model has the break (not literal spaces) as its semantic marker.
+      def trim_hardbreak_text(nodes)
+        out = []
+        nodes.each_with_index do |node, i|
+          if node.text? && nodes[i + 1]&.type == :hardbreak
+            value = node.value.sub(/ {2}\z/, "")
+            out << (value.empty? ? nil : Text.new(value))
+          else
+            out << node
+          end
+        end
+        out.compact
+      end
+    end
+  end
+
+  # Public entry point: parse +source+ into an MDOM::Document tree.
+  def self.parse(source)
+    Parser.read(source)
+  end
+end

data/lib/mdom/serializer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module MDOM
+  # Serializes an MDOM tree back to a Markdown string. Traversal is driven by
+  # node type; the context (indentation level, in-blockquote flag, list marker)
+  # flows downward so nested lists and blockquotes render correctly.
+  class Serializer
+    # Serialize +node+ to Markdown. Returns a String.
+    def self.serialize(node, indent: 0, blockquote: false)
+      new.serialize(node, indent: indent, blockquote: blockquote)
+    end
+
+    def serialize(node, indent: 0, blockquote: false)
+      case node.type
+      when Types::DOCUMENT then serialize_document(node)
+      when Types::HEADING then serialize_heading(node, indent: indent, blockquote: blockquote)
+      when Types::PARAGRAPH then serialize_paragraph(node, indent: indent, blockquote: blockquote)
+      when Types::LIST then serialize_list(node, indent: indent, blockquote: blockquote)
+      when Types::LIST_ITEM then serialize_list_item(node, indent: indent, blockquote: blockquote)
+      when Types::BLOCKQUOTE then serialize_blockquote(node, indent: indent)
+      when Types::CODE_BLOCK then serialize_code_block(node, indent: indent, blockquote: blockquote)
+      when Types::HRULE then serialize_hrule(indent: indent, blockquote: blockquote)
+      else serialize_inline(node)
+      end
+    end
+
+    private
+
+    def serialize_document(node)
+      blocks = node.children.map { |c| serialize(c) }
+      join_blocks(blocks)
+    end
+
+    def serialize_heading(node, indent:, blockquote:)
+      prefix = spaces(indent)
+      text = serialize_inline_children(node.children)
+      line = "#{'#' * node.level} #{text}"
+      wrap(prefix + line, blockquote)
+    end
+
+    def serialize_paragraph(node, indent:, blockquote:)
+      prefix = spaces(indent)
+      inner = serialize_inline_children(node.children)
+      inner_lines = inner.split("\n").map { |l| prefix + l }
+      # Hard breaks (two trailing spaces) were captured as soft/hardbreak nodes;
+      # join preserved '\n' and treat each line under the same prefix.
+      wrap_inline_lines(inner_lines.join("\n"), blockquote)
+    end
+
+    def serialize_list(node, indent:, blockquote:)
+      marker = node.ordered? ? nil : "-"
+      start = node.ordered? ? (node.attributes[:start] || 1) : nil
+      lines = node.children.each_with_index.map do |item, idx|
+        num = start ? "#{start + idx}." : marker
+        serialize_list_item(item, marker: num, indent: indent, blockquote: blockquote)
+      end
+      wrap(lines.join("\n"), blockquote)
+    end
+
+    def serialize_list_item(node, indent:, blockquote:, marker:)
+      head = marker || "-"
+      prefix = spaces(indent)
+      marker_col = indent + head.length + 1
+      task = node.attributes[:task] ? "[#{node.attributes[:checked] ? 'x' : ' '}] " : ""
+
+      first = node.children.first
+      first_line =
+        if first && first.type == Types::PARAGRAPH
+          "#{prefix}#{head} #{task}#{first.plain_text}"
+        elsif first
+          "#{prefix}#{head} #{task}#{serialize(first, indent: marker_col, blockquote: blockquote).strip}"
+        else
+          "#{prefix}#{head} #{task}"
+        end
+
+      rest = node.children[1..] || []
+      rest_lines = rest.map { |c| serialize(c, indent: marker_col, blockquote: blockquote) }
+      [first_line, *rest_lines].join("\n")
+    end
+
+    def serialize_blockquote(node, indent:)
+      inner = node.children.map { |c| serialize(c) }.join("\n\n")
+      inner.lines.map(&:chomp).map { |l| l.strip.empty? ? ">" : "#{spaces(indent)}> #{l}" }.join("\n")
+    end
+
+    def serialize_code_block(node, indent:, blockquote:)
+      prefix = spaces(indent)
+      if node.fenced?
+        fence = "```"
+        lang = node.lang ? node.lang : ""
+        content = node.literal.to_s.lines.map { |l| prefix + l.chomp }.join("\n")
+        wrap("#{prefix}#{fence}#{lang}\n#{content}\n#{prefix}#{fence}", blockquote)
+      else
+        # Indented code: 4 spaces.
+        lines = node.literal.to_s.split("\n").map { |l| prefix + "    " + l }
+        wrap(lines.join("\n"), blockquote)
+      end
+    end
+
+    def serialize_hrule(indent:, blockquote:)
+      wrap(spaces(indent) + "---", blockquote)
+    end
+
+    # -- inline -------------------------------------------------------------
+
+    def serialize_inline(node)
+      serialize_inline_children(node.children)
+    end
+
+    def serialize_inline_children(children)
+      children.map { |c| serialize_inline_node(c) }.join
+    end
+
+    def serialize_inline_node(node)
+      case node.type
+      when Types::TEXT then node.value.to_s
+      when Types::EMPHASIS then "*#{serialize_inline_children(node.children)}*"
+      when Types::STRONG then "**#{serialize_inline_children(node.children)}**"
+      when Types::CODE then "`#{node.value}`"
+      when Types::LINK then serialize_link(node)
+      when Types::IMAGE then serialize_image(node)
+      when Types::SOFTBREAK then "\n"
+      when Types::HARDBREAK then "  \n"
+      when Types::DOCUMENT, Types::PARAGRAPH, Types::HEADING
+        serialize_inline_children(node.children)
+      else node.respond_to?(:value) ? node.value.to_s : ""
+      end
+    end
+
+    def serialize_link(node)
+      label = serialize_inline_children(node.children)
+      title = node.title ? %( "#{node.title}") : ""
+      "[#{label}](#{node.destination}#{title})"
+    end
+
+    def serialize_image(node)
+      title = node.title ? %( "#{node.title}") : ""
+      "![#{node.alt}](#{node.destination}#{title})"
+    end
+
+    # -- helpers ------------------------------------------------------------
+
+    def spaces(n)
+      " " * n
+    end
+
+    # Join top-level blocks with a single blank line between them.
+    def join_blocks(blocks)
+      blocks.map { |b| b.sub(/\A\n+|\n+\z/, "") }.join("\n\n")
+    end
+
+    # Prefix already-indented block content with a blockquote marker per line.
+    def wrap(content, blockquote)
+      return content unless blockquote
+
+      content.lines.map { |l| l.strip.empty? ? ">" : "> #{l}" }.join
+    end
+
+    def wrap_inline_lines(content, blockquote)
+      return content unless blockquote
+
+      content.lines.map { |l| l.strip.empty? ? ">" : "> #{l}" }.join
+    end
+  end
+end

data/lib/mdom/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MDOM
+  VERSION = "0.1.0"
+end

data/lib/mdom.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "mdom/version"
+require_relative "mdom/node"
+require_relative "mdom/nodes"
+require_relative "mdom/parser"
+require_relative "mdom/inline_parser"
+require_relative "mdom/serializer"
+
+module MDOM
+  # Serialize a node (or subtree) back to a Markdown string.
+  def self.serialize(node)
+    Serializer.serialize(node)
+  end
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: mdom
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- mdom
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: MDOM parses Markdown into a node tree (block + inline), supports traversal,
+  querying and mutation, and serializes back to a Markdown string.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/mdom.rb
+- lib/mdom/inline_parser.rb
+- lib/mdom/node.rb
+- lib/mdom/nodes.rb
+- lib/mdom/parser.rb
+- lib/mdom/serializer.rb
+- lib/mdom/version.rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: 'A Markdown DOM: a self-contained AST for Markdown.'
+test_files: []