Convert RDoc to OptionParser, clean up -h output, namespace Options under RDoc.

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

ChangeLog

@@ -1,3 +1,9 @@
+Mon Jan  7 15:51:35 2008  Eric Hodel  <drbrain@segment7.net>
+
+	* lib/rdoc/options.rb:  Convert to OptionParser, clean up -h output,
+	namespace under RDoc.
+	* lib/rdoc/*:  Namespace RDoc::Options.
+
 Mon Jan  7 15:42:46 2008  NAKAMURA Usaku  <usa@ruby-lang.org>
 
 	* common.mk, Makefile.in, */Makefile.sub (distclean-local): move

bin/rdoc

@@ -21,7 +21,7 @@
 #  search path if necessary.
 
 def adjust_for_existing_rdoc(path)
-  
+
   $stderr.puts %{
   It seems as if you have a previously-installed RDoc in
   the directory #{path}.
@@ -44,7 +44,7 @@ def adjust_for_existing_rdoc(path)
 end
 
 $:.each do |path|
-  if /site_ruby/ =~ path 
+  if /site_ruby/ =~ path
     rdoc_path = File.join(path, 'rdoc', 'rdoc.rb')
     if File.exist?(rdoc_path)
       adjust_for_existing_rdoc(path)
@@ -60,8 +60,8 @@ require 'rdoc/rdoc'
 
 begin
   r = RDoc::RDoc.new
-  r.document(ARGV)
+  r.document ARGV
-rescue RDoc::RDocError => e
+rescue RDoc::Error => e
   $stderr.puts e.message
-  exit(1)
+  exit 1
 end

lib/rdoc/diagram.rb

@@ -4,11 +4,11 @@
 # You must have the V1.7 or later in your path
 # http://www.research.att.com/sw/tools/graphviz/
 
-require "rdoc/dot"
+require 'rdoc/dot'
-require 'rdoc/options'
 
 module RDoc
 
+  ##
   # Draw a set of diagrams representing the modules and classes in the
   # system. We draw one diagram for each file, and one for each toplevel
   # class or module. This means there will be overlap. However, it also
@@ -167,7 +167,7 @@ module RDoc
 
     def add_classes(container, graph, file = nil )
 
-      use_fileboxes = Options.instance.fileboxes
+      use_fileboxes = @options.fileboxes
 
       files = {}
 
@@ -281,7 +281,7 @@ module RDoc
     def convert_to_png(file_base, graph)
       str = graph.to_s
       return @diagram_cache[str] if @diagram_cache[str]
-      op_type = Options.instance.image_format
+      op_type = @options.image_format
       dotfile = File.join(DOT_PATH, file_base)
       src = dotfile + ".dot"
       dot = dotfile + "." + op_type
@@ -332,4 +332,6 @@ module RDoc
       return res
     end
   end
+
 end
+

lib/rdoc/generators.rb

@@ -3,6 +3,7 @@ require 'rdoc/options'
 require 'rdoc/markup/simple_markup'
 require 'rdoc/template'
 
-module Generators
+module RDoc; end # HACK
-end
+
+module RDoc::Generators; end
 

lib/rdoc/generators/chm_generator.rb

@@ -1,6 +1,6 @@
 require 'rdoc/generators/html_generator'
 
-class Generators::CHMGenerator < Generators::HTMLGenerator
+class RDoc::Generators::CHMGenerator < RDoc::Generators::HTMLGenerator
 
   HHC_PATH = "c:/Program Files/HTML Help Workshop/hhc.exe"
 

lib/rdoc/generators/html_generator.rb

@@ -3,7 +3,7 @@ require 'fileutils'
 require 'rdoc/generators'
 require 'rdoc/markup/simple_markup/to_html'
 
-module Generators
+module RDoc::Generators
 
   ##
   # Name of sub-direcory that holds file descriptions
@@ -59,13 +59,16 @@ module Generators
     ##
     # We need to record the html path of our caller so we can generate
     # correct relative paths for any hyperlinks that we find
-    def initialize(from_path, context)
+    def initialize(from_path, context, options)
       super()
+
       @from_path = from_path
 
       @parent_name = context.parent_name
       @parent_name += "::" if @parent_name
       @context = context
+
+      @options = options
     end
 
     ##
@@ -80,7 +83,7 @@ module Generators
       name = special.text
       if name[0,1] == '#'
         lookup = name[1..-1]
-        name = lookup unless Options.instance.show_hash
+        name = lookup unless @options.show_hash
       else
         lookup = name
       end
@@ -201,7 +204,7 @@ module Generators
 
       end
       unless defined? @html_formatter
-        @html_formatter = HyperlinkHtml.new(self.path, self)
+        @html_formatter = HyperlinkHtml.new(self.path, self, @options)
       end
 
       # Convert leading comment markers to spaces, but only
@@ -615,9 +618,9 @@ module Generators
 
     def write_on(f)
       value_hash
-      template = TemplatePage.new(RDoc::Page::BODY,
+      template = RDoc::TemplatePage.new(RDoc::Page::BODY,
-                                      RDoc::Page::CLASS_PAGE,
+                                        RDoc::Page::CLASS_PAGE,
-                                      RDoc::Page::METHOD_LIST)
+                                        RDoc::Page::METHOD_LIST)
       template.write_html_on(f, @values)
     end
 
@@ -847,9 +850,9 @@ module Generators
 
     def write_on(f)
       value_hash
-      template = TemplatePage.new(RDoc::Page::BODY,
+      template = RDoc::TemplatePage.new(RDoc::Page::BODY,
-                                  RDoc::Page::FILE_PAGE,
+                                        RDoc::Page::FILE_PAGE,
-                                  RDoc::Page::METHOD_LIST)
+                                        RDoc::Page::METHOD_LIST)
       template.write_html_on(f, @values)
     end
 
@@ -878,8 +881,6 @@ module Generators
 
   end
 
-  ##
-
   class HtmlMethod
 
     include MarkUp
@@ -1014,7 +1015,7 @@ module Generators
       FileUtils.mkdir_p(meth_path)
       file_path = File.join(meth_path, @seq) + ".html"
 
-      template = TemplatePage.new(RDoc::Page::SRC_PAGE)
+      template = RDoc::TemplatePage.new(RDoc::Page::SRC_PAGE)
       File.open(file_path, "w") do |f|
         values = {
           'title'     => CGI.escapeHTML(index_name),
@@ -1069,7 +1070,7 @@ module Generators
         end
       end
 
-      add_line_numbers(src) if Options.instance.include_line_numbers
+      add_line_numbers(src) if @options.include_line_numbers
       src
     end
 
@@ -1239,7 +1240,7 @@ module Generators
     # Write out the style sheet used by the main frames
 
     def write_style_sheet
-      template = TemplatePage.new(RDoc::Page::STYLE)
+      template = RDoc::TemplatePage.new(RDoc::Page::STYLE)
       unless @options.css
         File.open(CSS_NAME, "w") do |f|
           values = { "fonts" => RDoc::Page::FONTS }
@@ -1333,7 +1334,7 @@ module Generators
     end
 
     def gen_an_index(collection, title, template, filename)
-      template = TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
+      template = RDoc::TemplatePage.new(RDoc::Page::FR_INDEX_BODY, template)
       res = []
       collection.sort.each do |f|
         if f.document_self
@@ -1361,7 +1362,7 @@ module Generators
     # line.
 
     def gen_main_index
-      template = TemplatePage.new(RDoc::Page::INDEX)
+      template = RDoc::TemplatePage.new(RDoc::Page::INDEX)
       File.open("index.html", "w") do |f|
         values = {
           "initial_page" => main_url,
@@ -1473,7 +1474,7 @@ module Generators
       # this method is defined in the template file
       write_extra_pages if defined? write_extra_pages
 
-      template = TemplatePage.new(RDoc::Page::ONE_PAGE)
+      template = RDoc::TemplatePage.new(RDoc::Page::ONE_PAGE)
 
       if @options.op_name
         opfile = File.open(@options.op_name, "w")

lib/rdoc/generators/ri_generator.rb

@@ -6,7 +6,7 @@ require 'rdoc/ri/ri_reader'
 require 'rdoc/ri/ri_writer'
 require 'rdoc/ri/ri_descriptions'
 
-class Generators::RIGenerator
+class RDoc::Generators::RIGenerator
 
   ##
   # Generators may need to return specific subclasses depending on the

lib/rdoc/generators/xml_generator.rb

@@ -3,7 +3,7 @@ require 'rdoc/generators/html_generator'
 ##
 # Generate XML output as one big file
 
-class Generators::XMLGenerator < Generators::HTMLGenerator
+class RDoc::Generators::XMLGenerator < RDoc::Generators::HTMLGenerator
 
   ##
   # Standard generator factory
@@ -42,16 +42,16 @@ class Generators::XMLGenerator < Generators::HTMLGenerator
 
   def build_indices
     @info.each do |toplevel|
-      @files << Generators::HtmlFile.new(toplevel, @options, Generators::FILE_DIR)
+      @files << RDoc::Generators::HtmlFile.new(toplevel, @options, RDoc::Generators::FILE_DIR)
     end
 
     RDoc::TopLevel.all_classes_and_modules.each do |cls|
-      build_class_list(cls, @files[0], Generators::CLASS_DIR)
+      build_class_list(cls, @files[0], RDoc::Generators::CLASS_DIR)
     end
   end
 
   def build_class_list(from, html_file, class_dir)
-    @classes << Generators::HtmlClass.new(from, html_file, class_dir, @options)
+    @classes << RDoc::Generators::HtmlClass.new(from, html_file, class_dir, @options)
     from.each_classmodule do |mod|
       build_class_list(mod, html_file, class_dir)
     end
@@ -71,7 +71,7 @@ class Generators::XMLGenerator < Generators::HTMLGenerator
     # this method is defined in the template file
     write_extra_pages if defined? write_extra_pages
 
-    template = TemplatePage.new(RDoc::Page::ONE_PAGE)
+    template = RDoc::TemplatePage.new(RDoc::Page::ONE_PAGE)
 
     if @options.op_name
       opfile = File.open(@options.op_name, "w")
@@ -98,7 +98,7 @@ class Generators::XMLGenerator < Generators::HTMLGenerator
   end
 
   def gen_method_index
-    gen_an_index(Generators::HtmlMethod.all_methods, 'Methods')
+    gen_an_index(RDoc::Generators::HtmlMethod.all_methods, 'Methods')
   end
 
   def gen_an_index(collection, title)

lib/rdoc/parsers/parse_c.rb

@@ -3,7 +3,6 @@
 
 require "rdoc/code_objects"
 require "rdoc/parsers/parserfactory"
-require "rdoc/options"
 require "rdoc/rdoc"
 
 module RDoc
@@ -37,6 +36,7 @@ module RDoc
     "rb_cTime"             => "Time",
     "rb_cTrueClass"        => "TrueClass",
     "rb_cStruct"           => "Struct",
+    "rb_cVM"               => "VM",
     "rb_eException"        => "Exception",
     "rb_eStandardError"    => "StandardError",
     "rb_eSystemExit"       => "SystemExit",
@@ -177,13 +177,13 @@ module RDoc
     # prepare to parse a C file
     def initialize(top_level, file_name, body, options, stats)
       @known_classes = KNOWN_CLASSES.dup
-      @body = handle_tab_width(handle_ifdefs_in(body))
       @options = options
+      @body = handle_tab_width(handle_ifdefs_in(body))
       @stats   = stats
       @top_level = top_level
       @classes = Hash.new
       @file_dir = File.dirname(file_name)
-      @progress = $stderr unless options.quiet
+      @progress = $stderr unless @options.quiet
     end
 
     # Extract the classes/modules and methods from a C file
@@ -627,8 +627,8 @@ module RDoc
     # Find the C code corresponding to a Ruby method
     def find_body(meth_name, meth_obj, body, quiet = false)
       case body
-      when %r{((?>/\*.*?\*/\s*))(?:static\s+)?VALUE\s+#{meth_name}
+      when %r"((?>/\*.*?\*/\s*))(?:static\s+)?VALUE\s+#{meth_name}
-              \s*(\([^)]*\))\s*\{.*?^\}}xm
+              \s*(\([^)]*\))\s*\{.*?^\}"xm
         comment, params = $1, $2
         body_text = $&
 
@@ -752,7 +752,7 @@ module RDoc
 
     def handle_tab_width(body)
       if /\t/ =~ body
-        tab_width = Options.instance.tab_width
+        tab_width = @options.tab_width
         body.split(/\n/).map do |line|
           1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
           line

lib/rdoc/parsers/parse_rb.rb

@@ -305,8 +305,6 @@ module RubyToken
 
 end
 
-
-
 # Lexical analyzer for Ruby source
 
 class RubyLex
@@ -345,9 +343,11 @@ class RubyLex
     
     attr_reader :line_num
     
-    def initialize(content)
+    def initialize(content, options)
+      @options = options
+      
       if /\t/ =~ content
-        tab_width = Options.instance.tab_width
+        tab_width = @options.tab_width
         content = content.split(/\n/).map do |line|
           1 while line.gsub!(/\t+/) { ' ' * (tab_width*$&.length - $`.length % tab_width)}  && $~ #`
           line
@@ -444,10 +444,12 @@ class RubyLex
     false
   end
 
-  def initialize(content)
+  def initialize(content, options)
     lex_init
 
-    @reader = BufferedReader.new(content)
+    @options = options
+
+    @reader = BufferedReader.new content, @options
 
     @exp_line_no = @line_no = 1
     @base_char_no = 0
@@ -1353,10 +1355,9 @@ class RubyLex
   end
 end
 
-
+##
-
+# Extract code elements from a source file, returning a TopLevel object
-# Extract code elements from a source file, returning a TopLevel
+# containing the constituent file elements.
-# object containing the constituent file elements.
 #
 # This file is based on rtags
 
@@ -1389,7 +1390,7 @@ module RDoc
       @size = 0
       @token_listeners = nil
       @input_file_name = file_name
-      @scanner = RubyLex.new(content)
+      @scanner = RubyLex.new content, @options
       @scanner.exception_on_syntax_error = false
       @top_level = top_level
       @progress = $stderr unless options.quiet
@@ -2325,13 +2326,11 @@ module RDoc
           throw :enddoc
 
         when "main"
-          options = Options.instance
+          @options.main_page = param
-          options.main_page = param
+          ""
-	  ""
 
         when "title"
-          options = Options.instance
+          @options.title = param
-          options.title = param
           ""
 
         when "section"
@@ -2605,3 +2604,4 @@ module RDoc
   end
 
 end
+

lib/rdoc/rdoc.rb

@@ -1,15 +1,8 @@
-# See README.
-#
- 
-
-VERSION_STRING = %{RDoc V1.0.1 - 20041108}
-
-
 require 'rdoc/parsers/parse_rb.rb'
 require 'rdoc/parsers/parse_c.rb'
 require 'rdoc/parsers/parse_f95.rb'
-
 require 'rdoc/parsers/parse_simple.rb'
+
 require 'rdoc/options'
 
 require 'rdoc/diagram'
@@ -18,19 +11,25 @@ require 'find'
 require 'fileutils'
 require 'time'
 
-# We put rdoc stuff in the RDoc module to avoid namespace clutter.
+##
-#
-# ToDo: This isn't universally true.
-#
 # :include: README
 
 module RDoc
 
-  # Name of the dotfile that contains the description of files to be
+  ##
-  # processed in the current directory
+  # RDoc version you are using
+
+  VERSION = "2.0.0"
+
+  ##
+  # Name of the dotfile that contains the description of files to be processed
+  # in the current directory
+
   DOT_DOC_FILENAME = ".document"
 
+  ##
   # Simple stats collector
+
   class Stats
     attr_accessor :num_files, :num_classes, :num_modules, :num_methods
     def initialize
@@ -46,13 +45,14 @@ module RDoc
     end
   end
 
+  ##
+  # Exception thrown by any rdoc error.
 
-  # Exception thrown by any rdoc error. Only the #message part is
+  class Error < StandardError; end
-  # of use externally.
 
-  class RDocError < Exception
+  RDocError = Error # :nodoc:
-  end
 
+  ##
   # Encapsulate the production of rdoc documentation. Basically
   # you can use this as you would invoke rdoc from the command
   # line:
@@ -61,24 +61,25 @@ module RDoc
   #    rdoc.document(args)
   #
   # where _args_ is an array of strings, each corresponding to
-  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb 
+  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb
   # for details.
-  
+
   class RDoc
 
+    Generator = Struct.new(:file_name, :class_name, :key)
+
     ##
     # This is the list of output generators that we
     # support
-    
+
-    Generator = Struct.new(:file_name, :class_name, :key)
-    
     GENERATORS = {}
-    $:.collect {|d|
+
-      File::expand_path(d)
+    $LOAD_PATH.collect do |d|
-    }.find_all {|d|
+      File.expand_path d
-      File::directory?("#{d}/rdoc/generators")
+    end.find_all do |d|
-    }.each {|dir|
+      File.directory? "#{d}/rdoc/generators"
-      Dir::entries("#{dir}/rdoc/generators").each {|gen|
+    end.each do |dir|
+      Dir.entries("#{dir}/rdoc/generators").each do |gen|
         next unless /(\w+)_generator.rb$/ =~ gen
         type = $1
         unless GENERATORS.has_key? type
@@ -86,31 +87,28 @@ module RDoc
                                            "#{type.upcase}Generator".intern,
                                            type)
         end
-      }
+      end
-    }                                                    
+    end
 
-    #######
     private
-    #######
 
     ##
     # Report an error message and exit
-    
+
     def error(msg)
-      raise RDocError.new(msg)
+      raise RDoc::Error, msg
     end
-    
+
     ##
-    # Create an output dir if it doesn't exist. If it does
+    # Create an output dir if it doesn't exist. If it does exist, but doesn't
-    # exist, but doesn't contain the flag file <tt>created.rid</tt>
+    # contain the flag file <tt>created.rid</tt> then we refuse to use it, as
-    # then we refuse to use it, as we may clobber some
+    # we may clobber some manually generated documentation
-    # manually generated documentation
+
-    
     def setup_output_dir(op_dir, force)
       flag_file = output_flag_file(op_dir)
       if File.exist?(op_dir)
         unless File.directory?(op_dir)
-          error "'#{op_dir}' exists, and is not a directory" 
+          error "'#{op_dir}' exists, and is not a directory"
         end
         begin
           created = File.read(flag_file)
@@ -129,19 +127,25 @@ module RDoc
       last
     end
 
+    ##
     # Update the flag file in an output directory.
+
     def update_output_dir(op_dir, time)
       File.open(output_flag_file(op_dir), "w") {|f| f.puts time.rfc2822 }
     end
 
+    ##
     # Return the path name of the flag file in an output directory.
+
     def output_flag_file(op_dir)
       File.join(op_dir, "created.rid")
     end
 
-    # The .document file contains a list of file and directory name
+    ##
-    # patterns, representing candidates for documentation. It may
+    # The .document file contains a list of file and directory name patterns,
-    # also contain comments (starting with '#')
+    # representing candidates for documentation. It may also contain comments
+    # (starting with '#')
+
     def parse_dot_doc_file(in_dir, filename, options)
       # read and strip comments
       patterns = File.read(filename).gsub(/#.*/, '')
@@ -155,20 +159,20 @@ module RDoc
       result
     end
 
+    ##
+    # Given a list of files and directories, create a list of all the Ruby
+    # files they contain.
+    #
+    # If +force_doc+ is true we always add the given files, if false, only
+    # add files that we guarantee we can parse.  It is true when looking at
+    # files given on the command line, false when recursing through
+    # subdirectories.
+    #
+    # The effect of this is that if you want a file with a non-standard
+    # extension parsed, you must name it explicity.
 
-    # Given a list of files and directories, create a list
+    def normalized_file_list(options, relative_files, force_doc = false,
-    # of all the Ruby files they contain. 
+                             exclude_pattern = nil)
-    #
-    # If +force_doc+ is true, we always add the given files.
-    # If false, only add files that we guarantee we can parse
-    # It is true when looking at files given on the command line,
-    # false when recursing through subdirectories. 
-    #
-    # The effect of this is that if you want a file with a non-
-    # standard extension parsed, you must name it explicity.
-    #
-
-    def normalized_file_list(options, relative_files, force_doc = false, exclude_pattern=nil)
       file_list = []
 
       relative_files.each do |rel_file_name|
@@ -187,27 +191,27 @@ module RDoc
             file_list.concat(list_files_in_directory(rel_file_name, options))
           end
         else
-          raise RDocError.new("I can't deal with a #{type} #{rel_file_name}")
+          raise RDoc::Error, "I can't deal with a #{type} #{rel_file_name}"
         end
       end
+
       file_list
     end
 
-    # Return a list of the files to be processed in
+    ##
-    # a directory. We know that this directory doesn't have
+    # Return a list of the files to be processed in a directory. We know that
-    # a .document file, so we're looking for real files. However
+    # this directory doesn't have a .document file, so we're looking for real
-    # we may well contain subdirectories which must
+    # files. However we may well contain subdirectories which must be tested
-    # be tested for .document files
+    # for .document files.
+
     def list_files_in_directory(dir, options)
       normalized_file_list(options, Dir.glob(File.join(dir, "*")), false, options.exclude)
     end
 
-
+    ##
-    # Parse each file on the command line, recursively entering
+    # Parse each file on the command line, recursively entering directories.
-    # directories
 
     def parse_files(options)
- 
       file_info = []
 
       files = options.files
@@ -217,7 +221,7 @@ module RDoc
 
       file_list.each do |fn|
         $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet
-        
+
         content = File.open(fn, "r:ascii-8bit") {|f| f.read}
         if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
           if enc = Encoding.find($1)
@@ -234,32 +238,30 @@ module RDoc
       file_info
     end
 
-
     public
 
-    ###################################################################
+    ##
-    #
     # Format up one or more files according to the given arguments.
-    # For simplicity, _argv_ is an array of strings, equivalent to the
-    # strings that would be passed on the command line. (This isn't a
-    # coincidence, as we _do_ pass in ARGV when running
-    # interactively). For a list of options, see rdoc/rdoc.rb. By
-    # default, output will be stored in a directory called +doc+ below
-    # the current directory, so make sure you're somewhere writable
-    # before invoking.
     #
-    # Throws: RDocError on error
+    # For simplicity, _argv_ is an array of strings, equivalent to the strings
+    # that would be passed on the command line. (This isn't a coincidence, as
+    # we _do_ pass in ARGV when running interactively). For a list of options,
+    # see rdoc/rdoc.rb. By default, output will be stored in a directory
+    # called +doc+ below the current directory, so make sure you're somewhere
+    # writable before invoking.
+    #
+    # Throws: RDoc::Error on error
 
     def document(argv)
-
       TopLevel::reset
 
       @stats = Stats.new
 
-      options = Options.instance
+      options = Options.new GENERATORS
-      options.parse(argv, GENERATORS)
+      options.parse argv
 
       @last_created = nil
+
       unless options.all_one_file
         @last_created = setup_output_dir(options.op_dir, options.force_update)
       end
@@ -298,5 +300,6 @@ module RDoc
       end
     end
   end
+
 end
 

lib/rdoc/template.rb

@@ -35,7 +35,7 @@
 #
 #
 
-class TemplatePage
+class RDoc::TemplatePage
 
   ##########
   # A context holds a stack of key/value pairs (like a symbol