rdoc 2.0.0

data/lib/rdoc/parsers/parse_simple.rb

@@ -0,0 +1,40 @@
+require 'rdoc'
+require 'rdoc/code_objects'
+require 'rdoc/markup/preprocess'
+
+##
+# Parse a non-source file. We basically take the whole thing as one big
+# comment. If the first character in the file is '#', we strip leading pound
+# signs.
+
+class RDoc::SimpleParser
+
+  ##
+  # Prepare to parse a plain file
+
+  def initialize(top_level, file_name, body, options, stats)
+    preprocess = RDoc::Markup::PreProcess.new(file_name, options.rdoc_include)
+
+    preprocess.handle(body) do |directive, param|
+      warn "Unrecognized directive '#{directive}' in #{file_name}"
+    end
+
+    @body = body
+    @options = options
+    @top_level = top_level
+  end
+
+  ##
+  # Extract the file contents and attach them to the toplevel as a comment
+
+  def scan
+    @top_level.comment = remove_private_comments(@body)
+    @top_level
+  end
+
+  def remove_private_comments(comment)
+    comment.gsub(/^--[^-].*?^\+\+/m, '').sub(/^--.*/m, '')
+  end
+
+end
+

data/lib/rdoc/parsers/parserfactory.rb

@@ -0,0 +1,99 @@
+require "rdoc/parsers/parse_simple"
+
+module RDoc
+
+  # A parser is simple a class that implements
+  #
+  #   #initialize(file_name, body, options)
+  #
+  # and
+  #
+  #   #scan
+  #
+  # The initialize method takes a file name to be used, the body of the
+  # file, and an RDoc::Options object. The scan method is then called
+  # to return an appropriately parsed TopLevel code object.
+  #
+  # The ParseFactory is used to redirect to the correct parser given a filename
+  # extension. This magic works because individual parsers have to register 
+  # themselves with us as they are loaded in. The do this using the following
+  # incantation
+  #
+  #
+  #    require "rdoc/parsers/parsefactory"
+  #    
+  #    module RDoc
+  #    
+  #      class XyzParser
+  #        extend ParseFactory                  <<<<
+  #        parse_files_matching /\.xyz$/        <<<<
+  #    
+  #        def initialize(file_name, body, options)
+  #          ...
+  #        end
+  #    
+  #        def scan
+  #          ...
+  #        end
+  #      end
+  #    end
+  #
+  # Just to make life interesting, if we suspect a plain text file, we
+  # also look for a shebang line just in case it's a potential
+  # shell script
+
+
+
+  module ParserFactory
+
+    @@parsers = []
+
+    Parsers = Struct.new(:regexp, :parser)
+
+    # Record the fact that a particular class parses files that
+    # match a given extension
+
+    def parse_files_matching(regexp)
+      @@parsers.unshift Parsers.new(regexp, self)
+    end
+
+    # Return a parser that can handle a particular extension
+
+    def ParserFactory.can_parse(file_name)
+      @@parsers.find {|p| p.regexp.match(file_name) }
+    end
+
+    # Alias an extension to another extension. After this call,
+    # files ending "new_ext" will be parsed using the same parser
+    # as "old_ext"
+
+    def ParserFactory.alias_extension(old_ext, new_ext)
+      parser = ParserFactory.can_parse("xxx.#{old_ext}")
+      return false unless parser
+      @@parsers.unshift Parsers.new(Regexp.new("\\.#{new_ext}$"), parser.parser)
+      true
+    end
+
+    # Find the correct parser for a particular file name. Return a 
+    # SimpleParser for ones that we don't know
+
+    def ParserFactory.parser_for(top_level, file_name, body, options, stats)
+      # If no extension, look for shebang
+      if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)}
+        shebang = $1
+        case shebang
+        when %r{env\s+ruby}, %r{/ruby}
+          file_name = "dummy.rb"
+        end
+      end
+      parser_description = can_parse(file_name)
+      if parser_description
+        parser = parser_description.parser 
+      else
+        parser = SimpleParser
+      end
+
+      parser.new(top_level, file_name, body, options, stats)
+    end
+  end
+end

data/lib/rdoc/rdoc.rb

@@ -0,0 +1,277 @@
+require 'rdoc'
+
+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/stats'
+require 'rdoc/options'
+
+require 'rdoc/diagram'
+
+require 'find'
+require 'fileutils'
+require 'time'
+
+module RDoc
+
+  ##
+  # Encapsulate the production of rdoc documentation. Basically
+  # you can use this as you would invoke rdoc from the command
+  # line:
+  #
+  #    rdoc = RDoc::RDoc.new
+  #    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
+  # for details.
+
+  class RDoc
+
+    Generator = Struct.new(:file_name, :class_name, :key)
+
+    ##
+    # This is the list of output generator that we support
+
+    GENERATORS = {}
+
+    $LOAD_PATH.collect do |d|
+      File.expand_path d
+    end.find_all do |d|
+      File.directory? "#{d}/rdoc/generator"
+    end.each do |dir|
+      Dir.entries("#{dir}/rdoc/generator").each do |gen|
+        next unless /(\w+)\.rb$/ =~ gen
+        type = $1
+        unless GENERATORS.has_key? type
+          GENERATORS[type] = Generator.new("rdoc/generator/#{gen}",
+                                           "#{type.upcase}".intern,
+                                           type)
+        end
+      end
+    end
+
+    def initialize
+      @stats = Stats.new
+    end
+
+    ##
+    # Report an error message and exit
+
+    def error(msg)
+      raise ::RDoc::Error, msg
+    end
+
+    ##
+    # Create an output dir if it doesn't exist. If it does exist, but doesn't
+    # contain the flag file <tt>created.rid</tt> then we refuse to use it, as
+    # we may clobber some 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"
+        end
+        begin
+          created = File.read(flag_file)
+        rescue SystemCallError
+          error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
+            "isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
+            "destroying any of your existing files, you'll need to\n" +
+            "specify a different output directory name (using the\n" +
+            "--op <dir> option).\n\n"
+        else
+          last = (Time.parse(created) unless force rescue nil)
+        end
+      else
+        FileUtils.mkdir_p(op_dir)
+      end
+      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 also contain comments
+    # (starting with '#')
+
+    def parse_dot_doc_file(in_dir, filename, options)
+      # read and strip comments
+      patterns = File.read(filename).gsub(/#.*/, '')
+
+      result = []
+
+      patterns.split.each do |patt|
+        candidates = Dir.glob(File.join(in_dir, patt))
+        result.concat(normalized_file_list(options,  candidates))
+      end
+      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.
+
+    def normalized_file_list(options, relative_files, force_doc = false,
+                             exclude_pattern = nil)
+      file_list = []
+
+      relative_files.each do |rel_file_name|
+        next if exclude_pattern && exclude_pattern =~ rel_file_name
+        stat = File.stat(rel_file_name)
+        case type = stat.ftype
+        when "file"
+          next if @last_created and stat.mtime < @last_created
+          file_list << rel_file_name.sub(/^\.\//, '') if force_doc || ParserFactory.can_parse(rel_file_name)
+        when "directory"
+          next if rel_file_name == "CVS" || rel_file_name == ".svn"
+          dot_doc = File.join(rel_file_name, DOT_DOC_FILENAME)
+          if File.file?(dot_doc)
+            file_list.concat(parse_dot_doc_file(rel_file_name, dot_doc, options))
+          else
+            file_list.concat(list_files_in_directory(rel_file_name, options))
+          end
+        else
+          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 a .document file, so we're looking for real
+    # files. However we may well contain subdirectories which must be tested
+    # for .document files.
+
+    def list_files_in_directory(dir, options)
+      files = Dir.glob File.join(dir, "*")
+
+      normalized_file_list options, files, false, options.exclude
+    end
+
+    ##
+    # Parse each file on the command line, recursively entering directories.
+
+    def parse_files(options)
+      files = options.files
+      files = ["."] if files.empty?
+
+      file_list = normalized_file_list(options, files, true)
+
+      return [] if file_list.empty?
+
+      file_info = []
+      width = file_list.map { |name| name.length }.max + 1
+
+      file_list.each do |fn|
+        $stderr.printf("\n%*s: ", width, fn) unless options.quiet
+
+        content = if RUBY_VERSION >= '1.9' then
+                    File.open(fn, "r:ascii-8bit") { |f| f.read }
+                  else
+                    File.read fn
+                  end
+
+        if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
+          if enc = Encoding.find($1)
+            content.force_encoding(enc)
+          end
+        end
+
+        top_level = TopLevel.new(fn)
+        parser = ParserFactory.parser_for(top_level, fn, content, options, @stats)
+        file_info << parser.scan
+        @stats.num_files += 1
+      end
+
+      file_info
+    end
+
+    ##
+    # 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: RDoc::Error on error
+
+    def document(argv)
+      TopLevel::reset
+
+      @options = Options.new GENERATORS
+      @options.parse argv
+
+      @last_created = nil
+
+      unless @options.all_one_file then
+        @last_created = setup_output_dir @options.op_dir, @options.force_update
+      end
+
+      start_time = Time.now
+
+      file_info = parse_files @options
+
+      if file_info.empty?
+        $stderr.puts "\nNo newer files." unless @options.quiet
+      else
+        gen = @options.generator
+
+        $stderr.puts "\nGenerating #{gen.key.upcase}..." unless @options.quiet
+
+        require gen.file_name
+
+        gen_class = ::RDoc::Generator.const_get gen.class_name
+        gen = gen_class.for @options
+
+        pwd = Dir.pwd
+
+        Dir.chdir @options.op_dir unless @options.all_one_file
+
+        begin
+          Diagram.new(file_info, @options).draw if @options.diagram
+          gen.generate(file_info)
+          update_output_dir(".", start_time)
+        ensure
+          Dir.chdir(pwd)
+        end
+      end
+
+      unless @options.quiet
+        puts
+        @stats.print
+      end
+    end
+  end
+
+end
+

data/lib/rdoc/ri.rb

@@ -0,0 +1,4 @@
+require 'rdoc'
+
+module RDoc::RI; end
+

data/lib/rdoc/ri/cache.rb

@@ -0,0 +1,188 @@
+require 'rdoc/ri'
+
+class RDoc::RI::ClassEntry
+
+  attr_reader :name
+  attr_reader :path_names
+
+  def initialize(path_name, name, in_class)
+    @path_names = [ path_name ]
+    @name = name
+    @in_class = in_class
+    @class_methods    = []
+    @instance_methods = []
+    @inferior_classes = []
+  end
+
+  # We found this class in more tha one place, so add
+  # in the name from there.
+  def add_path(path)
+    @path_names << path
+  end
+
+  # read in our methods and any classes
+  # and modules in our namespace. Methods are
+  # stored in files called name-c|i.yaml,
+  # where the 'name' portion is the external
+  # form of the method name and the c|i is a class|instance
+  # flag
+
+  def load_from(dir)
+    Dir.foreach(dir) do |name|
+      next if name =~ /^\./
+
+      # convert from external to internal form, and
+      # extract the instance/class flag
+
+      if name =~ /^(.*?)-(c|i).yaml$/
+        external_name = $1
+        is_class_method = $2 == "c"
+        internal_name = RiWriter.external_to_internal(external_name)
+        list = is_class_method ? @class_methods : @instance_methods
+        path = File.join(dir, name)
+        list << MethodEntry.new(path, internal_name, is_class_method, self)
+      else
+        full_name = File.join(dir, name)
+        if File.directory?(full_name)
+          inf_class = @inferior_classes.find {|c| c.name == name }
+          if inf_class
+            inf_class.add_path(full_name)
+          else
+            inf_class = ClassEntry.new(full_name, name, self)
+            @inferior_classes << inf_class
+          end
+          inf_class.load_from(full_name)
+        end
+      end
+    end
+  end
+
+  # Return a list of any classes or modules that we contain
+  # that match a given string
+
+  def contained_modules_matching(name)
+    @inferior_classes.find_all {|c| c.name[name]}
+  end
+
+  def classes_and_modules
+    @inferior_classes
+  end
+
+  # Return an exact match to a particular name
+  def contained_class_named(name)
+    @inferior_classes.find {|c| c.name == name}
+  end
+
+  # return the list of local methods matching name
+  # We're split into two because we need distinct behavior
+  # when called from the _toplevel_
+  def methods_matching(name, is_class_method)
+    local_methods_matching(name, is_class_method)
+  end
+
+  # Find methods matching 'name' in ourselves and in
+  # any classes we contain
+  def recursively_find_methods_matching(name, is_class_method)
+    res = local_methods_matching(name, is_class_method)
+    @inferior_classes.each do |c|
+      res.concat(c.recursively_find_methods_matching(name, is_class_method))
+    end
+    res
+  end
+
+
+  # Return our full name
+  def full_name
+    res = @in_class.full_name
+    res << "::" unless res.empty?
+    res << @name
+  end
+
+  # Return a list of all out method names
+  def all_method_names
+    res = @class_methods.map {|m| m.full_name }
+    @instance_methods.each {|m| res << m.full_name}
+    res
+  end
+
+  private
+
+  # Return a list of all our methods matching a given string.
+  # Is +is_class_methods+ if 'nil', we don't care if the method
+  # is a class method or not, otherwise we only return
+  # those methods that match
+  def local_methods_matching(name, is_class_method)
+
+    list = case is_class_method
+           when nil then  @class_methods + @instance_methods
+           when true then @class_methods
+           when false then @instance_methods
+           else fail "Unknown is_class_method: #{is_class_method.inspect}"
+           end
+
+    list.find_all {|m| m.name;  m.name[name]}
+  end
+end
+
+##
+# A TopLevelEntry is like a class entry, but when asked to search for methods
+# searches all classes, not just itself
+
+class RDoc::RI::TopLevelEntry < RDoc::RI::ClassEntry
+  def methods_matching(name, is_class_method)
+    res = recursively_find_methods_matching(name, is_class_method)
+  end
+
+  def full_name
+      ""
+  end
+
+  def module_named(name)
+
+  end
+
+end
+
+class RDoc::RI::MethodEntry
+  attr_reader :name
+  attr_reader :path_name
+
+  def initialize(path_name, name, is_class_method, in_class)
+    @path_name = path_name
+    @name = name
+    @is_class_method = is_class_method
+    @in_class = in_class
+  end
+
+  def full_name
+    res = @in_class.full_name
+    unless res.empty?
+      if @is_class_method
+        res << "::"
+      else
+        res << "#"
+      end
+    end
+    res << @name
+  end
+end
+
+##
+# We represent everything know about all 'ri' files accessible to this program
+
+class RDoc::RI::Cache
+
+  attr_reader :toplevel
+
+  def initialize(dirs)
+    # At the top level we have a dummy module holding the
+    # overall namespace
+    @toplevel = RDoc::RI::TopLevelEntry.new('', '::', nil)
+
+    dirs.each do |dir|
+      @toplevel.load_from(dir)
+    end
+  end
+
+end
+