Merge pull request #652 from aycabta/rename-special-with-regexp-handling

Rename the name "special" with "regexp handling"

lib/rdoc/cross_reference.rb

@@ -23,8 +23,8 @@ class RDoc::CrossReference
 
   ##
   # Regular expressions matching text that should potentially have
-  # cross-reference links generated are passed to add_special.  Note that
-  # these expressions are meant to pick up text for which cross-references
+  # cross-reference links generated are passed to add_regexp_handling. Note
+  # that these expressions are meant to pick up text for which cross-references
   # have been suppressed, since the suppression characters are removed by the
   # code that is triggered.
 

lib/rdoc/markup.rb

@@ -65,25 +65,24 @@
 #   puts h.convert(input_string)
 #
 # You can extend the RDoc::Markup parser to recognize new markup
-# sequences, and to add special processing for text that matches a
-# regular expression.  Here we make WikiWords significant to the parser,
-# and also make the sequences {word} and \<no>text...</no> signify
+# sequences, and to add regexp handling. Here we make WikiWords significant to
+# the parser, and also make the sequences {word} and \<no>text...</no> signify
 # strike-through text.  We then subclass the HTML output class to deal
 # with these:
 #
 #   require 'rdoc'
 #
 #   class WikiHtml < RDoc::Markup::ToHtml
-#     def handle_special_WIKIWORD(special)
-#       "<font color=red>" + special.text + "</font>"
+#     def handle_regexp_WIKIWORD(target)
+#       "<font color=red>" + target.text + "</font>"
 #     end
 #   end
 #
 #   markup = RDoc::Markup.new
 #   markup.add_word_pair("{", "}", :STRIKE)
 #   markup.add_html("no", :STRIKE)
 #
-#   markup.add_special(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
+#   markup.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
 #
 #   wh = WikiHtml.new RDoc::Options.new, markup
 #   wh.add_tag(:STRIKE, "<strike>", "</strike>")
@@ -800,13 +799,12 @@ def add_html(tag, name)
   # Add to other inline sequences.  For example, we could add WikiWords using
   # something like:
   #
-  #    parser.add_special(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
+  #    parser.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
   #
-  # Each wiki word will be presented to the output formatter via the
-  # accept_special method.
+  # Each wiki word will be presented to the output formatter.
 
-  def add_special(pattern, name)
-    @attribute_manager.add_special(pattern, name)
+  def add_regexp_handling(pattern, name)
+    @attribute_manager.add_regexp_handling(pattern, name)
   end
 
   ##
@@ -832,7 +830,7 @@ def convert input, formatter
   autoload :AttrSpan,              'rdoc/markup/attr_span'
   autoload :Attributes,            'rdoc/markup/attributes'
   autoload :AttributeManager,      'rdoc/markup/attribute_manager'
-  autoload :Special,               'rdoc/markup/special'
+  autoload :RegexpHandling,        'rdoc/markup/regexp_handling'
 
   # RDoc::Markup AST
   autoload :BlankLine,             'rdoc/markup/blank_line'

lib/rdoc/markup/attribute_manager.rb

@@ -53,10 +53,10 @@ 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
 
   ##
   # Creates a new attribute manager that understands bold, emphasized and
@@ -66,7 +66,7 @@ def initialize
     @html_tags = {}
     @matching_word_pairs = {}
     @protectable = %w[<]
-    @special = []
+    @regexp_handlings = []
     @word_pair_map = {}
     @attributes = RDoc::Markup::Attributes.new
 
@@ -166,22 +166,22 @@ def convert_html(str, attrs)
   end
 
   ##
-  # Converts special sequences to RDoc attributes
+  # Converts regexp handling sequences to RDoc attributes
 
-  def convert_specials str, attrs
-    @special.each do |regexp, attribute|
+  def convert_regexp_handlings str, attrs
+    @regexp_handlings.each do |regexp, attribute|
       str.scan(regexp) do
         capture = $~.size == 1 ? 0 : 1
 
         s, e = $~.offset capture
 
-        attrs.set_attrs s, e - s, attribute | @attributes.special
+        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.
@@ -193,7 +193,7 @@ def mask_protected_sequences
   end
 
   ##
-  # Unescapes special sequences of text
+  # Unescapes regexp handling sequences of text
 
   def unmask_protected_sequences
     @str.gsub!(/(.)#{PROTECT_ATTR}/, "\\1\000")
@@ -233,17 +233,17 @@ def add_html(tag, name)
   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, @attributes.bitmap_for(name)]
+  def add_regexp_handling pattern, name
+    @regexp_handlings << [pattern, @attributes.bitmap_for(name)]
   end
 
   ##
-  # Processes +str+ converting attributes, HTML and specials
+  # Processes +str+ converting attributes, HTML and regexp handlings
 
   def flow str
     @str = str.dup
@@ -252,9 +252,9 @@ def flow str
 
     @attrs = RDoc::Markup::AttrSpan.new @str.length
 
-    convert_attrs    @str, @attrs
-    convert_html     @str, @attrs
-    convert_specials @str, @attrs
+    convert_attrs            @str, @attrs
+    convert_html             @str, @attrs
+    convert_regexp_handlings @str, @attrs
 
     unmask_protected_sequences
 
@@ -312,12 +312,12 @@ def split_into_flow
         res << change_attribute(current_attr, new_attr)
         current_attr = new_attr
 
-        if (current_attr & @attributes.special) != 0 then
+        if (current_attr & @attributes.regexp_handling) != 0 then
           i += 1 while
-            i < str_len and (@attrs[i] & @attributes.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

lib/rdoc/markup/attributes.rb

@@ -6,21 +6,21 @@
 class RDoc::Markup::Attributes
 
   ##
-  # The special attribute type.  See RDoc::Markup#add_special
+  # The regexp handling attribute type. See RDoc::Markup#add_regexp_handling
 
-  attr_reader :special
+  attr_reader :regexp_handling
 
   ##
   # Creates a new attributes set.
 
   def initialize
-    @special = 1
+    @regexp_handling = 1
 
     @name_to_bitmap = [
-      [:_SPECIAL_, @special],
+      [:_REGEXP_HANDLING_, @regexp_handling],
     ]
 
-    @next_bitmap = @special << 1
+    @next_bitmap = @regexp_handling << 1
   end
 
   ##
@@ -61,7 +61,7 @@ def each_name_of bitmap
     return enum_for __method__, bitmap unless block_given?
 
     @name_to_bitmap.each do |name, bit|
-      next if bit == @special
+      next if bit == @regexp_handling
 
       yield name.to_s if (bitmap & bit) != 0
     end

lib/rdoc/markup/formatter.rb

@@ -50,7 +50,7 @@ def initialize options, markup = nil
 
     @markup = markup || RDoc::Markup.new
     @am     = @markup.attribute_manager
-    @am.add_special(/<br>/, :HARD_BREAK)
+    @am.add_regexp_handling(/<br>/, :HARD_BREAK)
 
     @attributes = @am.attributes
 
@@ -78,23 +78,24 @@ def accept_document document
   end
 
   ##
-  # Adds a special for links of the form rdoc-...:
+  # Adds a regexp handling for links of the form rdoc-...:
 
-  def add_special_RDOCLINK
-    @markup.add_special(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
+  def add_regexp_handling_RDOCLINK
+    @markup.add_regexp_handling(/rdoc-[a-z]+:[^\s\]]+/, :RDOCLINK)
   end
 
   ##
-  # Adds a special for links of the form {<text>}[<url>] and <word>[<url>]
+  # Adds a regexp handling for links of the form {<text>}[<url>] and
+  # <word>[<url>]
 
-  def add_special_TIDYLINK
-    @markup.add_special(/(?:
-                          \{.*?\} |    # multi-word label
-                          \b[^\s{}]+? # single-word label
-                         )
+  def add_regexp_handling_TIDYLINK
+    @markup.add_regexp_handling(/(?:
+                                  \{.*?\} |    # multi-word label
+                                  \b[^\s{}]+? # single-word label
+                                 )
 
-                         \[\S+?\]     # link target
-                        /x, :TIDYLINK)
+                                 \[\S+?\]     # link target
+                                /x, :TIDYLINK)
   end
 
   ##
@@ -133,8 +134,8 @@ def convert_flow(flow)
       when RDoc::Markup::AttrChanger then
         off_tags res, item
         on_tags res, item
-      when RDoc::Markup::Special then
-        res << convert_special(item)
+      when RDoc::Markup::RegexpHandling then
+        res << convert_regexp_handling(item)
       else
         raise "Unknown flow element: #{item.inspect}"
       end
@@ -144,29 +145,29 @@ def convert_flow(flow)
   end
 
   ##
-  # Converts added specials.  See RDoc::Markup#add_special
+  # Converts added regexp handlings. See RDoc::Markup#add_regexp_handling
 
-  def convert_special special
-    return special.text if in_tt?
+  def convert_regexp_handling target
+    return target.text if in_tt?
 
     handled = false
 
-    @attributes.each_name_of special.type do |name|
-      method_name = "handle_special_#{name}"
+    @attributes.each_name_of target.type do |name|
+      method_name = "handle_regexp_#{name}"
 
       if respond_to? method_name then
-        special.text = send method_name, special
+        target.text = send method_name, target
         handled = true
       end
     end
 
     unless handled then
-      special_name = @attributes.as_string special.type
+      target_name = @attributes.as_string target.type
 
-      raise RDoc::Error, "Unhandled special #{special_name}: #{special}"
+      raise RDoc::Error, "Unhandled regexp handling #{target_name}: #{target}"
     end
 
-    special.text
+    target.text
   end
 
   ##

lib/rdoc/markup/heading.rb

@@ -23,12 +23,12 @@ def self.to_html
     return @to_html if @to_html
 
     markup = RDoc::Markup.new
-    markup.add_special RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
+    markup.add_regexp_handling RDoc::CrossReference::CROSSREF_REGEXP, :CROSSREF
 
     @to_html = RDoc::Markup::ToHtml.new nil
 
-    def @to_html.handle_special_CROSSREF special
-      special.text.sub(/^\\/, '')
+    def @to_html.handle_regexp_CROSSREF target
+      target.text.sub(/^\\/, '')
     end
 
     @to_html

lib/rdoc/markup/regexp_handling.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+##
+# Hold details of a regexp handling sequence
+
+class RDoc::Markup::RegexpHandling
+
+  ##
+  # Regexp handling type
+
+  attr_reader   :type
+
+  ##
+  # Regexp handling text
+
+  attr_accessor :text
+
+  ##
+  # Creates a new regexp handling sequence of +type+ with +text+
+
+  def initialize(type, text)
+    @type, @text = type, text
+  end
+
+  ##
+  # Regexp handlings are equal when the have the same text and type
+
+  def ==(o)
+    self.text == o.text && self.type == o.type
+  end
+
+  def inspect # :nodoc:
+    "#<RDoc::Markup::RegexpHandling:0x%x @type=%p, @text=%p>" % [
+      object_id, @type, text.dump]
+  end
+
+  def to_s # :nodoc:
+    "RegexpHandling: type=#{type} text=#{text.dump}"
+  end
+
+end
+