markbridge 0.4.3 → 0.5.0

data/lib/markbridge/renderers/discourse/tags/url_tag.rb

@@ -4,12 +4,12 @@ module Markbridge
   module Renderers
     module Discourse
       module Tags
-        # Tag for rendering URLs
-        #
-        # Bare URLs (a single Text child equal to the href, or no link
-        # text at all) render as the plain href instead of a Markdown
-        # link — in Discourse a bare URL on its own line oneboxes, a
-        # `[text](url)` link does not.
+        # Links. A bare link (no text of its own, or a text that is the
+        # href, or a label with nothing visible in it) is a bare URL token:
+        # the serializer decides from the neighbors whether it can stay
+        # bare, which oneboxes in Discourse, or has to be written as
+        # `[url](url)`. Any other link is a link token pair around the
+        # children.
         class UrlTag < Tag
           # Schemes that are safe to link. Anything else that *looks*
           # like a scheme (javascript:, data:, vbscript:, …) is dropped;
@@ -17,41 +17,51 @@ module Markbridge
           # URLs) pass through — common in forum exports and harmless.
           ALLOWED_SCHEMES = /\A(?:https?|ftps?|mailto):/i
           SCHEME_LIKE = /\A[a-z][a-z0-9+.-]*:/i
-          private_constant :ALLOWED_SCHEMES, :SCHEME_LIKE
+          # The whitespace in front of the text and after it.
+          EDGES = /\A([[:space:]]*).*?([[:space:]]*)\z/m
+          private_constant :ALLOWED_SCHEMES, :SCHEME_LIKE, :EDGES
 
           def render(element, interface)
-            child_context = interface.with_parent(element)
-            text = interface.render_children(element, context: child_context)
             href = element.href
+            linkable = linkable?(href)
+            # Url#bare? judges the AST, so label escaping cannot confuse it.
+            return bare_tokens(element, href) if linkable && element.bare?
 
-            return text unless linkable?(href)
+            tokens = interface.render_tokens(element, context: interface.with_parent(element))
+            return tokens unless linkable
+            # A label that renders to nothing (an empty formatting child)
+            # or to whitespace only is no label either.
+            return [Inline::Tokens.bare_url(href)] unless Inline::Tokens.visible?(tokens)
 
-            if interface.html_mode?
-              %(<a href="#{HtmlEscaper.escape(href)}">#{text}</a>)
-            elsif element.bare? || blank?(text)
-              # Url#bare? judges the AST (so label escaping can't confuse
-              # it); the rendered-text check additionally catches labels
-              # that render to nothing (e.g. an empty formatting child)
-              # or to whitespace only, which wrap_inline would leave
-              # unlinked.
-              href
-            else
-              interface.wrap_inline(text, "[", "](#{markdown_destination(href)})")
-            end
+            tokens.unshift(Inline::Tokens.link_open(href)) << Inline::Tokens.link_close
           end
 
           private
 
-          # Unicode-aware, matching the guard in RenderingInterface#wrap_inline.
-          def blank?(text)
-            !text.match?(/[^[:space:]]/)
-          end
+          # The bare URL in place of the text. Whitespace at the edges of
+          # the text and the line breaks in front of it and after it stay
+          # outside the URL, so `[url] https://e.com [/url]` keeps its
+          # spaces. A bare link has only Text and LineBreak children (see
+          # Url#bare?); the line breaks are written as hard break tokens
+          # here, the serializer picks their form.
+          def bare_tokens(element, href)
+            bare = Inline::Tokens.bare_url(href)
+            return [bare] if element.children.empty?
+
+            element
+              .children
+              .each_with_object([]) do |child, tokens|
+                next tokens << Inline::Tokens.hard_break if child.instance_of?(AST::LineBreak)
+
+                label_text = child.text
+                # Most bare links have no whitespace to keep.
+                next tokens << bare if label_text == href
 
-          # CommonMark link destinations cannot contain whitespace unless
-          # wrapped in <> — relevant for relative targets like MediaWiki
-          # page names ("Main Page").
-          def markdown_destination(href)
-            href.match?(/\s/) ? "<#{href}>" : href
+                lead, trail = label_text.match(EDGES).captures
+                tokens << Inline::Tokens.text(lead) unless lead.empty?
+                tokens << bare
+                tokens << Inline::Tokens.text(trail) unless trail.empty?
+              end
           end
 
           def linkable?(href)

data/lib/markbridge/renderers/discourse.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../errors"
 require_relative "discourse/tag"
 require_relative "discourse/tag_library"
 require_relative "discourse/render_context"
@@ -8,6 +9,11 @@ require_relative "discourse/markdown_escaper"
 require_relative "discourse/identity_escaper"
 require_relative "discourse/html_escaper"
 require_relative "discourse/html_block"
+require_relative "discourse/paragraphs"
+require_relative "discourse/link_destination"
+require_relative "discourse/inline/tokens"
+require_relative "discourse/inline/joins"
+require_relative "discourse/inline/serializer"
 require_relative "discourse/postprocessor"
 
 # Builders

data/lib/markbridge/rspec.rb

@@ -38,9 +38,11 @@ RSpec.shared_examples "an html_mode safe tag" do
 
   it "renders html_mode output that is safe inside an HTML block" do
     output = tag.render(element, markbridge_html_mode_interface)
+    output = markbridge_renderer.serialize(output, markbridge_html_mode_interface.context)
 
     expect(Markbridge::Renderers::Discourse::HtmlBlock.safe?(output)).to be(true),
-    "Expected #{tag.class} to render raw HTML or a \\n\\n-wrapped " \
-      "Markdown island in html_mode, got: #{output.inspect}"
+    "Expected #{tag.class} to render raw HTML without a blank line, or a " \
+      "Markdown island in a <div> (interface.markdown_island) in html_mode, " \
+      "got: #{output.inspect}"
   end
 end

data/lib/markbridge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Markbridge
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

data/lib/markbridge.rb

@@ -9,6 +9,26 @@ require_relative "markbridge/normalizer"
 require_relative "markbridge/renderers/discourse"
 
 module Markbridge
+  # The tags of the plugins bundled with Discourse, by feature. The
+  # discourse-bbcode plugin (:bbcode) has its own registration, its tags
+  # take the mappings.
+  FEATURE_TAGS = {
+    details: {
+      AST::Details => Renderers::Discourse::Tags::DetailsTag,
+    },
+    spoiler: {
+      AST::Spoiler => Renderers::Discourse::Tags::SpoilerTag,
+    },
+    poll: {
+      AST::Poll => Renderers::Discourse::Tags::PollTag,
+    },
+    post_event: {
+      AST::Event => Renderers::Discourse::Tags::EventTag,
+    },
+  }.freeze
+  FEATURES = (FEATURE_TAGS.keys + [:bbcode]).freeze
+  private_constant :FEATURE_TAGS, :FEATURES
+
   class << self
     # Parse BBCode to AST.
     #
@@ -297,7 +317,32 @@ module Markbridge
     #   {Renderers::Discourse::Postprocessor} when no explicit
     #   +postprocessor:+ is given. Strips NBSP and zero-width format
     #   characters from the end of each line.
+    # @param features [Hash{Symbol => Boolean}, nil] the plugins of the
+    #   target site. +:details+, +:spoiler+, +:poll+ and +:post_event+ are
+    #   bundled with Discourse and on by default. With one of them off,
+    #   the tag writes a plain form instead of the plugin's BBCode: the
+    #   title in bold and the content for a details block, the content
+    #   for a spoiler, the options as a list for a poll, a paragraph with
+    #   the name and the dates for an event. +:bbcode+ is the
+    #   discourse-bbcode plugin, which needs an install, and starts
+    #   undecided: a color or size in a post raises
+    #   {UndecidedFeatureError} until it is +false+ (the text only) or
+    #   +true+ (the BBCode, with +sizes:+). Mappings in +tags:+ still win.
+    # @param sizes [Hash, #call, nil] with +bbcode: true+, the mapping
+    #   from the size values of the source forum to the percent value
+    #   the plugin reads: a whole number from 1 to 999, or nil to drop a
+    #   size. A Hash is read with +fetch+, so an unknown value raises
+    #   KeyError. Required with +bbcode: true+, because every forum has
+    #   its own scale.
+    # @param colors [Hash, #call, nil] with +bbcode: true+, a mapping from
+    #   the color values of the source forum to +#rgb+, +#rrggbb+ or a
+    #   name, or nil to drop a color. Without it the values are written
+    #   as they are, and a value the plugin does not accept raises
+    #   ArgumentError.
     # @return [Renderers::Discourse::Renderer]
+    # @raise [ArgumentError] for a feature that does not exist, for
+    #   +bbcode: true+ without +sizes:+, and for a mapping without
+    #   +bbcode: true+
     def discourse_renderer(
       tags: nil,
       tag_library: nil,
@@ -307,7 +352,10 @@ module Markbridge
       escape_hard_line_breaks: false,
       allow: nil,
       postprocessor: nil,
-      strip_trailing_invisibles: false
+      strip_trailing_invisibles: false,
+      features: nil,
+      sizes: nil,
+      colors: nil
     )
       # Dup the caller's library before mutating so successive
       # +discourse_renderer+ calls against the same +tag_library:+ don't
@@ -315,6 +363,7 @@ module Markbridge
       # a fresh instance, so the dup is only needed in the explicit
       # +tag_library:+ branch.
       library = tag_library ? tag_library.dup : Renderers::Discourse::TagLibrary.default
+      register_features(library, features || {}, sizes:, colors:)
       library.merge!(tags) if tags
       Array(unregister).each { |klass| library.unregister(klass) }
 
@@ -326,6 +375,46 @@ module Markbridge
 
     private
 
+    # Registers the tags of the features named, so the other tags of the
+    # library stay as they are.
+    def register_features(library, features, sizes:, colors:)
+      features.each do |feature, enabled|
+        unless FEATURES.include?(feature)
+          raise ArgumentError,
+                "unknown feature #{feature.inspect}, the features are #{FEATURES.join(", ")}"
+        end
+        unless [true, false].include?(enabled)
+          raise ArgumentError, "feature #{feature} must be true or false, got #{enabled.inspect}"
+        end
+        next if feature == :bbcode
+
+        FEATURE_TAGS
+          .fetch(feature)
+          .each { |klass, tag_class| library.register(klass, tag_class.new(bbcode: enabled)) }
+      end
+
+      register_bbcode_feature(library, features[:bbcode], sizes:, colors:)
+    end
+
+    def register_bbcode_feature(library, bbcode, sizes:, colors:)
+      if bbcode && sizes.nil?
+        raise ArgumentError,
+              "features: { bbcode: true } needs sizes:, the mapping from the size values of " \
+                "the source forum to percent"
+      end
+      { sizes:, colors: }.each do |name, mapping|
+        next if mapping.nil?
+        unless mapping.respond_to?(:call) || mapping.respond_to?(:fetch)
+          raise ArgumentError, "#{name}: must be a Hash or respond to call"
+        end
+        raise ArgumentError, "#{name}: needs features: { bbcode: true }" unless bbcode
+      end
+      return if bbcode.nil?
+
+      library.register(AST::Color, Renderers::Discourse::Tags::ColorTag.new(bbcode:, colors:))
+      library.register(AST::Size, Renderers::Discourse::Tags::SizeTag.new(bbcode:, sizes:))
+    end
+
     def bbcode_diagnostics(parser)
       {
         auto_closed_tags_count: parser.auto_closed_tags_count,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: markbridge
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Discourse Team
@@ -55,6 +55,7 @@ files:
 - lib/markbridge/ast/url.rb
 - lib/markbridge/bbcode.rb
 - lib/markbridge/conversion.rb
+- lib/markbridge/errors.rb
 - lib/markbridge/gem_loader.rb
 - lib/markbridge/html.rb
 - lib/markbridge/mediawiki.rb
@@ -141,7 +142,12 @@ files:
 - lib/markbridge/renderers/discourse/html_block.rb
 - lib/markbridge/renderers/discourse/html_escaper.rb
 - lib/markbridge/renderers/discourse/identity_escaper.rb
+- lib/markbridge/renderers/discourse/inline/joins.rb
+- lib/markbridge/renderers/discourse/inline/serializer.rb
+- lib/markbridge/renderers/discourse/inline/tokens.rb
+- lib/markbridge/renderers/discourse/link_destination.rb
 - lib/markbridge/renderers/discourse/markdown_escaper.rb
+- lib/markbridge/renderers/discourse/paragraphs.rb
 - lib/markbridge/renderers/discourse/postprocessor.rb
 - lib/markbridge/renderers/discourse/render_context.rb
 - lib/markbridge/renderers/discourse/renderer.rb