mdom 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46b3e2018949cf138e98983729796223a7388a612d3b8a7257a55abd9f1bcb53
-  data.tar.gz: df13bcf4a9d0aac9a9e7150a80a9cdf82ba6081a02cfeb1d1d43b63bb467cbbb
+  metadata.gz: f5fd39950b36dde37a473d2ed62086a94a218bf3d7fc17bfc107fe2b443c2003
+  data.tar.gz: 15d24864d48fe97e4d82e5990f9163578b6a4b55104d195e87c4e24f14d26f1f
 SHA512:
-  metadata.gz: 8662a2697905070ec926e79d9b47dfc9753747dc43437a9498304db9f353d848f13b4cd73113663826c4e9bffb887204fb274ca39c6a0c984f368f95696c6a3f
-  data.tar.gz: 0e4e44ba65089ab2562715fba447ecc5cc0ae1211e700424692c13a8ed98fc5e94bc8145f46a7c9566b26e1d8d4ca594a1c77862c54a7937677c6a09a8373a74
+  metadata.gz: 995dfd2579600430baedb7592b22ef2c94908c2bf3e16b1daa33550f3058d25783275af0237d00e7152876e14156befe18a2894d087f9cc556acdc7fe36f32ad
+  data.tar.gz: f286b92331b99bb57250df4d13ea1d4e5e08dc9020b2c8cb3e90e5f5522430897cf112c0ffce0dd05f280a63de5f560869c8a8dda444946d072a0296977cb0c6

data/lib/mdom/builder.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module MDOM
+  # A builder (DSL) for constructing MDOM trees programmatically, as an
+  # alternative to parsing Markdown text.
+  #
+  # Every method both appends the constructed node to the node currently being
+  # built and returns the builder itself, so calls chain. Blocks nest: while a
+  # block runs, the node it creates becomes the builder's current target, and
+  # the previous target is restored when the block returns.
+  #
+  #   doc = MDOM.build do |b|
+  #     b.h1 "Title"
+  #     b.p "A paragraph with *emphasis*."
+  #     b.list do
+  #       b.item "one"
+  #       b.item "two"
+  #     end
+  #   end
+  #   doc.to_markdown
+  #
+  # String arguments to block- and inline-level methods are run through the
+  # inline parser, so *emphasis*, **strong**, `code`, [links](url) and
+  # ![images](src) are recognised. Use the explicit inline methods
+  # (+em+, +strong+, +code_span+, +link+, +image+) when you need an exact
+  # structure; their string arguments are treated as literal text unless you
+  # nest an explicit method inside a block.
+  class Builder
+    # Build a document with +block+ (or a nested block passed to an explicit
+    # +builder+) and return it. See MDOM.build.
+    def self.build(builder = new, &block)
+      builder.document(&block)
+      builder.to_document
+    end
+
+    def initialize
+      @document = Document.new
+      @stack = [@document]
+    end
+
+    # -- block level ---------------------------------------------------------
+
+    # Build a document (the root node). With a block, the block is evaluated
+    # against this builder and its content is added to the root document.
+    # Returns the builder; use +to_document+ / +finish+ for the tree.
+    def document(&block)
+      push(@document) { instance_eval(&block) } if block
+      self
+    end
+
+    # An ATX heading. +level+ defaults to 1; the remaining arguments are the
+    # heading's inline content.
+    def heading(level = 1, *parts, **attributes)
+      node = Heading.new(level, children: inline_nodes(parts), attributes: attributes)
+      append(node)
+    end
+
+    def h1(*parts, **attributes) = heading(1, *parts, **attributes)
+    def h2(*parts, **attributes) = heading(2, *parts, **attributes)
+    def h3(*parts, **attributes) = heading(3, *parts, **attributes)
+    def h4(*parts, **attributes) = heading(4, *parts, **attributes)
+    def h5(*parts, **attributes) = heading(5, *parts, **attributes)
+    def h6(*parts, **attributes) = heading(6, *parts, **attributes)
+
+    # A paragraph. With a block, the block's inline nodes become its children.
+    def paragraph(*parts, &block)
+      node = Paragraph.new
+      build_inline(node, parts, &block)
+      append(node)
+    end
+    alias p paragraph
+
+    # A list. +ordered: true+ produces an ordered list; +start:+ sets its first
+    # number. Without a block, +items+ are wrapped into single-paragraph list
+    # items.
+    def list(*items, ordered: false, tight: true, start: nil, &block)
+      node = List.new(ordered: ordered, tight: tight, start: start)
+      if block
+        push(node) { instance_eval(&block) }
+      else
+        items.each { node.append(ListItem.new(children: [Paragraph.new])) }
+        refill_items(node, items)
+      end
+      append(node)
+    end
+
+    # An unordered list, as a shorthand for +list(ordered: false)+.
+    def ul(*items, &block) = list(*items, ordered: false, &block)
+    # An ordered list, as a shorthand for +list(ordered: true)+.
+    def ol(*items, start: nil, &block) = list(*items, ordered: true, start: start, &block)
+
+    # A list item. Without a block, +parts+ become a single paragraph.
+    def item(*parts, task: nil, checked: false, &block)
+      node = ListItem.new
+      unless task.nil?
+        node.attributes[:task] = true
+        node.attributes[:checked] = checked ? true : false
+      end
+      if block
+        push(node) { instance_eval(&block) }
+      elsif !parts.empty?
+        node.append(Paragraph.new(children: inline_nodes(parts)))
+      end
+      append(node)
+    end
+    alias li item
+
+    # A task list item (+checked+ marks it done).
+    def task(checked, *parts, &block)
+      item(*parts, task: true, checked: checked, &block)
+    end
+
+    # A blockquote. +parts+/+block+ are parsed as block content.
+    def blockquote(*parts, &block)
+      node = Blockquote.new
+      build_blocks(node, parts, &block)
+      append(node)
+    end
+    alias quote blockquote
+
+    # A fenced code block. +lang+ sets the info string.
+    def code_block(literal, lang: nil, fenced: true)
+      append(CodeBlock.new(literal.to_s, lang: lang, fenced: fenced))
+    end
+
+    # A horizontal rule.
+    def hrule(*, **)
+      append(Hrule.new)
+    end
+    alias hr hrule
+
+    # -- inline --------------------------------------------------------------
+
+    # Emphasis (*x*). With a block, nested explicit inline methods are used;
+    # otherwise string arguments are parsed as inline content. Appends to the
+    # current target and returns the node.
+    def em(*parts, &block)
+      node = Emphasis.new
+      build_inline(node, parts, &block)
+      append(node)
+      node
+    end
+    alias emphasis em
+
+    # Strong (**x**).
+    def strong(*parts, &block)
+      node = Strong.new
+      build_inline(node, parts, &block)
+      append(node)
+      node
+    end
+
+    # A code span (`x`). The argument is literal.
+    def code_span(value)
+      append(Code.new(value.to_s))
+    end
+
+    # A link. Without a block the label is the literal +*label+ parts; with a
+    # block, nested explicit inline methods build the label.
+    def link(destination, *label, title: nil, &block)
+      node = Link.new(destination, title: title)
+      build_inline(node, label, &block)
+      append(node)
+      node
+    end
+
+    # An image.
+    def image(destination, alt: nil, title: nil)
+      append(Image.new(destination, alt: alt, title: title))
+    end
+
+    # A soft line break.
+    def softbreak
+      append(Softbreak.new)
+    end
+
+    # A hard line break (two trailing spaces).
+    def hardbreak
+      append(Hardbreak.new)
+    end
+
+    # -- results -------------------------------------------------------------
+
+    # The document built so far.
+    def to_document
+      @document
+    end
+    alias finish to_document
+
+    # Serialize the document built so far to Markdown.
+    def to_markdown
+      @document.to_markdown
+    end
+
+    # A human-readable tree rendering of the document built so far.
+    def inspect
+      to_document.inspect
+    end
+
+    private
+
+    # Append +node+ to the current target and return the builder, so both
+    # +b.p "x"+ chains and top-level calls accumulate in the document.
+    def append(node)
+      @stack.last.append(node)
+      self
+    end
+
+    # Make +node+ the current target while the block runs, then restore.
+    def push(node)
+      @stack.push(node)
+      yield
+    ensure
+      @stack.pop
+    end
+
+    # Fill +node+ with inline content: a block plus direct parts, or the parts
+    # alone. With a block, parts are rejected (there is only one content site).
+    def build_inline(node, parts, &block)
+      if block
+        raise ArgumentError, "cannot combine inline arguments with a block" unless parts.empty?
+
+        push(node) { instance_eval(&block) }
+      else
+        node.append_parts(inline_nodes(parts))
+      end
+    end
+
+    # Fill +node+ with block content: a block plus direct parts (paragraphs),
+    # or the parts alone.
+    def build_blocks(node, parts, &block)
+      parts.each { |part| node.append(Paragraph.new(children: inline_nodes([part]))) }
+      push(node) { instance_eval(&block) } if block
+    end
+
+    # Build the item paragraphs for a block-less +list(*items)+ call.
+    def refill_items(list_node, items)
+      list_node.children.each_with_index do |item_node, idx|
+        item_node.children.first.append_parts(inline_nodes([items[idx]]))
+      end
+    end
+
+    # Convert arguments into inline nodes: strings are parsed as inline
+    # Markdown, existing nodes pass through (and are detached from any parent).
+    def inline_nodes(parts)
+      parts.flat_map do |part|
+        if part.is_a?(Node)
+          part.remove
+          part
+        else
+          InlineParser.parse(part.to_s)
+        end
+      end
+    end
+  end
+
+  def self.build(&block)
+    Builder.build(&block)
+  end
+
+  # Adds a batch-append helper to the block/inline nodes that carry inline
+  # content, so the builder can attach parsed parts in one call.
+  module InlineContainer
+    def append_parts(nodes)
+      nodes.each { |node| append(node) }
+      self
+    end
+  end
+
+  [Paragraph, Emphasis, Strong, Link].each { |klass| klass.include(InlineContainer) }
+end

data/lib/mdom/serializer.rb

@@ -6,17 +6,17 @@ module MDOM
   # 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)
+    def self.serialize(node, indent: 0, blockquote: false, marker: "-")
+      new.serialize(node, indent: indent, blockquote: blockquote, marker: marker)
     end
 
-    def serialize(node, indent: 0, blockquote: false)
+    def serialize(node, indent: 0, blockquote: false, marker: "-")
       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::LIST_ITEM then serialize_list_item(node, indent: indent, blockquote: blockquote, marker: marker)
       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)

data/lib/mdom/version.rb

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

data/lib/mdom.rb

@@ -6,6 +6,7 @@ require_relative "mdom/nodes"
 require_relative "mdom/parser"
 require_relative "mdom/inline_parser"
 require_relative "mdom/serializer"
+require_relative "mdom/builder"
 
 module MDOM
   # Serialize a node (or subtree) back to a Markdown string.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mdom
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - mdom
@@ -16,6 +16,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/mdom.rb
+- lib/mdom/builder.rb
 - lib/mdom/inline_parser.rb
 - lib/mdom/node.rb
 - lib/mdom/nodes.rb