markbridge 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 356955e6ba849a6acb08902465ed0d45c710020183d75eca66d3904b93995f3c
-  data.tar.gz: 4c1bf20ea2c024478cdfa6bbea5ceade531de96085a2cc911499a0c8d31d78ad
+  metadata.gz: e9a481ff76e961a6f9c93e9cea998a6cdbe02ee46000c3acfba4e00023c12fd4
+  data.tar.gz: ffcc31afdae7383a83a2a51a26bfacfcd1c482dd5e779144cb6263b8547ed63c
 SHA512:
-  metadata.gz: 0fbb3282126a07f194e4c833bc2694b91a64b877144e6ea0317ff2f62785a28dd144a969cc5d4a3fc1eda3306fa1416496cc478b6fe51ffe4862dba9f468a288
-  data.tar.gz: 0624ec779e99b904de91eb2d519b65ee7c123d2b8e8d51c659b4ce5005afc521bd2290e07517a7f9aaf5ea9e19998354b31e7a6818e27fe55dceb02da22cad41
+  metadata.gz: 46ba479a92c780d448385002567fea76f51478d18af74b6e7675bf916d01e5bbf61d56fd4f6b9f8ce1fd702662a9d41f15f1d43d86ec605e62604f2171b17795
+  data.tar.gz: 1eb764723017c5ca0afefb538945b37343dddf9aefb891947a7c3357451078bea5b045588c66275e517a95343ebef0a9bb9bfaef17639ded233333a819af0c9f

data/lib/markbridge/ast/image.rb

@@ -9,6 +9,9 @@ module Markbridge
     #
     # @example Image with dimensions
     #   image = AST::Image.new(src: "https://example.com/img.png", width: 100, height: 100)
+    #
+    # @example Image with alternative text
+    #   image = AST::Image.new(src: "https://example.com/img.png", alt: "a cat")
     class Image < Element
       # @return [String, nil] the image source URL
       attr_reader :src
@@ -19,16 +22,21 @@ module Markbridge
       # @return [Integer, nil] the image height
       attr_reader :height
 
+      # @return [String, nil] the alternative text
+      attr_reader :alt
+
       # Create a new Image element.
       #
       # @param src [String, nil] the image source URL
       # @param width [Integer, nil] the image width
       # @param height [Integer, nil] the image height
-      def initialize(src: nil, width: nil, height: nil)
+      # @param alt [String, nil] the alternative text
+      def initialize(src: nil, width: nil, height: nil, alt: nil)
         super()
         @src = src
         @width = width
         @height = height
+        @alt = alt
       end
     end
   end

data/lib/markbridge/ast/url.rb

@@ -12,6 +12,10 @@ module Markbridge
     #   url = AST::Url.new(href: "https://example.com")
     #   url << AST::Text.new("https://example.com")
     class Url < Element
+      # Whitespace at the start or at the end of the text.
+      EDGE_SPACE = /\A[[:space:]]+|[[:space:]]+\z/
+      private_constant :EDGE_SPACE
+
       # @return [String, nil] the URL/href for this link
       attr_reader :href
 
@@ -24,18 +28,39 @@ module Markbridge
       end
 
       # Whether this link is "bare" — it has no link text of its own:
-      # either no children, or a single Text child whose content is
-      # exactly the href (how parsers model a URL that stands for
-      # itself). Consumers that record or rewrite links need this
+      # either no children, or a single Text child whose content is the
+      # href (how parsers model a URL that stands for itself).
+      # Whitespace at the edges of the text and line breaks in front of
+      # it or after it don't count: forum posts often have
+      # `[url] https://example.com [/url]` or a line break right after
+      # `[url]`. Consumers that record or rewrite links need this
       # judgment too (a bare URL must stay bare to keep autolinking
       # and oneboxing working), so it lives on the node rather than
       # in the renderer.
       #
       # @return [Boolean]
+      # @example
+      #   url = AST::Url.new(href: "https://example.com")
+      #   url << AST::LineBreak.new << AST::Text.new(" https://example.com ")
+      #   url.bare? # => true
       def bare?
         return true if children.empty?
 
-        children.size == 1 && children.first.instance_of?(Text) && children.first.text == href
+        bare_text = nil
+        children.each do |child|
+          if child.instance_of?(Text)
+            return false if bare_text
+
+            bare_text = child.text
+          elsif !child.instance_of?(LineBreak)
+            return false
+          end
+        end
+        return false if bare_text.nil?
+        # Most bare links have no whitespace to take off.
+        return true if bare_text == href
+
+        bare_text.gsub(EDGE_SPACE, "") == href
       end
     end
   end

data/lib/markbridge/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Markbridge
+  # Raised when a post holds something whose output depends on a plugin
+  # of the target site and the renderer was not told whether the site
+  # has it. See the +features:+ option of {Markbridge.discourse_renderer}.
+  class UndecidedFeatureError < StandardError
+  end
+end

data/lib/markbridge/parsers/bbcode/handlers/image_handler.rb

@@ -10,6 +10,7 @@ module Markbridge
         # - [img=100x100]url[/img]
         # - [img width=100]url[/img]
         # - [img width=100 height=50]url[/img]
+        # - [img alt="a cat"]url[/img]
         class ImageHandler < RawHandler
           def initialize
             super(AST::Image)
@@ -19,7 +20,7 @@ module Markbridge
 
           def create_element(token:, content:)
             width, height = extract_dimensions(token)
-            AST::Image.new(src: content, width:, height:)
+            AST::Image.new(src: content, width:, height:, alt: token.attrs[:alt])
           end
 
           OPTION_DIMENSIONS_PATTERN = /\A(?<width>\d+)(?:x(?<height>\d+))?\z/i

data/lib/markbridge/parsers/bbcode/handlers/url_handler.rb

@@ -5,6 +5,9 @@ module Markbridge
     module BBCode
       module Handlers
         # Handler for URL tags
+        # Supports:
+        # - [url=https://example.com]text[/url]
+        # - [url]https://example.com[/url], where the text is the href
         class UrlHandler < BaseHandler
           def initialize
             @element_class = AST::Url
@@ -12,11 +15,32 @@ module Markbridge
 
           def on_open(token:, context:, registry:, tokens: nil)
             href = token.attrs[:href] || token.attrs[:url] || token.attrs[:option]
-            element = AST::Url.new(href:)
-            context.push(element, token:)
+            content = href ? nil : content_href(token:, tokens:)
+            return context.push(AST::Url.new(href:), token:) unless content
+
+            # The text and the closing tag that content_href looked at.
+            tokens.next
+            tokens.next
+            context.add_child(AST::Url.new(href: content) << AST::Text.new(content))
           end
 
           attr_reader :element_class
+
+          private
+
+          # [url]https://example.com[/url] has its href in the text. Only
+          # plain text followed by the closing tag counts: with tags inside
+          # the text is no URL, and the element keeps a nil href.
+          #
+          # @return [String, nil]
+          def content_href(token:, tokens:)
+            text, close = tokens&.peek_ahead(2)
+            return unless text.instance_of?(TextToken) && close.instance_of?(TagEndToken)
+            return unless close.tag == token.tag
+
+            href = text.text.strip
+            href unless href.empty?
+          end
         end
       end
     end

data/lib/markbridge/parsers/html/handlers/image_handler.rb

@@ -14,8 +14,11 @@ module Markbridge
             src = element["src"]
             width = sanitize_dimension(element["width"])
             height = sanitize_dimension(element["height"])
+            # An empty alt attribute means "no text", the same as a missing one.
+            alt = element["alt"]
+            alt = nil if alt&.empty?
 
-            ast_element = AST::Image.new(src:, width:, height:)
+            ast_element = AST::Image.new(src:, width:, height:, alt:)
             parent << ast_element
 
             # Return nil to signal: don't process children (void element)

data/lib/markbridge/parsers/text_formatter/handlers/attachment_handler.rb

@@ -21,8 +21,9 @@ module Markbridge
               )
             parent << node
 
-            # Return node to signal: process children into this node
-            node
+            # The content is only fallback text (the filename), so there are
+            # no children to process.
+            nil
           end
 
           attr_reader :element_class

data/lib/markbridge/parsers/text_formatter/handlers/image_handler.rb

@@ -17,11 +17,13 @@ module Markbridge
                 src: attrs[:src],
                 width: attrs[:width]&.to_i,
                 height: attrs[:height]&.to_i,
+                alt: attrs[:alt],
               )
             parent << node
 
-            # Return node to signal: process children into this node
-            node
+            # The content is only fallback text (the URL), so there are
+            # no children to process.
+            nil
           end
 
           attr_reader :element_class

data/lib/markbridge/parsers/text_formatter/parser.rb

@@ -9,6 +9,12 @@ module Markbridge
       # - Plain text: <t>text content</t>
       # - Rich text: <r><B>bold</B> <URL url="...">link</URL></r>
       # - Markup preservation: <s> and <e> elements (ignored during parsing)
+      # - Ignored text: <i> (lowercase) holds text s9e did not use, like the
+      #   newline after [list] or a stray [/b]. It is skipped too; <I> is italic.
+      # - Line breaks: <br/> followed by a newline in the next text node. The
+      #   newline is only source formatting, like any whitespace at the start
+      #   of a line, because phpBB renders the XML as HTML. Inside <CODE> the
+      #   text is kept as it is.
       #
       # This format is used by phpBB 3.2+ and other forum software.
       #
@@ -36,6 +42,12 @@ module Markbridge
               handlers || HandlerRegistry.shared_default
             end
           @unknown_tags = Hash.new(0)
+          # Whether an AST class is one of the BLOCK_NODES, computed once
+          # per class, so an inline element doesn't check all of them.
+          @block_classes =
+            Hash.new do |block_class_cache, klass|
+              block_class_cache[klass] = BLOCK_NODES.any? { klass <= _1 }
+            end
         end
 
         # Parse s9e/TextFormatter XML into an AST.
@@ -49,11 +61,13 @@ module Markbridge
         # @return [AST::Document]
         def parse(input)
           @unknown_tags.clear
+          @line_start = true
 
           if input.is_a?(Nokogiri::XML::Node)
             root = input.is_a?(Nokogiri::XML::Document) ? input.root : input
             document = AST::Document.new
             process_node(root, document) if root
+            flush_line_break
             return document
           end
 
@@ -70,17 +84,38 @@ module Markbridge
 
           document = AST::Document.new
           process_node(root, document)
+          flush_line_break
           document
         rescue Nokogiri::XML::SyntaxError
           AST::Document.new << AST::Text.new(input)
         end
 
-        # <s>/<e> hold the original BBCode markup for unparsing; <t>/<r>
-        # are the plain-text/rich-text roots. Frozen constants — the
-        # membership checks run once per element node.
-        MARKUP_PRESERVATION_TAGS = %w[s e].freeze
+        # <s>/<e> hold the original BBCode markup for unparsing, <i> holds
+        # text that s9e ignored; <t>/<r> are the plain-text/rich-text roots.
+        # Frozen constants — the membership checks run once per element
+        # node. The check is case-sensitive: <I> is italic.
+        MARKUP_PRESERVATION_TAGS = %w[s e i].freeze
         ROOT_TAGS = %w[t r].freeze
-        private_constant :MARKUP_PRESERVATION_TAGS, :ROOT_TAGS
+
+        # AST nodes that phpBB shows as blocks. A new line starts before and
+        # after them, so whitespace at the start of their content and of the
+        # text after them is not visible.
+        BLOCK_NODES = [
+          AST::Align,
+          AST::Code,
+          AST::Details,
+          AST::Heading,
+          AST::HorizontalRule,
+          AST::List,
+          AST::ListItem,
+          AST::Paragraph,
+          AST::Quote,
+          AST::Spoiler,
+          AST::Table,
+          AST::TableCell,
+          AST::TableRow,
+        ].freeze
+        private_constant :MARKUP_PRESERVATION_TAGS, :ROOT_TAGS, :BLOCK_NODES
 
         # Process children of an XML element (public for handler access)
         # @param element [Nokogiri::XML::Element]
@@ -114,33 +149,91 @@ module Markbridge
           # Handle root nodes
           return process_children(element, ast_parent) if ROOT_TAGS.include?(tag_name)
 
-          # Handle line breaks
-          if tag_name == "br"
-            ast_parent << AST::LineBreak.new
-            return
-          end
+          return process_line_break(ast_parent) if tag_name == "br"
 
           # Process element with registered handler
           # Handler returns element if children should be processed, nil otherwise
+          flush_line_break
           result_element = @handlers.process_element(element, ast_parent, self)
 
           if result_element
             # Handler succeeded and returned element - process children into it
-            process_children(element, result_element)
-          elsif !@handlers.has_handler?(tag_name)
+            process_handled_children(element, result_element)
+          elsif @handlers.has_handler?(tag_name)
+            # The handler returned nil intentionally: a leaf like an image
+            # or an attachment, whose content is only fallback text. It is
+            # visible, so the text after it is no longer at the line start.
+            @line_start = false
+          else
             # No handler found - track as unknown and process children directly
             @unknown_tags[tag_name] += 1
             process_children(element, ast_parent)
           end
-          # else: handler returned nil intentionally (no children to process)
+        end
+
+        # Two line breaks in a row are an empty line in phpBB. In Markdown
+        # that is a paragraph break, so a line break waits in
+        # +@pending_break+ until something visible follows it. When the
+        # next line break comes first, the two become a blank line. A
+        # third one comes after the blank line and is not visible.
+        #
+        # @param ast_parent [AST::Element]
+        def process_line_break(ast_parent)
+          if @pending_break.equal?(ast_parent)
+            @pending_break = nil
+            ast_parent << AST::Text.new("\n\n")
+          else
+            flush_line_break
+            @pending_break = ast_parent
+          end
+          @line_start = true
+        end
+
+        # Adds the line break that waits, if there is one, before anything
+        # visible is added after it.
+        def flush_line_break
+          @pending_break&.<<(AST::LineBreak.new)
+          @pending_break = nil
+        end
+
+        # @param element [Nokogiri::XML::Element]
+        # @param ast_element [AST::Element]
+        def process_handled_children(element, ast_element)
+          if @block_classes[ast_element.class]
+            @line_start = true
+            process_children(element, ast_element)
+            @line_start = true
+          else
+            process_children(element, ast_element)
+          end
         end
 
         # Process text node
+        #
+        # Outside of code, whitespace at the start of a line is not visible
+        # in phpBB, but in Markdown a newline after a line break would end
+        # the paragraph and four spaces would start a code block, so it is
+        # removed. Whitespace-only text between two inline elements (the
+        # space in "<B>a</B> <I>b</I>") is kept; with a newline in it, it
+        # is only formatting between blocks.
+        #
         # @param text_node [Nokogiri::XML::Text]
         # @param ast_parent [AST::Element]
         def process_text(text_node, ast_parent)
           text = text_node.content
-          ast_parent << AST::Text.new(text) if text.match?(/\S/)
+
+          if ast_parent.is_a?(AST::Code)
+            ast_parent << AST::Text.new(text) if text.match?(/\S/)
+          elsif @line_start
+            text = text.lstrip
+            return if text.empty?
+
+            @line_start = false
+            flush_line_break
+            ast_parent << AST::Text.new(text)
+          elsif text.match?(/\S/) || !text.include?("\n")
+            ast_parent << AST::Text.new(text)
+          end
         end
       end
     end

data/lib/markbridge/renderers/discourse/html_block.rb

@@ -11,15 +11,21 @@ module Markbridge
       # renders into such a block therefore picks one of two forms:
       #
       # 1. raw HTML — an HTML equivalent of the tag's Markdown, spliced
-      #    into the block as it is;
+      #    into the block as it is, with no blank line in it;
       # 2. a Markdown island — the tag's normal Markdown surrounded by
-      #    blank lines, which end the block and start it again:
+      #    blank lines, which end the block, and a line that opens it
+      #    again after them:
       #
       #        <div align="center">
       #
       #        [a link](https://example.com)
       #
       #        </div>
+      #
+      # Inside an HTML block the island is always in a `<div>`
+      # (.enclosed_island, which a tag reaches through
+      # RenderingInterface#markdown_island). After a bare island the rest
+      # of the cell would be Markdown too.
       module HtmlBlock
         # Tag names that start a type 6 HTML block when a line begins
         # with `<name` or `</name` followed by a space, a tab, `>`, `/>`
@@ -94,6 +100,10 @@ module Markbridge
         # are item content that the list builder has not indented yet.
         OPENER = %r{\A[ \t]*</?(?:#{Regexp.union(BLOCK_TAGS).source})(?:[ \t>]|/>|\z)}i
 
+        # The newline in front of a line that holds nothing but spaces and
+        # tabs: with the line it makes a blank line.
+        BLANK_LINE_NEWLINE = /\n(?=[ \t]*\n)/
+
         # Markdown sigils that would surface as literal text inside an
         # HTML block: emphasis (`*`, `_`, `~`) and link middles (`](`).
         MARKDOWN_SIGILS = /[*_~]|\]\(/
@@ -102,7 +112,7 @@ module Markbridge
         # content line keeps its own indentation, e.g. a nested `  - a`.
         BLANK_EDGES = /\A(?:[ \t]*\n)+|(?:\n[ \t]*)+\z/
 
-        private_constant :BLOCK_TAGS, :OPENER, :MARKDOWN_SIGILS, :BLANK_EDGES
+        private_constant :BLOCK_TAGS, :OPENER, :BLANK_LINE_NEWLINE, :MARKDOWN_SIGILS, :BLANK_EDGES
 
         # Whether +line+ starts an HTML block. A closing tag such as
         # `</div>` starts one too. The block runs until the next blank
@@ -124,17 +134,50 @@ module Markbridge
           "\n\n#{markdown.gsub(BLANK_EDGES, "")}\n\n"
         end
 
-        # Whether a fragment can be spliced into an HTML block: raw HTML
-        # or plain text without Markdown sigils, or an island.
+        # An island for the inside of an HTML block, in a `<div>`. After
+        # a bare island what follows on the same lines is Markdown until
+        # a line opens an HTML block again, so text after it in a table
+        # cell would get Markdown meaning; the `</div>` line opens the
+        # block again. A `div` is a block in the HTML as well, so the
+        # island shows as a paragraph of its own, like a bare island
+        # does.
+        # @param markdown [String]
+        # @return [String]
+        # @example
+        #   HtmlBlock.enclosed_island("![a](b)") # => "<div>\n\n![a](b)\n\n</div>"
+        def self.enclosed_island(markdown)
+          "<div>#{island(markdown)}</div>"
+        end
+
+        # Text for the inside of an HTML block, with no blank line in it:
+        # a blank line ends the block, and what follows is Markdown
+        # again. The newline that would start a blank line is written as
+        # the entity, which the HTML parser reads back as a newline.
+        # @param text [String] text or HTML, already escaped
+        # @return [String]
+        # @example
+        #   HtmlBlock.without_blank_lines("a\n\nb") # => "a&#10;\nb"
+        def self.without_blank_lines(text)
+          return text unless text.include?("\n")
+
+          text.gsub(BLANK_LINE_NEWLINE, "&#10;")
+        end
+
+        # Whether a fragment can be spliced into an HTML block: an island
+        # in a `<div>`, or raw HTML or plain text without Markdown sigils
+        # and without a blank line. A blank line anywhere else ends the
+        # block, and what follows it is Markdown until a line opens a
+        # block again; a bare island, `\n\n…\n\n`, is not accepted for
+        # that reason.
         #
         # Used by the html_mode contract check that ships in
         # +markbridge/rspec+ and by this repo's own contract spec.
         # @param output [String] a tag's html_mode render result
         # @return [Boolean]
         def self.safe?(output)
-          return true if output.start_with?("\n\n") && output.end_with?("\n\n")
+          return true if output.start_with?("<div>\n\n") && output.end_with?("\n\n</div>")
 
-          !output.match?(MARKDOWN_SIGILS)
+          !output.match?(MARKDOWN_SIGILS) && !output.match?(BLANK_LINE_NEWLINE)
         end
       end
     end