rdoc 6.17.0 → 8.1.0

data/lib/rdoc/markup/formatter.rb

@@ -10,263 +10,280 @@
 # RDoc::Markup::FormatterTestCase.  If you're writing a text-output formatter
 # use RDoc::Markup::TextFormatterTestCase which provides extra test cases.
 
-class RDoc::Markup::Formatter
+require 'rdoc/markup/inline_parser'
 
-  ##
-  # Tag for inline markup containing a +bit+ for the bitmask and the +on+ and
-  # +off+ triggers.
+module RDoc
+  class Markup
+    class Formatter
 
-  InlineTag = Struct.new(:bit, :on, :off)
+      ##
+      # Converts a target url to one that is relative to a given path
 
-  ##
-  # Converts a target url to one that is relative to a given path
+      def self.gen_relative_url(path, target)
+        from        = File.dirname path
+        to, to_file = File.split target
 
-  def self.gen_relative_url(path, target)
-    from        = File.dirname path
-    to, to_file = File.split target
+        from = from.split "/"
+        to   = to.split "/"
 
-    from = from.split "/"
-    to   = to.split "/"
+        from.delete '.'
+        to.delete '.'
 
-    from.delete '.'
-    to.delete '.'
+        while from.size > 0 and to.size > 0 and from[0] == to[0] do
+          from.shift
+          to.shift
+        end
 
-    while from.size > 0 and to.size > 0 and from[0] == to[0] do
-      from.shift
-      to.shift
-    end
-
-    from.fill ".."
-    from.concat to
-    from << to_file
-    File.join(*from)
-  end
-
-  ##
-  # Creates a new Formatter
+        from.fill ".."
+        from.concat to
+        from << to_file
+        File.join(*from)
+      end
 
-  def initialize(options, markup = nil)
-    @options = options
+      ##
+      # Creates a new Formatter
 
-    @markup = markup || RDoc::Markup.new
-    @am     = @markup.attribute_manager
-    @am.add_regexp_handling(/<br>/, :HARD_BREAK)
+      def initialize
+        @markup = Markup.new
 
-    @attributes = @am.attributes
+        @from_path = '.'
+      end
 
-    @attr_tags = []
+      ##
+      # Adds +document+ to the output
+
+      def accept_document(document)
+        document.parts.each do |item|
+          case item
+          when Markup::Document # HACK
+            accept_document item
+          else
+            item.accept self
+          end
+        end
+      end
 
-    @in_tt = 0
-    @tt_bit = @attributes.bitmap_for :TT
+      ##
+      # Adds a regexp handling for links of the form rdoc-...:
 
-    @hard_break = ''
-    @from_path = '.'
-  end
+      def add_regexp_handling_RDOCLINK
+        @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
+      end
 
-  ##
-  # Adds +document+ to the output
+      ##
+      # Allows +tag+ to be decorated with additional information.
 
-  def accept_document(document)
-    document.parts.each do |item|
-      case item
-      when RDoc::Markup::Document then # HACK
-        accept_document item
-      else
-        item.accept self
+      def annotate(tag)
+        tag
       end
-    end
-  end
 
-  ##
-  # Adds a regexp handling for links of the form rdoc-...:
+      ##
+      # Marks up +content+
 
-  def add_regexp_handling_RDOCLINK
-    @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
-  end
+      def convert(content)
+        @markup.convert content, self
+      end
 
-  ##
-  # Adds a regexp handling for links of the form {<text>}[<url>] and
-  # <word>[<url>]
+      # Applies regexp handling to +text+ and returns an array of [text, converted?] pairs.
+
+      def apply_regexp_handling(text)
+        matched = []
+        @markup.regexp_handlings.each_with_index do |(pattern, name), priority|
+          text.scan(pattern) do
+            m = Regexp.last_match
+            idx = m[1] ? 1 : 0
+            matched << [m.begin(idx), m.end(idx), m[idx], name, priority]
+          end
+        end
+        # If the start positions are the same, prefer the earlier-registered one
+        # (lower numeric priority from each_with_index).
+        matched.sort_by! {|beg_pos, _, _, _, priority| [beg_pos, priority] }
+
+        pos = 0
+        output = []
+        matched.each do |beg_pos, end_pos, s, name|
+          next if beg_pos < pos
+
+          output << [text[pos...beg_pos], false] if beg_pos != pos
+          handled = public_send(:"handle_regexp_#{name}", s)
+          output << [handled, true]
+          pos = end_pos
+        end
+
+        output << [text[pos..], false] if pos < text.size
+        output
+      end
 
-  def add_regexp_handling_TIDYLINK
-    @markup.add_regexp_handling(/(?:
-                                  \{[^{}]*\} | # multi-word label
-                                  \b[^\s{}]+? # single-word label
-                                 )
+      # Called when processing plain text while traversing inline nodes from handle_inline.
+      # +text+ may need proper escaping.
 
-                                 \[\S+?\]     # link target
-                                /x, :TIDYLINK)
-  end
+      def handle_PLAIN_TEXT(text)
+      end
 
-  ##
-  # Add a new set of tags for an attribute. We allow separate start and end
-  # tags for flexibility
+      # Called when processing regexp-handling-processed text while traversing inline nodes from handle_inline.
+      # +text+ may contain markup tags.
 
-  def add_tag(name, start, stop)
-    attr = @attributes.bitmap_for name
-    @attr_tags << InlineTag.new(attr, start, stop)
-  end
+      def handle_REGEXP_HANDLING_TEXT(text)
+      end
 
-  ##
-  # Allows +tag+ to be decorated with additional information.
+      # Called when processing text node while traversing inline nodes from handle_inline.
+      # Apply regexp handling and dispatch to the appropriate handler: handle_REGEXP_HANDLING_TEXT or handle_PLAIN_TEXT.
+
+      def handle_TEXT(text)
+        apply_regexp_handling(text).each do |part, converted|
+          if converted
+            handle_REGEXP_HANDLING_TEXT(part)
+          else
+            handle_PLAIN_TEXT(part)
+          end
+        end
+      end
 
-  def annotate(tag)
-    tag
-  end
+      # Called when processing a hard break while traversing inline nodes from handle_inline.
 
-  ##
-  # Marks up +content+
+      def handle_HARD_BREAK
+      end
 
-  def convert(content)
-    @markup.convert content, self
-  end
+      # Called when processing bold nodes while traversing inline nodes from handle_inline.
+      # Traverse the children nodes and dispatch to the appropriate handlers.
 
-  ##
-  # Converts flow items +flow+
-
-  def convert_flow(flow)
-    res = []
-
-    flow.each do |item|
-      case item
-      when String then
-        res << convert_string(item)
-      when RDoc::Markup::AttrChanger then
-        off_tags res, item
-        on_tags res, item
-      when RDoc::Markup::RegexpHandling then
-        res << convert_regexp_handling(item)
-      else
-        raise "Unknown flow element: #{item.inspect}"
+      def handle_BOLD(nodes)
+        traverse_inline_nodes(nodes)
       end
-    end
 
-    res.join
-  end
+      # Called when processing emphasis nodes while traversing inline nodes from handle_inline.
+      # Traverse the children nodes and dispatch to the appropriate handlers.
 
-  ##
-  # Converts added regexp handlings. See RDoc::Markup#add_regexp_handling
+      def handle_EM(nodes)
+        traverse_inline_nodes(nodes)
+      end
 
-  def convert_regexp_handling(target)
-    return target.text if in_tt?
+      # Called when processing bold word nodes while traversing inline nodes from handle_inline.
+      # +word+ may need proper escaping.
 
-    handled = false
+      def handle_BOLD_WORD(word)
+        handle_PLAIN_TEXT(word)
+      end
 
-    @attributes.each_name_of target.type do |name|
-      method_name = "handle_regexp_#{name}"
+      # Called when processing emphasis word nodes while traversing inline nodes from handle_inline.
+      # +word+ may need proper escaping.
 
-      if respond_to? method_name then
-        target.text = public_send method_name, target
-        handled = true
+      def handle_EM_WORD(word)
+        handle_PLAIN_TEXT(word)
       end
-    end
 
-    unless handled then
-      target_name = @attributes.as_string target.type
+      # Called when processing tt nodes while traversing inline nodes from handle_inline.
+      # +code+ may need proper escaping.
 
-      raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
-    end
+      def handle_TT(code)
+        handle_PLAIN_TEXT(code)
+      end
 
-    target.text
-  end
+      # Called when processing strike nodes while traversing inline nodes from handle_inline.
+      # Traverse the children nodes and dispatch to the appropriate handlers.
 
-  ##
-  # Converts a string to be fancier if desired
+      def handle_STRIKE(nodes)
+        traverse_inline_nodes(nodes)
+      end
 
-  def convert_string(string)
-    string
-  end
+      # Called when processing tidylink nodes while traversing inline nodes from handle_inline.
+      # +label_part+ is an array of strings or nodes representing the link label.
+      # +url+ is the link URL.
+      # Traverse the label_part nodes and dispatch to the appropriate handlers.
 
-  ##
-  # Use ignore in your subclass to ignore the content of a node.
-  #
-  #   ##
-  #   # We don't support raw nodes in ToNoRaw
-  #
-  #   alias accept_raw ignore
+      def handle_TIDYLINK(label_part, url)
+        traverse_inline_nodes(label_part)
+      end
 
-  def ignore *node
-  end
+      # Parses inline +text+, traverse the resulting nodes, and calls the appropriate handler methods.
 
-  ##
-  # Are we currently inside tt tags?
+      def handle_inline(text)
+        nodes = Markup::InlineParser.new(text).parse
+        traverse_inline_nodes(nodes)
+      end
 
-  def in_tt?
-    @in_tt > 0
-  end
+      # Traverses +nodes+ and calls the appropriate handler methods
+      # Nodes formats are described in RDoc::Markup::InlineParser#parse
+
+      def traverse_inline_nodes(nodes)
+        nodes.each do |node|
+          next handle_TEXT(node) if String === node
+          case node[:type]
+          when :TIDYLINK
+            handle_TIDYLINK(node[:children], node[:url])
+          when :HARD_BREAK
+            handle_HARD_BREAK
+          when :BOLD
+            handle_BOLD(node[:children])
+          when :BOLD_WORD
+            handle_BOLD_WORD(node[:children][0] || '')
+          when :EM
+            handle_EM(node[:children])
+          when :EM_WORD
+            handle_EM_WORD(node[:children][0] || '')
+          when :TT
+            handle_TT(node[:children][0] || '')
+          when :STRIKE
+            handle_STRIKE(node[:children])
+          end
+        end
+      end
 
-  def tt_tag?(attr_mask, reverse = false)
-    each_attr_tag(attr_mask, reverse) do |tag|
-      return true if tt? tag
-    end
-    false
-  end
+      ##
+      # Converts a string to be fancier if desired
 
-  ##
-  # Turns on tags for +item+ on +res+
+      def convert_string(string)
+        string
+      end
 
-  def on_tags(res, item)
-    each_attr_tag(item.turn_on) do |tag|
-      res << annotate(tag.on)
-      @in_tt += 1 if tt? tag
-    end
-  end
+      ##
+      # Use ignore in your subclass to ignore the content of a node.
+      #
+      #   ##
+      #   # We don't support raw nodes in ToNoRaw
+      #
+      #   alias accept_raw ignore
 
-  ##
-  # Turns off tags for +item+ on +res+
+      def ignore(*node)
+      end
 
-  def off_tags(res, item)
-    each_attr_tag(item.turn_off, true) do |tag|
-      @in_tt -= 1 if tt? tag
-      res << annotate(tag.off)
-    end
-  end
+      ##
+      # Extracts and a scheme, url and an anchor id from +url+ and returns them.
+
+      def parse_url(url)
+        case url
+        when /^rdoc-label:([^:]*)(?::(.*))?/
+          scheme = 'link'
+          path   = "##{$1}"
+          id     = " id=\"#{$2}\"" if $2
+        when /([A-Za-z]+):(.*)/
+          scheme = $1.downcase
+          path   = $2
+        when /^#/
+        else
+          scheme = 'http'
+          path   = url
+          url    = url
+        end
+
+        if scheme == 'link'
+          url = if path[0, 1] == '#' # is this meaningful?
+                  path
+                else
+                  self.class.gen_relative_url @from_path, path
+                end
+        end
+
+        [scheme, url, id]
+      end
 
-  def each_attr_tag(attr_mask, reverse = false)
-    return if attr_mask.zero?
+      ##
+      # Is +tag+ a tt tag?
 
-    @attr_tags.public_send(reverse ? :reverse_each : :each) do |tag|
-      if attr_mask & tag.bit != 0 then
-        yield tag
+      def tt?(tag)
+        tag.bit == @tt_bit
       end
-    end
-  end
 
-  ##
-  # Extracts and a scheme, url and an anchor id from +url+ and returns them.
-
-  def parse_url(url)
-    case url
-    when /^rdoc-label:([^:]*)(?::(.*))?/ then
-      scheme = 'link'
-      path   = "##{$1}"
-      id     = " id=\"#{$2}\"" if $2
-    when /([A-Za-z]+):(.*)/ then
-      scheme = $1.downcase
-      path   = $2
-    when /^#/ then
-    else
-      scheme = 'http'
-      path   = url
-      url    = url
     end
-
-    if scheme == 'link' then
-      url = if path[0, 1] == '#' then # is this meaningful?
-              path
-            else
-              self.class.gen_relative_url @from_path, path
-            end
-    end
-
-    [scheme, url, id]
-  end
-
-  ##
-  # Is +tag+ a tt tag?
-
-  def tt?(tag)
-    tag.bit == @tt_bit
   end
-
 end

data/lib/rdoc/markup/hard_break.rb

@@ -1,31 +1,34 @@
 # frozen_string_literal: true
-##
-# A hard-break in the middle of a paragraph.
 
-class RDoc::Markup::HardBreak
-
-  @instance = new
-
-  ##
-  # RDoc::Markup::HardBreak is a singleton
-
-  def self.new
-    @instance
-  end
-
-  ##
-  # Calls #accept_hard_break on +visitor+
-
-  def accept(visitor)
-    visitor.accept_hard_break self
+module RDoc
+  class Markup
+    # A hard-break in the middle of a paragraph.
+    class HardBreak < Element
+      @instance = new
+
+      # RDoc::Markup::HardBreak is a singleton
+      #: () -> HardBreak
+      def self.new
+        @instance
+      end
+
+      # Calls #accept_hard_break on +visitor+
+      # @override
+      #: (untyped) -> void
+      def accept(visitor)
+        visitor.accept_hard_break(self)
+      end
+
+      #: (top) -> bool
+      def ==(other) # :nodoc:
+        self.class === other
+      end
+
+      # @override
+      #: (PP) -> void
+      def pretty_print(q) # :nodoc:
+        q.text("[break]")
+      end
+    end
   end
-
-  def ==(other) # :nodoc:
-    self.class === other
-  end
-
-  def pretty_print(q) # :nodoc:
-    q.text "[break]"
-  end
-
 end