rdoc 3.1 → 6.3.3

data/lib/rdoc/markup/pre_process.rb

@@ -1,6 +1,4 @@
-require 'rdoc/markup'
-require 'rdoc/encoding'
-
+# frozen_string_literal: true
 ##
 # Handle common directives that can occur in a block of text:
 #
@@ -9,16 +7,48 @@ require 'rdoc/encoding'
 # Directives can be escaped by preceding them with a backslash.
 #
 # RDoc plugin authors can register additional directives to be handled by
-# using RDoc::Markup::PreProcess::register
+# using RDoc::Markup::PreProcess::register.
+#
+# Any directive that is not built-in to RDoc (including those registered via
+# plugins) will be stored in the metadata hash on the CodeObject the comment
+# is attached to.  See RDoc::Markup@Directives for the list of built-in
+# directives.
 
 class RDoc::Markup::PreProcess
 
-  @registered = {}
+  ##
+  # An RDoc::Options instance that will be filled in with overrides from
+  # directives
+
+  attr_accessor :options
+
+  ##
+  # Adds a post-process handler for directives.  The handler will be called
+  # with the result RDoc::Comment (or text String) and the code object for the
+  # comment (if any).
+
+  def self.post_process &block
+    @post_processors << block
+  end
+
+  ##
+  # Registered post-processors
+
+  def self.post_processors
+    @post_processors
+  end
 
   ##
   # Registers +directive+ as one handled by RDoc.  If a block is given the
   # directive will be replaced by the result of the block, otherwise the
   # directive will be removed from the processed text.
+  #
+  # The block will be called with the directive name and the directive
+  # parameter:
+  #
+  #   RDoc::Markup::PreProcess.register 'my-directive' do |directive, param|
+  #     # replace text, etc.
+  #   end
 
   def self.register directive, &block
     @registered[directive] = block
@@ -31,6 +61,16 @@ class RDoc::Markup::PreProcess
     @registered
   end
 
+  ##
+  # Clears all registered directives and post-processors
+
+  def self.reset
+    @post_processors = []
+    @registered = {}
+  end
+
+  reset
+
   ##
   # Creates a new pre-processor for +input_file_name+ that will look for
   # included files in +include_path+
@@ -38,10 +78,11 @@ class RDoc::Markup::PreProcess
   def initialize(input_file_name, include_path)
     @input_file_name = input_file_name
     @include_path = include_path
+    @options = nil
   end
 
   ##
-  # Look for directives in a chunk of +text+.
+  # Look for directives in the given +text+.
   #
   # Options that we don't handle are yielded.  If the block returns false the
   # directive is restored to the text.  If the block returns nil or no block
@@ -51,52 +92,156 @@ class RDoc::Markup::PreProcess
   # If no matching directive was registered the directive is restored to the
   # text.
   #
-  # If +code_object+ is given and the param is set as metadata on the
-  # +code_object+.  See RDoc::CodeObject#metadata
+  # If +code_object+ is given and the directive is unknown then the
+  # directive's parameter is set as metadata on the +code_object+.  See
+  # RDoc::CodeObject#metadata for details.
+
+  def handle text, code_object = nil, &block
+    if RDoc::Comment === text then
+      comment = text
+      text = text.text
+    end
 
-  def handle text, code_object = nil
     # regexp helper (square brackets for optional)
     # $1      $2  $3        $4      $5
     # [prefix][\]:directive:[spaces][param]newline
-    text.gsub!(/^([ \t]*#?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?\n/) do
+    text = text.gsub(/^([ \t]*(?:#|\/?\*)?[ \t]*)(\\?):(\w+):([ \t]*)(.+)?(\r?\n|$)/) do
       # skip something like ':toto::'
       next $& if $4.empty? and $5 and $5[0, 1] == ':'
 
       # skip if escaped
       next "#$1:#$3:#$4#$5\n" unless $2.empty?
 
-      prefix    = $1
-      directive = $3.downcase
-      param     = $5
-
-      case directive
-      when 'include' then
-        filename = param.split[0]
-        encoding = if defined?(Encoding) then text.encoding else nil end
-        include_file filename, prefix, encoding
-      else
-        result = yield directive, param if block_given?
-
-        case result
-        when nil then
-          code_object.metadata[directive] = param if code_object
-          if RDoc::Markup::PreProcess.registered.include? directive then
-            handler = RDoc::Markup::PreProcess.registered[directive]
-            result = handler.call directive, param if handler
-          else
-            result = "#{prefix}:#{directive}: #{param}\n"
-          end
-        when false then
-          result = "#{prefix}:#{directive}: #{param}\n"
-        end
-
-        result
+      # This is not in handle_directive because I didn't want to pass another
+      # argument into it
+      if comment and $3 == 'markup' then
+        next "#{$1.strip}\n" unless $5
+        comment.format = $5.downcase
+        next "#{$1.strip}\n"
       end
+
+      handle_directive $1, $3, $5, code_object, text.encoding, &block
+    end
+
+    if comment then
+      comment.text = text
+    else
+      comment = text
+    end
+
+    self.class.post_processors.each do |handler|
+      handler.call comment, code_object
     end
 
     text
   end
 
+  ##
+  # Performs the actions described by +directive+ and its parameter +param+.
+  #
+  # +code_object+ is used for directives that operate on a class or module.
+  # +prefix+ is used to ensure the replacement for handled directives is
+  # correct.  +encoding+ is used for the <tt>include</tt> directive.
+  #
+  # For a list of directives in RDoc see RDoc::Markup.
+  #--
+  # When 1.8.7 support is ditched prefix can be defaulted to ''
+
+  def handle_directive prefix, directive, param, code_object = nil,
+                       encoding = nil
+    blankline = "#{prefix.strip}\n"
+    directive = directive.downcase
+
+    case directive
+    when 'arg', 'args' then
+      return "#{prefix}:#{directive}: #{param}\n" unless code_object && code_object.kind_of?(RDoc::AnyMethod)
+
+      code_object.params = param
+
+      blankline
+    when 'category' then
+      if RDoc::Context === code_object then
+        section = code_object.add_section param
+        code_object.temporary_section = section
+      end
+
+      blankline # ignore category if we're not on an RDoc::Context
+    when 'doc' then
+      return blankline unless code_object
+      code_object.document_self = true
+      code_object.force_documentation = true
+
+      blankline
+    when 'enddoc' then
+      return blankline unless code_object
+      code_object.done_documenting = true
+
+      blankline
+    when 'include' then
+      filename = param.split(' ', 2).first
+      include_file filename, prefix, encoding
+    when 'main' then
+      @options.main_page = param if @options.respond_to? :main_page
+
+      blankline
+    when 'nodoc' then
+      return blankline unless code_object
+      code_object.document_self = nil # notify nodoc
+      code_object.document_children = param !~ /all/i
+
+      blankline
+    when 'notnew', 'not_new', 'not-new' then
+      return blankline unless RDoc::AnyMethod === code_object
+
+      code_object.dont_rename_initialize = true
+
+      blankline
+    when 'startdoc' then
+      return blankline unless code_object
+
+      code_object.start_doc
+      code_object.force_documentation = true
+
+      blankline
+    when 'stopdoc' then
+      return blankline unless code_object
+
+      code_object.stop_doc
+
+      blankline
+    when 'title' then
+      @options.default_title = param if @options.respond_to? :default_title=
+
+      blankline
+    when 'yield', 'yields' then
+      return blankline unless code_object
+      # remove parameter &block
+      code_object.params = code_object.params.sub(/,?\s*&\w+/, '') if code_object.params
+
+      code_object.block_params = param
+
+      blankline
+    else
+      result = yield directive, param if block_given?
+
+      case result
+      when nil then
+        code_object.metadata[directive] = param if code_object
+
+        if RDoc::Markup::PreProcess.registered.include? directive then
+          handler = RDoc::Markup::PreProcess.registered[directive]
+          result = handler.call directive, param if handler
+        else
+          result = "#{prefix}:#{directive}: #{param}\n"
+        end
+      when false then
+        result = "#{prefix}:#{directive}: #{param}\n"
+      end
+
+      result
+    end
+  end
+
   ##
   # Handles the <tt>:include: _filename_</tt> directive.
   #
@@ -120,7 +265,8 @@ class RDoc::Markup::PreProcess
       return ''
     end
 
-    content = RDoc::Encoding.read_file full_name, encoding
+    content = RDoc::Encoding.read_file full_name, encoding, true
+    content = RDoc::Encoding.remove_magic_comment content
 
     # strip magic comment
     content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
@@ -148,4 +294,3 @@ class RDoc::Markup::PreProcess
   end
 
 end
-

data/lib/rdoc/markup/raw.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A section of text that is added to the output document as-is
 
@@ -13,7 +14,7 @@ class RDoc::Markup::Raw
 
   def initialize *parts
     @parts = []
-    @parts.push(*parts)
+    @parts.concat parts
   end
 
   ##
@@ -24,7 +25,7 @@ class RDoc::Markup::Raw
   end
 
   def == other # :nodoc:
-    self.class == other.class and text == other.text
+    self.class == other.class and @parts == other.parts
   end
 
   ##
@@ -38,11 +39,11 @@ class RDoc::Markup::Raw
   # Appends +other+'s parts
 
   def merge other
-    @parts.push(*other.parts)
+    @parts.concat other.parts
   end
 
   def pretty_print q # :nodoc:
-    self.class.name =~ /.*::(\w{4})/i
+    self.class.name =~ /.*::(\w{1,4})/i
 
     q.group 2, "[#{$1.downcase}: ", ']' do
       q.seplist @parts do |part|
@@ -55,7 +56,7 @@ class RDoc::Markup::Raw
   # Appends +texts+ onto this Paragraph
 
   def push *texts
-    self.parts.push(*texts)
+    self.parts.concat texts
   end
 
   ##

data/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
+

data/lib/rdoc/markup/rule.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 ##
 # A horizontal rule with a weight
 

data/lib/rdoc/markup/table.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+##
+# A section of table
+
+class RDoc::Markup::Table
+  attr_accessor :header, :align, :body
+
+  def initialize header, align, body
+    @header, @align, @body = header, align, body
+  end
+
+  def == other
+    self.class == other.class and
+      @header == other.header and
+      @align == other.align and
+      @body == other.body
+  end
+
+  def accept visitor
+    visitor.accept_table @header, @body, @align
+  end
+
+  def pretty_print q # :nodoc:
+    q.group 2, '[Table: ', ']' do
+      q.group 2, '[Head: ', ']' do
+        q.seplist @header.zip(@align) do |text, align|
+          q.pp text
+          if align
+            q.text ":"
+            q.breakable
+            q.text align.to_s
+          end
+        end
+      end
+      q.breakable
+      q.group 2, '[Body: ', ']' do
+        q.seplist @body do |body|
+          q.group 2, '[', ']' do
+            q.seplist body do |text|
+              q.pp text
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rdoc/markup/to_ansi.rb

@@ -1,5 +1,4 @@
-require 'rdoc/markup/to_rdoc'
-
+# frozen_string_literal: true
 ##
 # Outputs RDoc markup with vibrant ANSI color!
 
@@ -8,13 +7,13 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
   ##
   # Creates a new ToAnsi visitor that is ready to output vibrant ANSI color!
 
-  def initialize
+  def initialize markup = nil
     super
 
     @headings.clear
-    @headings[1] = ["\e[1;32m", "\e[m"]
-    @headings[2] = ["\e[4;32m", "\e[m"]
-    @headings[3] = ["\e[32m",   "\e[m"]
+    @headings[1] = ["\e[1;32m", "\e[m"] # bold
+    @headings[2] = ["\e[4;32m", "\e[m"] # underline
+    @headings[3] = ["\e[32m",   "\e[m"] # just green
   end
 
   ##
@@ -34,6 +33,11 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
             when :BULLET then
               2
             when :NOTE, :LABEL then
+              if @prefix then
+                @res << @prefix.strip
+                @prefix = nil
+              end
+
               @res << "\n" unless res.length == 1
               2
             else
@@ -53,7 +57,13 @@ class RDoc::Markup::ToAnsi < RDoc::Markup::ToRdoc
              when :BULLET then
                '*'
              when :NOTE, :LABEL then
-               attributes(list_item.label) + ":\n"
+               labels = Array(list_item.label).map do |label|
+                 attributes(label).strip
+               end.join "\n"
+
+               labels << ":\n" unless labels.empty?
+
+               labels
              else
                @list_index.last.to_s + '.'
              end

data/lib/rdoc/markup/to_bs.rb

@@ -1,5 +1,4 @@
-require 'rdoc/markup/to_rdoc'
-
+# frozen_string_literal: true
 ##
 # Outputs RDoc markup with hot backspace action!  You will probably need a
 # pager to use this output format.
@@ -11,7 +10,7 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   ##
   # Returns a new ToBs that is ready for hot backspace action!
 
-  def initialize
+  def initialize markup = nil
     super
 
     @in_b  = false
@@ -42,7 +41,7 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   end
 
   ##
-  # Turns on or off special handling for +convert_string+
+  # Turns on or off regexp handling for +convert_string+
 
   def annotate tag
     case tag
@@ -55,9 +54,9 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   end
 
   ##
-  # Calls convert_string on the result of convert_special
+  # Calls convert_string on the result of convert_regexp_handling
 
-  def convert_special special
+  def convert_regexp_handling target
     convert_string super
   end
 
@@ -65,7 +64,6 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   # Adds bold or underline mixed with backspaces
 
   def convert_string string
-    return string unless string.respond_to? :chars # your ruby is lame
     return string unless @in_b or @in_em
     chars = if @in_b then
               string.chars.map do |char| "#{char}\b#{char}" end
@@ -77,4 +75,3 @@ class RDoc::Markup::ToBs < RDoc::Markup::ToRdoc
   end
 
 end
-