rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/attr_changer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+class RDoc::Markup
+
+  AttrChanger = Struct.new :turn_on, :turn_off # :nodoc:
+
+end
+
+##
+# An AttrChanger records a change in attributes. It contains a bitmap of the
+# attributes to turn on, and a bitmap of those to turn off.
+
+class RDoc::Markup::AttrChanger
+
+  def to_s # :nodoc:
+    "Attr: +#{turn_on}/-#{turn_off}"
+  end
+
+  def inspect # :nodoc:
+    '+%d/-%d' % [turn_on, turn_off]
+  end
+
+end
+

data/lib/rdoc/markup/attr_span.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+##
+# An array of attributes which parallels the characters in a string.
+
+class RDoc::Markup::AttrSpan
+
+  ##
+  # Creates a new AttrSpan for +length+ characters
+
+  def initialize(length, exclusive)
+    @attrs = Array.new(length, 0)
+    @exclusive = exclusive
+  end
+
+  ##
+  # Toggles +bits+ from +start+ to +length+
+  def set_attrs(start, length, bits)
+    updated = false
+    for i in start ... (start+length)
+      if (@exclusive & @attrs[i]) == 0 || (@exclusive & bits) != 0
+        @attrs[i] |= bits
+        updated = true
+      end
+    end
+    updated
+  end
+
+  ##
+  # Accesses flags for character +n+
+
+  def [](n)
+    @attrs[n]
+  end
+
+end
+

data/lib/rdoc/markup/attribute_manager.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # Manages changes of attributes in a block of text
 
@@ -22,6 +23,11 @@ class RDoc::Markup::AttributeManager
 
   PROTECT_ATTR = A_PROTECT.chr # :nodoc:
 
+  ##
+  # The attributes enabled for this markup object.
+
+  attr_reader :attributes
+
   ##
   # This maps delimiters that occur around words (such as *bold* or +tt+)
   # where the start and end delimiters and the same. This lets us optimize
@@ -47,10 +53,14 @@ class RDoc::Markup::AttributeManager
   attr_reader :protectable
 
   ##
-  # And this maps _special_ sequences to a name. A special sequence is
-  # something like a WikiWord
+  # And this maps _regexp handling_ sequences to a name. A regexp handling
+  # sequence is something like a WikiWord
 
-  attr_reader :special
+  attr_reader :regexp_handlings
+
+  ##
+  # A bits of exclusive maps
+  attr_reader :exclusive_bitmap
 
   ##
   # Creates a new attribute manager that understands bold, emphasized and
@@ -60,21 +70,22 @@ class RDoc::Markup::AttributeManager
     @html_tags = {}
     @matching_word_pairs = {}
     @protectable = %w[<]
-    @special = {}
+    @regexp_handlings = []
     @word_pair_map = {}
-
-    add_word_pair "*", "*", :BOLD
-    add_word_pair "_", "_", :EM
-    add_word_pair "+", "+", :TT
-
-    add_html "em", :EM
-    add_html "i",  :EM
-    add_html "b",  :BOLD
-    add_html "tt",   :TT
-    add_html "code", :TT
+    @exclusive_bitmap = 0
+    @attributes = RDoc::Markup::Attributes.new
+
+    add_word_pair "*", "*", :BOLD, true
+    add_word_pair "_", "_", :EM, true
+    add_word_pair "+", "+", :TT, true
+
+    add_html "em", :EM, true
+    add_html "i",  :EM, true
+    add_html "b",  :BOLD, true
+    add_html "tt",   :TT, true
+    add_html "code", :TT, true
   end
 
-
   ##
   # Return an attribute object with the given turn_on and turn_off bits set
 
@@ -97,11 +108,11 @@ class RDoc::Markup::AttributeManager
   def changed_attribute_by_name current_set, new_set
     current = new = 0
     current_set.each do |name|
-      current |= RDoc::Markup::Attribute.bitmap_for(name)
+      current |= @attributes.bitmap_for(name)
     end
 
     new_set.each do |name|
-      new |= RDoc::Markup::Attribute.bitmap_for(name)
+      new |= @attributes.bitmap_for(name)
     end
 
     change_attribute(current, new)
@@ -116,29 +127,67 @@ class RDoc::Markup::AttributeManager
     res
   end
 
+  def exclusive?(attr)
+    (attr & @exclusive_bitmap) != 0
+  end
+
+  NON_PRINTING_START = "\1" # :nodoc:
+  NON_PRINTING_END = "\2" # :nodoc:
+
   ##
   # Map attributes like <b>text</b>to the sequence
   # \001\002<char>\001\003<char>, where <char> is a per-attribute specific
   # character
 
-  def convert_attrs(str, attrs)
+  def convert_attrs(str, attrs, exclusive = false)
+    convert_attrs_matching_word_pairs(str, attrs, exclusive)
+    convert_attrs_word_pair_map(str, attrs, exclusive)
+  end
+
+  def convert_attrs_matching_word_pairs(str, attrs, exclusive)
     # first do matching ones
-    tags = @matching_word_pairs.keys.join("")
+    tags = @matching_word_pairs.select { |start, bitmap|
+      if exclusive && exclusive?(bitmap)
+        true
+      elsif !exclusive && !exclusive?(bitmap)
+        true
+      else
+        false
+      end
+    }.keys
+    return if tags.empty?
+    all_tags = @matching_word_pairs.keys
 
-    re = /(^|\W)([#{tags}])([#:\\]?[\w.\/-]+?\S?)\2(\W|$)/
+    re = /(^|\W|[#{all_tags.join("")}])([#{tags.join("")}])(\2*[#\\]?[\w:.\/\[\]-]+?\S?)\2(?!\2)([#{all_tags.join("")}]|\W|$)/
 
-    1 while str.gsub!(re) do
+    1 while str.gsub!(re) { |orig|
       attr = @matching_word_pairs[$2]
-      attrs.set_attrs($`.length + $1.length + $2.length, $3.length, attr)
-      $1 + NULL * $2.length + $3 + NULL * $2.length + $4
-    end
+      attr_updated = attrs.set_attrs($`.length + $1.length + $2.length, $3.length, attr)
+      if attr_updated
+        $1 + NULL * $2.length + $3 + NULL * $2.length + $4
+      else
+        $1 + NON_PRINTING_START + $2 + NON_PRINTING_END + $3 + NON_PRINTING_START + $2 + NON_PRINTING_END + $4
+      end
+    }
+    str.delete!(NON_PRINTING_START + NON_PRINTING_END)
+  end
 
+  def convert_attrs_word_pair_map(str, attrs, exclusive)
     # then non-matching
     unless @word_pair_map.empty? then
       @word_pair_map.each do |regexp, attr|
-        str.gsub!(regexp) {
-          attrs.set_attrs($`.length + $1.length, $2.length, attr)
-          NULL * $1.length + $2 + NULL * $3.length
+        if !exclusive
+          next if exclusive?(attr)
+        else
+          next if !exclusive?(attr)
+        end
+        1 while str.gsub!(regexp) { |orig|
+          updated = attrs.set_attrs($`.length + $1.length, $2.length, attr)
+          if updated
+            NULL * $1.length + $2 + NULL * $3.length
+          else
+            orig
+          end
         }
       end
     end
@@ -147,10 +196,18 @@ class RDoc::Markup::AttributeManager
   ##
   # Converts HTML tags to RDoc attributes
 
-  def convert_html(str, attrs)
-    tags = @html_tags.keys.join '|'
+  def convert_html(str, attrs, exclusive = false)
+    tags = @html_tags.select { |start, bitmap|
+      if exclusive && exclusive?(bitmap)
+        true
+      elsif !exclusive && !exclusive?(bitmap)
+        true
+      else
+        false
+      end
+    }.keys.join '|'
 
-    1 while str.gsub!(/<(#{tags})>(.*?)<\/\1>/i) {
+    1 while str.gsub!(/<(#{tags})>(.*?)<\/\1>/i) { |orig|
       attr = @html_tags[$1.downcase]
       html_length = $1.length + 2
       seq = NULL * html_length
@@ -160,32 +217,39 @@ class RDoc::Markup::AttributeManager
   end
 
   ##
-  # Converts special sequences to RDoc attributes
-
-  def convert_specials(str, attrs)
-    unless @special.empty?
-      @special.each do |regexp, attr|
-        str.scan(regexp) do
-          attrs.set_attrs($`.length, $&.length,
-                          attr | RDoc::Markup::Attribute::SPECIAL)
-        end
+  # Converts regexp handling sequences to RDoc attributes
+
+  def convert_regexp_handlings str, attrs, exclusive = false
+    @regexp_handlings.each do |regexp, attribute|
+      if exclusive
+        next if !exclusive?(attribute)
+      else
+        next if exclusive?(attribute)
+      end
+      str.scan(regexp) do
+        capture = $~.size == 1 ? 0 : 1
+
+        s, e = $~.offset capture
+
+        attrs.set_attrs s, e - s, attribute | @attributes.regexp_handling
       end
     end
   end
 
   ##
-  # Escapes special sequences of text to prevent conversion to RDoc
+  # Escapes regexp handling sequences of text to prevent conversion to RDoc
 
   def mask_protected_sequences
     # protect __send__, __FILE__, etc.
     @str.gsub!(/__([a-z]+)__/i,
       "_#{PROTECT_ATTR}_#{PROTECT_ATTR}\\1_#{PROTECT_ATTR}_#{PROTECT_ATTR}")
-    @str.gsub!(/\\([#{Regexp.escape @protectable.join('')}])/,
-               "\\1#{PROTECT_ATTR}")
+    @str.gsub!(/(\A|[^\\])\\([#{Regexp.escape @protectable.join}])/m,
+               "\\1\\2#{PROTECT_ATTR}")
+    @str.gsub!(/\\(\\[#{Regexp.escape @protectable.join}])/m, "\\1")
   end
 
   ##
-  # Unescapes special sequences of text
+  # Unescapes regexp handling sequences of text
 
   def unmask_protected_sequences
     @str.gsub!(/(.)#{PROTECT_ATTR}/, "\\1\000")
@@ -197,11 +261,11 @@ class RDoc::Markup::AttributeManager
   #
   #   am.add_word_pair '*', '*', :BOLD
 
-  def add_word_pair(start, stop, name)
+  def add_word_pair(start, stop, name, exclusive = false)
     raise ArgumentError, "Word flags may not start with '<'" if
       start[0,1] == '<'
 
-    bitmap = RDoc::Markup::Attribute.bitmap_for name
+    bitmap = @attributes.bitmap_for name
 
     if start == stop then
       @matching_word_pairs[start] = bitmap
@@ -212,6 +276,8 @@ class RDoc::Markup::AttributeManager
 
     @protectable << start[0,1]
     @protectable.uniq!
+
+    @exclusive_bitmap |= bitmap if exclusive
   end
 
   ##
@@ -220,33 +286,40 @@ class RDoc::Markup::AttributeManager
   #
   #   am.add_html 'em', :EM
 
-  def add_html(tag, name)
-    @html_tags[tag.downcase] = RDoc::Markup::Attribute.bitmap_for name
+  def add_html(tag, name, exclusive = false)
+    bitmap = @attributes.bitmap_for name
+    @html_tags[tag.downcase] = bitmap
+    @exclusive_bitmap |= bitmap if exclusive
   end
 
   ##
-  # Adds a special handler for +pattern+ with +name+.  A simple URL handler
+  # Adds a regexp handling for +pattern+ with +name+.  A simple URL handler
   # would be:
   #
-  #   @am.add_special(/((https?:)\S+\w)/, :HYPERLINK)
+  #   @am.add_regexp_handling(/((https?:)\S+\w)/, :HYPERLINK)
 
-  def add_special(pattern, name)
-    @special[pattern] = RDoc::Markup::Attribute.bitmap_for name
+  def add_regexp_handling pattern, name, exclusive = false
+    bitmap = @attributes.bitmap_for(name)
+    @regexp_handlings << [pattern, bitmap]
+    @exclusive_bitmap |= bitmap if exclusive
   end
 
   ##
-  # Processes +str+ converting attributes, HTML and specials
+  # Processes +str+ converting attributes, HTML and regexp handlings
 
-  def flow(str)
-    @str = str
+  def flow str
+    @str = str.dup
 
     mask_protected_sequences
 
-    @attrs = RDoc::Markup::AttrSpan.new @str.length
+    @attrs = RDoc::Markup::AttrSpan.new @str.length, @exclusive_bitmap
 
-    convert_attrs    @str, @attrs
-    convert_html     @str, @attrs
-    convert_specials @str, @attrs
+    convert_attrs            @str, @attrs, true
+    convert_html             @str, @attrs, true
+    convert_regexp_handlings @str, @attrs, true
+    convert_attrs            @str, @attrs
+    convert_html             @str, @attrs
+    convert_regexp_handlings @str, @attrs
 
     unmask_protected_sequences
 
@@ -304,12 +377,12 @@ class RDoc::Markup::AttributeManager
         res << change_attribute(current_attr, new_attr)
         current_attr = new_attr
 
-        if (current_attr & RDoc::Markup::Attribute::SPECIAL) != 0 then
+        if (current_attr & @attributes.regexp_handling) != 0 then
           i += 1 while
-            i < str_len and (@attrs[i] & RDoc::Markup::Attribute::SPECIAL) != 0
+            i < str_len and (@attrs[i] & @attributes.regexp_handling) != 0
 
-          res << RDoc::Markup::Special.new(current_attr,
-                                           copy_string(start_pos, i))
+          res << RDoc::Markup::RegexpHandling.new(current_attr,
+                                                  copy_string(start_pos, i))
           start_pos = i
           next
         end

data/lib/rdoc/markup/attributes.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+##
+# We manage a set of attributes.  Each attribute has a symbol name and a bit
+# value.
+
+class RDoc::Markup::Attributes
+
+  ##
+  # The regexp handling attribute type. See RDoc::Markup#add_regexp_handling
+
+  attr_reader :regexp_handling
+
+  ##
+  # Creates a new attributes set.
+
+  def initialize
+    @regexp_handling = 1
+
+    @name_to_bitmap = [
+      [:_REGEXP_HANDLING_, @regexp_handling],
+    ]
+
+    @next_bitmap = @regexp_handling << 1
+  end
+
+  ##
+  # Returns a unique bit for +name+
+
+  def bitmap_for name
+    bitmap = @name_to_bitmap.assoc name
+
+    unless bitmap then
+      bitmap = @next_bitmap
+      @next_bitmap <<= 1
+      @name_to_bitmap << [name, bitmap]
+    else
+      bitmap = bitmap.last
+    end
+
+    bitmap
+  end
+
+  ##
+  # Returns a string representation of +bitmap+
+
+  def as_string bitmap
+    return 'none' if bitmap.zero?
+    res = []
+
+    @name_to_bitmap.each do |name, bit|
+      res << name if (bitmap & bit) != 0
+    end
+
+    res.join ','
+  end
+
+  ##
+  # yields each attribute name in +bitmap+
+
+  def each_name_of bitmap
+    return enum_for __method__, bitmap unless block_given?
+
+    @name_to_bitmap.each do |name, bit|
+      next if bit == @regexp_handling
+
+      yield name.to_s if (bitmap & bit) != 0
+    end
+  end
+
+end
+

data/lib/rdoc/markup/blank_line.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # An empty line.  This class is a singleton.
 

data/lib/rdoc/markup/block_quote.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+##
+# A quoted section which contains markup items.
+
+class RDoc::Markup::BlockQuote < RDoc::Markup::Raw
+
+  ##
+  # Calls #accept_block_quote on +visitor+
+
+  def accept visitor
+    visitor.accept_block_quote self
+  end
+
+end
+

data/lib/rdoc/markup/document.rb

@@ -1,8 +1,23 @@
+# frozen_string_literal: true
 ##
 # A Document containing lists, headings, paragraphs, etc.
 
 class RDoc::Markup::Document
 
+  include Enumerable
+
+  ##
+  # The file this document was created from.  See also
+  # RDoc::ClassModule#add_comment
+
+  attr_reader :file
+
+  ##
+  # If a heading is below the given level it will be omitted from the
+  # table_of_contents
+
+  attr_accessor :omit_headings_below
+
   ##
   # The parts of the Document
 
@@ -13,7 +28,10 @@ class RDoc::Markup::Document
 
   def initialize *parts
     @parts = []
-    @parts.push(*parts)
+    @parts.concat parts
+
+    @file = nil
+    @omit_headings_from_table_of_contents_below = nil
   end
 
   ##
@@ -23,7 +41,7 @@ class RDoc::Markup::Document
     case part
     when RDoc::Markup::Document then
       unless part.empty? then
-        parts.push(*part.parts)
+        parts.concat part.parts
         parts << RDoc::Markup::BlankLine.new
       end
     when String then
@@ -36,7 +54,9 @@ class RDoc::Markup::Document
   end
 
   def == other # :nodoc:
-    self.class == other.class and @parts == other.parts
+    self.class == other.class and
+      @file == other.file and
+      @parts == other.parts
   end
 
   ##
@@ -45,22 +65,80 @@ class RDoc::Markup::Document
   def accept visitor
     visitor.start_accepting
 
-    @parts.each do |item|
-      item.accept visitor
-    end
+    visitor.accept_document self
 
     visitor.end_accepting
   end
 
+  ##
+  # Concatenates the given +parts+ onto the document
+
+  def concat parts
+    self.parts.concat parts
+  end
+
+  ##
+  # Enumerator for the parts of this document
+
+  def each &block
+    @parts.each(&block)
+  end
+
   ##
   # Does this document have no parts?
 
   def empty?
-    @parts.empty?
+    @parts.empty? or (@parts.length == 1 and merged? and @parts.first.empty?)
+  end
+
+  ##
+  # The file this Document was created from.
+
+  def file= location
+    @file = case location
+            when RDoc::TopLevel then
+              location.relative_name
+            else
+              location
+            end
+  end
+
+  ##
+  # When this is a collection of documents (#file is not set and this document
+  # contains only other documents as its direct children) #merge replaces
+  # documents in this class with documents from +other+ when the file matches
+  # and adds documents from +other+ when the files do not.
+  #
+  # The information in +other+ is preferred over the receiver
+
+  def merge other
+    if empty? then
+      @parts = other.parts
+      return self
+    end
+
+    other.parts.each do |other_part|
+      self.parts.delete_if do |self_part|
+        self_part.file and self_part.file == other_part.file
+      end
+
+      self.parts << other_part
+    end
+
+    self
+  end
+
+  ##
+  # Does this Document contain other Documents?
+
+  def merged?
+    RDoc::Markup::Document === @parts.first
   end
 
   def pretty_print q # :nodoc:
-    q.group 2, '[doc: ', ']' do
+    start = @file ? "[doc (#{@file}): " : '[doc: '
+
+    q.group 2, start, ']' do
       q.seplist @parts do |part|
         q.pp part
       end
@@ -71,7 +149,16 @@ class RDoc::Markup::Document
   # Appends +parts+ to the document
 
   def push *parts
-    self.parts.push(*parts)
+    self.parts.concat parts
+  end
+
+  ##
+  # Returns an Array of headings in the document.
+  #
+  # Require 'rdoc/markup/formatter' before calling this method.
+
+  def table_of_contents
+    accept RDoc::Markup::ToTableOfContents.to_toc
   end
 
 end