Import RDoc 2.5.7. Fixes #1318 and ruby-core:29780

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@27509 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,7 @@
+Tue Apr 27 12:44:23 2010  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/rdoc: Import RDoc 2.5.7.  Fixes #1318 and ruby-core:29780.
+
 Tue Apr 27 10:54:14 2010  Nobuyoshi Nakada  <nobu@ruby-lang.org>
 
 	* parse.y (parser_read_escape): deny extra character escapes.

NEWS

@@ -211,7 +211,7 @@ with all sufficient information, see the ChangeLog file.
 
 * RDoc
 
-  * Updated to RDoc 2.5.6
+  * Updated to RDoc 2.5.7
 
 * logger
 

lib/rdoc.rb

@@ -383,7 +383,7 @@ module RDoc
   ##
   # RDoc version you are using
 
-  VERSION = '2.5.6'
+  VERSION = '2.5.7'
 
   ##
   # Name of the dotfile that contains the description of files to be processed

lib/rdoc/known_classes.rb

@@ -5,6 +5,7 @@ module RDoc
 
   KNOWN_CLASSES = {
     "rb_cArray"            => "Array",
+    "rb_cBasicObject"      => "BasicObject",
     "rb_cBignum"           => "Bignum",
     "rb_cClass"            => "Class",
     "rb_cData"             => "Data",

lib/rdoc/markup.rb

@@ -107,15 +107,13 @@ class RDoc::Markup
   end
 
   ##
-  # We take a string, split it into lines, work out the type of each line,
+  # We take +text+, parse it then invoke the output +formatter+ using a
-  # and from there deduce groups of lines (for example all lines in a
+  # Visitor to render the result.
-  # paragraph).  We then invoke the output formatter using a Visitor to
-  # display the result.
 
-  def convert(str, op)
+  def convert text, formatter
-    document = RDoc::Markup::Parser.parse str
+    document = RDoc::Markup::Parser.parse text
 
-    document.accept op
+    document.accept formatter
   end
 
 end

lib/rdoc/markup/formatter_test_case.rb

@@ -87,6 +87,18 @@ class RDoc::Markup::FormatterTestCase < MiniTest::Unit::TestCase
         accept_verbatim
       end
 
+      def test_accept_raw
+        @to.start_accepting
+
+        @to.accept_raw @RM::Raw.new("<table>",
+                                    "<tr><th>Name<th>Count",
+                                    "<tr><td>a<td>1",
+                                    "<tr><td>b<td>2",
+                                    "</table>")
+
+        accept_raw
+      end
+
       def test_accept_rule
         @to.start_accepting
 

lib/rdoc/markup/paragraph.rb

@@ -1,66 +1,11 @@
 ##
 # A Paragraph of text
 
-class RDoc::Markup::Paragraph
+class RDoc::Markup::Paragraph < RDoc::Markup::Raw
-
-  ##
-  # The component parts of the list
-
-  attr_reader :parts
-
-  ##
-  # Creates a new Paragraph containing +parts+
-
-  def initialize *parts
-    @parts = []
-    @parts.push(*parts)
-  end
-
-  ##
-  # Appends +text+ to the Paragraph
-
-  def << text
-    @parts << text
-  end
-
-  def == other # :nodoc:
-    self.class == other.class and text == other.text
-  end
 
   def accept visitor
     visitor.accept_paragraph self
   end
 
-  ##
-  # Appends +other+'s parts into this Paragraph
-
-  def merge other
-    @parts.push(*other.parts)
-  end
-
-  def pretty_print q # :nodoc:
-    self.class.name =~ /.*::(\w{4})/i
-
-    q.group 2, "[#{$1.downcase}: ", ']' do
-      q.seplist @parts do |part|
-        q.pp part
-      end
-    end
-  end
-
-  ##
-  # Appends +texts+ onto this Paragraph
-
-  def push *texts
-    self.parts.push(*texts)
-  end
-
-  ##
-  # The text of this paragraph
-
-  def text
-    @parts.join ' '
-  end
-
 end
 

lib/rdoc/markup/parser.rb

@@ -522,6 +522,7 @@ require 'rdoc/markup/document'
 require 'rdoc/markup/heading'
 require 'rdoc/markup/list'
 require 'rdoc/markup/list_item'
+require 'rdoc/markup/raw'
 require 'rdoc/markup/paragraph'
 require 'rdoc/markup/rule'
 require 'rdoc/markup/verbatim'

lib/rdoc/markup/preprocess.rb

@@ -4,9 +4,30 @@ require 'rdoc/markup'
 # Handle common directives that can occur in a block of text:
 #
 # : include : filename
+#
+# RDoc plugin authors can register additional directives to be handled through
+# RDoc::Markup::PreProcess::register
 
 class RDoc::Markup::PreProcess
 
+  @registered = {}
+
+  ##
+  # 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.
+
+  def self.register directive, &block
+    @registered[directive] = block
+  end
+
+  ##
+  # Registered directives
+
+  def self.registered
+    @registered
+  end
+
   ##
   # Creates a new pre-processor for +input_file_name+ that will look for
   # included files in +include_path+
@@ -17,10 +38,20 @@ class RDoc::Markup::PreProcess
   end
 
   ##
-  # Look for common options in a chunk of text. Options that we don't handle
+  # Look for directives in a chunk of +text+.
-  # are yielded to the caller.
+  #
+  # 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
+  # was given the directive is handled according to the registered directives.
+  # If a String was returned the directive is replaced with the string.
+  #
+  # 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
 
-  def handle(text)
+  def handle text, code_object = nil
     text.gsub!(/^([ \t]*#?[ \t]*):(\w+):([ \t]*)(.+)?\n/) do
       next $& if $3.empty? and $4 and $4[0, 1] == ':'
 
@@ -34,11 +65,26 @@ class RDoc::Markup::PreProcess
         include_file filename, prefix
 
       else
-        result = yield directive, param
+        result = yield directive, param if block_given?
-        result = "#{prefix}:#{directive}: #{param}\n" unless result
+
+        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
+
+    text
   end
 
   ##
@@ -46,7 +92,11 @@ class RDoc::Markup::PreProcess
 
   def include_file(name, indent)
     if full_name = find_include_file(name) then
-      content = File.binread full_name
+      content = if defined?(Encoding) then
+                  File.binread full_name
+                else
+                  File.read full_name
+                end
       # HACK determine content type and force encoding
       content = content.sub(/\A# .*coding[=:].*$/, '').lstrip
 

lib/rdoc/markup/raw.rb

@@ -0,0 +1,65 @@
+##
+# A section of text that is added to the output document as-is
+
+class RDoc::Markup::Raw
+
+  ##
+  # The component parts of the list
+
+  attr_reader :parts
+
+  ##
+  # Creates a new Raw containing +parts+
+
+  def initialize *parts
+    @parts = []
+    @parts.push(*parts)
+  end
+
+  ##
+  # Appends +text+
+
+  def << text
+    @parts << text
+  end
+
+  def == other # :nodoc:
+    self.class == other.class and text == other.text
+  end
+
+  def accept visitor
+    visitor.accept_raw self
+  end
+
+  ##
+  # Appends +other+'s parts
+
+  def merge other
+    @parts.push(*other.parts)
+  end
+
+  def pretty_print q # :nodoc:
+    self.class.name =~ /.*::(\w{4})/i
+
+    q.group 2, "[#{$1.downcase}: ", ']' do
+      q.seplist @parts do |part|
+        q.pp part
+      end
+    end
+  end
+
+  ##
+  # Appends +texts+ onto this Paragraph
+
+  def push *texts
+    self.parts.push(*texts)
+  end
+
+  ##
+  # The raw text
+
+  def text
+    @parts.join ' '
+  end
+
+end

lib/rdoc/markup/to_html.rb

@@ -227,6 +227,10 @@ class RDoc::Markup::ToHtml < RDoc::Markup::Formatter
     @res << convert_heading(heading.level, @am.flow(heading.text))
   end
 
+  def accept_raw raw
+    @res << raw.parts.join("\n")
+  end
+
   private
 
   ##

lib/rdoc/markup/to_rdoc.rb

@@ -127,6 +127,10 @@ class RDoc::Markup::ToRdoc < RDoc::Markup::Formatter
     wrap attributes(paragraph.text)
   end
 
+  def accept_raw raw
+    @res << raw.parts.join("\n")
+  end
+
   def accept_rule rule
     use_prefix or @res << ' ' * @indent
     @res << '-' * (@width - @indent)

lib/rdoc/markup/verbatim.rb

@@ -1,7 +1,7 @@
 ##
 # A section of verbatim text
 
-class RDoc::Markup::Verbatim < RDoc::Markup::Paragraph
+class RDoc::Markup::Verbatim < RDoc::Markup::Raw
 
   def accept visitor
     visitor.accept_verbatim self

lib/rdoc/options.rb

@@ -366,6 +366,11 @@ Usage: #{opt.program_name} [options] [names...]
       end
     end
 
+    if @pipe and not argv.empty? then
+      @pipe = false
+      ignored << '-p (with files)'
+    end
+
     unless ignored.empty? or quiet then
       $stderr.puts "invalid options: #{ignored.join ', '}"
       $stderr.puts '(invalid options are ignored)'

lib/rdoc/parser/c.rb

@@ -661,7 +661,7 @@ class RDoc::Parser::C < RDoc::Parser
   def look_for_directives_in(context, comment)
     preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
 
-    preprocess.handle comment do |directive, param|
+    preprocess.handle comment, context do |directive, param|
       case directive
       when 'main' then
         @options.main_page = param
@@ -669,9 +669,6 @@ class RDoc::Parser::C < RDoc::Parser
       when 'title' then
         @options.title = param
         ''
-      else
-        context.metadata[directive] = param
-        false
       end
     end
 

lib/rdoc/parser/ruby.rb

@@ -379,7 +379,7 @@ class RDoc::Parser::Ruby < RDoc::Parser
   def look_for_directives_in(context, comment)
     preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
 
-    preprocess.handle comment do |directive, param|
+    preprocess.handle comment, context do |directive, param|
       case directive
       when 'enddoc' then
         throw :enddoc
@@ -403,9 +403,6 @@ class RDoc::Parser::Ruby < RDoc::Parser
       when 'title' then
         @options.title = param
         ''
-      else
-        @top_level.metadata[directive] = param
-        false
       end
     end
 

lib/rdoc/parser/simple.rb

@@ -17,10 +17,7 @@ class RDoc::Parser::Simple < RDoc::Parser
 
     preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
 
-    preprocess.handle @content do |directive, param|
+    preprocess.handle @content, @top_level
-      top_level.metadata[directive] = param
-      false
-    end
   end
 
   ##

test/rdoc/test_rdoc_markup_paragraph.rb

@@ -5,23 +5,5 @@ require 'rdoc/markup'
 
 class TestRDocMarkupParagraph < MiniTest::Unit::TestCase
 
-  def setup
-    @RM = RDoc::Markup
-    @p = @RM::Paragraph.new
-  end
-
-  def mu_pp obj
-    s = ''
-    s = PP.pp obj, s
-    s.force_encoding Encoding.default_external if defined? Encoding
-    s.chomp
-  end
-
-  def test_push
-    @p.push 'hi', 'there'
-
-    assert_equal @RM::Paragraph.new('hi', 'there'), @p
-  end
-
 end
 

test/rdoc/test_rdoc_markup_pre_process.rb

@@ -2,10 +2,13 @@ require 'tempfile'
 require 'rubygems'
 require 'minitest/autorun'
 require 'rdoc/markup/preprocess'
+require 'rdoc/code_objects'
 
 class TestRDocMarkupPreProcess < MiniTest::Unit::TestCase
 
   def setup
+    RDoc::Markup::PreProcess.registered.clear
+
     @tempfile = Tempfile.new 'test_rdoc_markup_pre_process'
     @name = File.basename @tempfile.path
     @dir  = File.dirname @tempfile.path
@@ -38,5 +41,140 @@ contents of a string.
     assert_equal expected, content
   end
 
+  def test_handle
+    text = "# :x: y\n"
+    out = @pp.handle text
+
+    assert_same out, text
+    assert_equal "# :x: y\n", text
+  end
+
+  def test_handle_block
+    text = "# :x: y\n"
+
+    @pp.handle text do |directive, param|
+      false
+    end
+
+    assert_equal "# :x: y\n", text
+
+    @pp.handle text do |directive, param|
+      ''
+    end
+
+    assert_equal "", text
+  end
+
+  def test_handle_code_object
+    cd = RDoc::CodeObject.new
+    text = "# :x: y\n"
+    @pp.handle text, cd
+
+    assert_equal "# :x: y\n", text
+    assert_equal 'y', cd.metadata['x']
+
+    cd.metadata.clear
+    text = "# :x:\n"
+    @pp.handle text, cd
+
+    assert_equal "# :x: \n", text
+    assert_includes cd.metadata, 'x'
+  end
+
+  def test_handle_code_object_block
+    cd = RDoc::CodeObject.new
+    text = "# :x: y\n"
+    @pp.handle text, cd do
+      false
+    end
+
+    assert_equal "# :x: y\n", text
+    assert_empty cd.metadata
+
+    @pp.handle text, cd do
+      nil
+    end
+
+    assert_equal "# :x: y\n", text
+    assert_equal 'y', cd.metadata['x']
+
+    cd.metadata.clear
+
+    @pp.handle text, cd do
+      ''
+    end
+
+    assert_equal '', text
+    assert_empty cd.metadata
+  end
+
+  def test_handle_registered
+    RDoc::Markup::PreProcess.register 'x'
+    text = "# :x: y\n"
+    @pp.handle text
+
+    assert_equal '', text
+
+    text = "# :x: y\n"
+
+    @pp.handle text do |directive, param|
+      false
+    end
+
+    assert_equal "# :x: y\n", text
+
+    text = "# :x: y\n"
+
+    @pp.handle text do |directive, param|
+      ''
+    end
+
+    assert_equal "", text
+  end
+
+  def test_handle_registered_block
+    called = nil
+    RDoc::Markup::PreProcess.register 'x' do |directive, param|
+      called = [directive, param]
+      'blah'
+    end
+
+    text = "# :x: y\n"
+    @pp.handle text
+
+    assert_equal 'blah', text
+    assert_equal %w[x y], called
+  end
+
+  def test_handle_registered_code_object
+    RDoc::Markup::PreProcess.register 'x'
+    cd = RDoc::CodeObject.new
+
+    text = "# :x: y\n"
+    @pp.handle text, cd
+
+    assert_equal '', text
+    assert_equal 'y', cd.metadata['x']
+
+    cd.metadata.clear
+    text = "# :x: y\n"
+
+    @pp.handle text do |directive, param|
+      false
+    end
+
+    assert_equal "# :x: y\n", text
+    assert_empty cd.metadata
+
+    text = "# :x: y\n"
+
+    @pp.handle text do |directive, param|
+      ''
+    end
+
+    assert_equal "", text
+    assert_empty cd.metadata
+  end
+
 end
 

test/rdoc/test_rdoc_markup_raw.rb

@@ -0,0 +1,27 @@
+require 'pp'
+require 'rubygems'
+require 'minitest/autorun'
+require 'rdoc/markup'
+
+class TestRDocMarkupRaw < MiniTest::Unit::TestCase
+
+  def setup
+    @RM = RDoc::Markup
+    @p = @RM::Raw.new
+  end
+
+  def mu_pp obj
+    s = ''
+    s = PP.pp obj, s
+    s.force_encoding Encoding.default_external if defined? Encoding
+    s.chomp
+  end
+
+  def test_push
+    @p.push 'hi', 'there'
+
+    assert_equal @RM::Raw.new('hi', 'there'), @p
+  end
+
+end
+

test/rdoc/test_rdoc_markup_to_ansi.rb

@@ -175,6 +175,18 @@ class TestRDocMarkupToAnsi < RDoc::Markup::FormatterTestCase
     assert_equal "\e[0mhi\n", @to.res.join
   end
 
+  def accept_raw
+    raw = <<-RAW.rstrip
+\e[0m<table>
+<tr><th>Name<th>Count
+<tr><td>a<td>1
+<tr><td>b<td>2
+</table>
+    RAW
+
+    assert_equal raw, @to.res.join
+  end
+
   def accept_rule
     assert_equal "\e[0m#{'-' * 78}\n", @to.res.join
   end

test/rdoc/test_rdoc_markup_to_bs.rb

@@ -174,6 +174,18 @@ class TestRDocMarkupToBs < RDoc::Markup::FormatterTestCase
     assert_equal "hi\n", @to.res.join
   end
 
+  def accept_raw
+    raw = <<-RAW.rstrip
+<table>
+<tr><th>Name<th>Count
+<tr><td>a<td>1
+<tr><td>b<td>2
+</table>
+    RAW
+
+    assert_equal raw, @to.res.join
+  end
+
   def accept_rule
     assert_equal "#{'-' * 78}\n", @to.res.join
   end

test/rdoc/test_rdoc_markup_to_html.rb

@@ -170,6 +170,18 @@ class TestRDocMarkupToHtml < RDoc::Markup::FormatterTestCase
     assert_equal "<p>\nhi\n</p>\n", @to.res.join
   end
 
+  def accept_raw
+    raw = <<-RAW.rstrip
+<table>
+<tr><th>Name<th>Count
+<tr><td>a<td>1
+<tr><td>b<td>2
+</table>
+    RAW
+
+    assert_equal raw, @to.res.join
+  end
+
   def accept_rule
     assert_equal '<hr style="height: 4px"></hr>', @to.res.join
   end

test/rdoc/test_rdoc_markup_to_rdoc.rb

@@ -175,6 +175,18 @@ class TestRDocMarkupToRdoc < RDoc::Markup::FormatterTestCase
     assert_equal "hi\n", @to.res.join
   end
 
+  def accept_raw
+    raw = <<-RAW.rstrip
+<table>
+<tr><th>Name<th>Count
+<tr><td>a<td>1
+<tr><td>b<td>2
+</table>
+    RAW
+
+    assert_equal raw, @to.res.join
+  end
+
   def accept_rule
     assert_equal "#{'-' * 78}\n", @to.res.join
   end

test/rdoc/test_rdoc_options.rb

@@ -50,5 +50,25 @@ class TestRDocOptions < MiniTest::Unit::TestCase
     assert_equal 'MAIN', @options.main_page
   end
 
+  def test_parse_dash_p
+    out, err = capture_io do
+      @options.parse %w[-p]
+    end
+
+    assert @options.pipe
+    refute_match %r%^Usage: %, err
+    refute_match %r%^invalid options%, err
+  end
+
+  def test_parse_dash_p_files
+    out, err = capture_io do
+      @options.parse %w[-p README]
+    end
+
+    refute @options.pipe
+    refute_match %r%^Usage: %, err
+    assert_match %r%^invalid options: -p .with files.%, err
+  end
+
 end
 

test/rdoc/test_rdoc_parser_ruby.rb

@@ -151,16 +151,9 @@ class TestRDocParserRuby < MiniTest::Unit::TestCase
   def test_look_for_directives_in_unhandled
     util_parser ""
 
-    comment = "# :unhandled: \n# :markup: not rdoc\n# :title: hi\n"
+    @parser.look_for_directives_in @top_level, "# :unhandled: blah\n"
 
-    @parser.look_for_directives_in @top_level, comment
+    assert_equal 'blah', @top_level.metadata['unhandled']
-
-    assert_equal "# :unhandled: \n# :markup: not rdoc\n", comment
-
-    assert_equal nil,        @top_level.metadata['unhandled']
-    assert_equal 'not rdoc', @top_level.metadata['markup']
-
-    assert_equal 'hi', @options.title
   end
 
   def test_parse_alias

test/rdoc/test_rdoc_parser_simple.rb

@@ -23,12 +23,11 @@ class TestRDocParserSimple < MiniTest::Unit::TestCase
   end
 
   def test_initialize_metadata
-    parser = util_parser ":unhandled: \n# :markup: not rdoc\n"
+    parser = util_parser ":unhandled: \n"
 
-    assert_equal nil,        @top_level.metadata['unhandled']
+    assert_includes @top_level.metadata, 'unhandled'
-    assert_equal 'not rdoc', @top_level.metadata['markup']
 
-    assert_equal ":unhandled: \n# :markup: not rdoc\n", parser.content
+    assert_equal ":unhandled: \n", parser.content
   end
 
   def test_remove_coding_comment

test/rdoc/test_rdoc_rdoc.rb

@@ -82,50 +82,47 @@ class TestRDocRDoc < MiniTest::Unit::TestCase
   end
 
   def test_setup_output_dir
-    path = @tempfile.path
+    skip "No Dir::mktmpdir, upgrade your ruby" unless Dir.respond_to? :mktmpdir
-    @tempfile.unlink
 
-    last = @rdoc.setup_output_dir path, false
+    Dir.mktmpdir {|d|
+      path = File.join(d, 'testdir')
 
-    assert_empty last
+      last = @rdoc.setup_output_dir path, false
 
-    assert File.directory? path
+      assert_empty last
-  ensure
+
-    FileUtils.rm_f path
+      assert File.directory? path
+    }
   end
 
   def test_setup_output_dir_exists
-    path = @tempfile.path
+    skip "No Dir::mktmpdir, upgrade your ruby" unless Dir.respond_to? :mktmpdir
-    @tempfile.unlink
-    FileUtils.mkdir_p path
 
-    open @rdoc.output_flag_file(path), 'w' do |io|
+    Dir.mktmpdir {|path|
-      io.puts Time.at 0
+      open @rdoc.output_flag_file(path), 'w' do |io|
-      io.puts "./lib/rdoc.rb\t#{Time.at 86400}"
+        io.puts Time.at 0
-    end
+        io.puts "./lib/rdoc.rb\t#{Time.at 86400}"
+      end
 
-    last = @rdoc.setup_output_dir path, false
+      last = @rdoc.setup_output_dir path, false
 
-    assert_equal 1, last.size
+      assert_equal 1, last.size
-    assert_equal Time.at(86400), last['./lib/rdoc.rb']
+      assert_equal Time.at(86400), last['./lib/rdoc.rb']
-  ensure
+    }
-    FileUtils.rm_f path
   end
 
   def test_setup_output_dir_exists_empty_created_rid
-    path = @tempfile.path
+    skip "No Dir::mktmpdir, upgrade your ruby" unless Dir.respond_to? :mktmpdir
-    @tempfile.unlink
-    FileUtils.mkdir_p path
 
-    open @rdoc.output_flag_file(path), 'w' do end
+    Dir.mktmpdir {|path|
+      open @rdoc.output_flag_file(path), 'w' do end
 
-    e = assert_raises RDoc::Error do
+      e = assert_raises RDoc::Error do
-      @rdoc.setup_output_dir path, false
+        @rdoc.setup_output_dir path, false
-    end
+      end
 
-    assert_match %r%Directory #{Regexp.escape path} already exists%, e.message
+      assert_match %r%Directory #{Regexp.escape path} already exists%, e.message
-  ensure
+    }
-    FileUtils.rm_f path
   end
 
   def test_setup_output_dir_exists_file