rdoc 7.0.3 → 7.2.0

data/lib/rdoc/markup/formatter.rb

@@ -10,6 +10,8 @@
 # RDoc::Markup::FormatterTestCase.  If you're writing a text-output formatter
 # use RDoc::Markup::TextFormatterTestCase which provides extra test cases.
 
+require 'rdoc/markup/inline_parser'
+
 class RDoc::Markup::Formatter
 
   ##
@@ -18,6 +20,7 @@ class RDoc::Markup::Formatter
 
   InlineTag = Struct.new(:bit, :on, :off)
 
+
   ##
   # Converts a target url to one that is relative to a given path
 
@@ -49,17 +52,7 @@ class RDoc::Markup::Formatter
     @options = options
 
     @markup = markup || RDoc::Markup.new
-    @am     = @markup.attribute_manager
-    @am.add_regexp_handling(/<br>/, :HARD_BREAK)
-
-    @attributes = @am.attributes
-
-    @attr_tags = []
-
-    @in_tt = 0
-    @tt_bit = @attributes.bitmap_for :TT
 
-    @hard_break = ''
     @from_path = '.'
   end
 
@@ -84,29 +77,6 @@ class RDoc::Markup::Formatter
     @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
   end
 
-  ##
-  # Adds a regexp handling for links of the form {<text>}[<url>] and
-  # <word>[<url>]
-
-  def add_regexp_handling_TIDYLINK
-    @markup.add_regexp_handling(/(?:
-                                  \{[^{}]*\} | # multi-word label
-                                  \b[^\s{}]+? # single-word label
-                                 )
-
-                                 \[\S+?\]     # link target
-                                /x, :TIDYLINK)
-  end
-
-  ##
-  # Add a new set of tags for an attribute. We allow separate start and end
-  # tags for flexibility
-
-  def add_tag(name, start, stop)
-    attr = @attributes.bitmap_for name
-    @attr_tags << InlineTag.new(attr, start, stop)
-  end
-
   ##
   # Allows +tag+ to be decorated with additional information.
 
@@ -121,117 +91,170 @@ class RDoc::Markup::Formatter
     @markup.convert content, self
   end
 
-  ##
-  # 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)
+  # Applies regexp handling to +text+ and returns an array of [text, converted?] pairs.
+
+  def apply_regexp_handling(text)
+    output = []
+    start = 0
+    loop do
+      pos = text.size
+      matched_name = matched_text = nil
+      @markup.regexp_handlings.each do |pattern, name|
+        m = text.match(pattern, start)
+        next unless m
+        idx = m[1] ? 1 : 0
+        if m.begin(idx) < pos
+          pos = m.begin(idx)
+          matched_text = m[idx]
+          matched_name = name
+        end
+      end
+      output << [text[start...pos], false] if pos > start
+      if matched_name
+        handled = public_send(:"handle_regexp_#{matched_name}", matched_text)
+        output << [handled, true]
+        start = pos + matched_text.size
       else
-        raise "Unknown flow element: #{item.inspect}"
+        start = pos
       end
+      break if pos == text.size
     end
-
-    res.join
+    output
   end
 
-  ##
-  # Converts added regexp handlings. See RDoc::Markup#add_regexp_handling
+  # Called when processing plain text while traversing inline nodes from handle_inline.
+  # +text+ may need proper escaping.
 
-  def convert_regexp_handling(target)
-    return target.text if in_tt?
+  def handle_PLAIN_TEXT(text)
+  end
 
-    handled = false
+  # Called when processing regexp-handling-processed text while traversing inline nodes from handle_inline.
+  # +text+ may contain markup tags.
 
-    @attributes.each_name_of target.type do |name|
-      method_name = "handle_regexp_#{name}"
+  def handle_REGEXP_HANDLING_TEXT(text)
+  end
+
+  # 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.
 
-      if respond_to? method_name then
-        target.text = public_send method_name, target
-        handled = true
+  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
 
-    unless handled then
-      target_name = @attributes.as_string target.type
+  # Called when processing a hard break while traversing inline nodes from handle_inline.
 
-      raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
-    end
+  def handle_HARD_BREAK
+  end
 
-    target.text
+  # Called when processing bold nodes while traversing inline nodes from handle_inline.
+  # Traverse the children nodes and dispatch to the appropriate handlers.
+
+  def handle_BOLD(nodes)
+    traverse_inline_nodes(nodes)
   end
 
-  ##
-  # Converts a string to be fancier if desired
+  # Called when processing emphasis nodes while traversing inline nodes from handle_inline.
+  # Traverse the children nodes and dispatch to the appropriate handlers.
 
-  def convert_string(string)
-    string
+  def handle_EM(nodes)
+    traverse_inline_nodes(nodes)
   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
+  # Called when processing bold word nodes while traversing inline nodes from handle_inline.
+  # +word+ may need proper escaping.
 
-  def ignore *node
+  def handle_BOLD_WORD(word)
+    handle_PLAIN_TEXT(word)
   end
 
-  ##
-  # Are we currently inside tt tags?
+  # Called when processing emphasis word nodes while traversing inline nodes from handle_inline.
+  # +word+ may need proper escaping.
 
-  def in_tt?
-    @in_tt > 0
+  def handle_EM_WORD(word)
+    handle_PLAIN_TEXT(word)
   end
 
-  def tt_tag?(attr_mask, reverse = false)
-    each_attr_tag(attr_mask, reverse) do |tag|
-      return true if tt? tag
-    end
-    false
+  # Called when processing tt nodes while traversing inline nodes from handle_inline.
+  # +code+ may need proper escaping.
+
+  def handle_TT(code)
+    handle_PLAIN_TEXT(code)
   end
 
-  ##
-  # Turns on tags for +item+ on +res+
+  # Called when processing strike nodes while traversing inline nodes from handle_inline.
+  # Traverse the children nodes and dispatch to the appropriate handlers.
 
-  def on_tags(res, item)
-    each_attr_tag(item.turn_on) do |tag|
-      res << annotate(tag.on)
-      @in_tt += 1 if tt? tag
-    end
+  def handle_STRIKE(nodes)
+    traverse_inline_nodes(nodes)
   end
 
-  ##
-  # Turns off tags for +item+ on +res+
+  # 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.
 
-  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
+  def handle_TIDYLINK(label_part, url)
+    traverse_inline_nodes(label_part)
   end
 
-  def each_attr_tag(attr_mask, reverse = false)
-    return if attr_mask.zero?
+  # Parses inline +text+, traverse the resulting nodes, and calls the appropriate handler methods.
+
+  def handle_inline(text)
+    nodes = RDoc::Markup::InlineParser.new(text).parse
+    traverse_inline_nodes(nodes)
+  end
 
-    @attr_tags.public_send(reverse ? :reverse_each : :each) do |tag|
-      if attr_mask & tag.bit != 0 then
-        yield tag
+  # 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
 
+  ##
+  # Converts a string to be fancier if desired
+
+  def convert_string(string)
+    string
+  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
+
+  def ignore *node
+  end
+
   ##
   # Extracts and a scheme, url and an anchor id from +url+ and returns them.
 

data/lib/rdoc/markup/heading.rb

@@ -2,6 +2,33 @@
 
 module RDoc
   class Markup
+    # IMPORTANT! This weird workaround is required to ensure that RDoc can correctly deserializing Marshal data from
+    # older rubies. Older rubies have `Heading` as a struct, so if we change it to a class, deserialization fails
+    if RUBY_VERSION.start_with?("4.")
+      class Heading < Element
+        #: String
+        attr_reader :text
+
+        #: Integer
+        attr_accessor :level
+
+        #: (Integer, String) -> void
+        def initialize(level, text)
+          super()
+
+          @level = level
+          @text = text
+        end
+
+        #: (Object) -> bool
+        def ==(other)
+          other.is_a?(Heading) && other.level == @level && other.text == @text
+        end
+      end
+    else
+      Heading = Struct.new(:level, :text)
+    end
+
     # A heading with a level (1-6) and text
     #
     #  RDoc syntax:
@@ -13,13 +40,8 @@ module RDoc
     #   # Heading 1
     #   ## Heading 2
     #   ### Heading 3
-    class Heading < Element
-      #: String
-      attr_reader :text
-
-      #: Integer
-      attr_accessor :level
-
+    #
+    class Heading
       # A singleton RDoc::Markup::ToLabel formatter for headings.
       #: () -> RDoc::Markup::ToLabel
       def self.to_label
@@ -35,46 +57,96 @@ module RDoc
 
           to_html = Markup::ToHtml.new nil
 
-          def to_html.handle_regexp_CROSSREF(target)
-            target.text.sub(/^\\/, '')
+          def to_html.handle_regexp_CROSSREF(text)
+            text.sub(/^\\/, '')
           end
 
           to_html
         end
       end
 
-      #: (Integer, String) -> void
-      def initialize(level, text)
-        super()
-
-        @level = level
-        @text = text
-      end
-
-      #: (Object) -> bool
-      def ==(other)
-        other.is_a?(Heading) && other.level == @level && other.text == @text
-      end
-
       # @override
       #: (untyped) -> void
       def accept(visitor)
         visitor.accept_heading(self)
       end
 
-      # An HTML-safe anchor reference for this header.
+      # An HTML-safe anchor reference for this header using GitHub-style formatting:
+      # - Lowercase
+      # - Spaces converted to hyphens
+      # - Special characters removed (except hyphens)
+      #
+      # Examples:
+      #   "Hello"       -> "hello"
+      #   "Hello World" -> "hello-world"
+      #   "Foo Bar Baz" -> "foo-bar-baz"
+      #
       #: () -> String
       def aref
-        "label-#{self.class.to_label.convert text.dup}"
+        self.class.to_label.convert text.dup
+      end
+
+      # An HTML-safe anchor reference using legacy RDoc formatting:
+      # - Prefixed with "label-"
+      # - Original case preserved
+      # - Spaces converted to + (URL encoding style)
+      # - Special characters percent-encoded
+      #
+      # Returns nil if it would be the same as the GitHub-style aref (no alias needed).
+      #
+      # Examples:
+      #   "hello"       -> "label-hello" (different due to label- prefix)
+      #   "Hello"       -> "label-Hello"
+      #   "Hello World" -> "label-Hello+World"
+      #   "Foo Bar Baz" -> "label-Foo+Bar+Baz"
+      #
+      #: () -> String?
+      def legacy_aref
+        "label-#{self.class.to_label.convert_legacy text.dup}"
       end
 
-      # Creates a fully-qualified label which will include the label from +context+. This helps keep ids unique in HTML.
+      # Creates a fully-qualified label (GitHub-style) which includes the context's aref prefix.
+      # This helps keep IDs unique in HTML when headings appear within class/method documentation.
+      #
+      # Examples (without context):
+      #   "Hello World" -> "hello-world"
+      #
+      # Examples (with context being class Foo):
+      #   "Hello World" -> "class-foo-hello-world"
+      #
+      # Examples (with context being method #bar):
+      #   "Hello World" -> "method-i-bar-hello-world"
+      #
       #: (RDoc::Context?) -> String
       def label(context = nil)
-        label = +""
-        label << "#{context.aref}-" if context&.respond_to?(:aref)
-        label << aref
-        label
+        result = +""
+        result << "#{context.aref}-" if context&.respond_to?(:aref)
+        result << aref
+        result
+      end
+
+      # Creates a fully-qualified legacy label for backward compatibility.
+      # This is used to generate a secondary ID attribute on the heading's inner anchor,
+      # allowing old-style links (e.g., #label-Hello+World) to continue working.
+      #
+      # Examples (without context):
+      #   "hello"       -> "label-hello"
+      #   "Hello World" -> "label-Hello+World"
+      #
+      # Examples (with context being class Foo):
+      #   "hello"       -> "class-Foo-label-hello"
+      #   "Hello World" -> "class-Foo-label-Hello+World"
+      #
+      #: (RDoc::Context?) -> String
+      def legacy_label(context = nil)
+        result = +""
+        if context&.respond_to?(:legacy_aref)
+          result << "#{context.legacy_aref}-"
+        elsif context&.respond_to?(:aref)
+          result << "#{context.aref}-"
+        end
+        result << legacy_aref
+        result
       end
 
       # HTML markup of the text of this label without the surrounding header element.