voloko-sdoc 0.1.2 → 0.1.3

data/rdoc/lib/rdoc/parser/simple.rb

@@ -0,0 +1,39 @@
+require 'rdoc/parser'
+
+##
+# 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::Parser::Simple < RDoc::Parser
+
+  parse_files_matching(//)
+
+  ##
+  # Prepare to parse a plain file
+
+  def initialize(top_level, file_name, content, options, stats)
+    super
+
+    preprocess = RDoc::Markup::PreProcess.new @file_name, @options.rdoc_include
+
+    preprocess.handle @content do |directive, param|
+      warn "Unrecognized directive '#{directive}' in #{@file_name}"
+    end
+  end
+
+  ##
+  # Extract the file contents and attach them to the TopLevel as a comment
+
+  def scan
+    @top_level.comment = remove_private_comments(@content)
+    @top_level.parser = self.class
+    @top_level
+  end
+
+  def remove_private_comments(comment)
+    comment.gsub(/^--\n.*?^\+\+/m, '').sub(/^--\n.*/m, '')
+  end
+
+end
+

data/rdoc/lib/rdoc/parser.rb

@@ -0,0 +1,138 @@
+require 'rdoc'
+require 'rdoc/code_objects'
+require 'rdoc/markup/preprocess'
+require 'rdoc/stats'
+
+##
+# 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/parser"
+#   
+#   class RDoc::Parser::Xyz < RDoc::Parser
+#     parse_files_matching /\.xyz$/ # <<<<
+#   
+#     def initialize(file_name, body, options)
+#       ...
+#     end
+#   
+#     def scan
+#       ...
+#     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
+
+class RDoc::Parser
+
+  @parsers = []
+
+  class << self
+    attr_reader :parsers
+  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 self.alias_extension(old_ext, new_ext)
+    old_ext = old_ext.sub(/^\.(.*)/, '\1')
+    new_ext = new_ext.sub(/^\.(.*)/, '\1')
+
+    parser = can_parse "xxx.#{old_ext}"
+    return false unless parser
+
+    RDoc::Parser.parsers.unshift [/\.#{new_ext}$/, parser]
+
+    true
+  end
+
+  ##
+  # Shamelessly stolen from the ptools gem (since RDoc cannot depend on
+  # the gem).
+
+  def self.binary?(file)
+    s = (File.read(file, File.stat(file).blksize) || "").split(//)
+
+    if s.size > 0 then
+      ((s.size - s.grep(" ".."~").size) / s.size.to_f) > 0.30
+    else
+      false
+    end
+  end
+  private_class_method :binary?
+
+  ##
+  # Return a parser that can handle a particular extension
+
+  def self.can_parse(file_name)
+    parser = RDoc::Parser.parsers.find { |regexp,| regexp =~ file_name }.last
+
+    #
+    # The default parser should *NOT* parse binary files.
+    #
+    if parser == RDoc::Parser::Simple && file_name !~ /\.(txt|rdoc)$/ then
+      if binary? file_name then
+        return nil
+      end
+    end
+
+    return parser
+  end
+
+  ##
+  # Find the correct parser for a particular file name. Return a SimpleParser
+  # for ones that we don't know
+
+  def self.for(top_level, file_name, body, options, stats)
+    # If no extension, look for shebang
+    if file_name !~ /\.\w+$/ && body =~ %r{\A#!(.+)} then
+      shebang = $1
+      case shebang
+      when %r{env\s+ruby}, %r{/ruby}
+        file_name = "dummy.rb"
+      end
+    end
+
+    parser = can_parse file_name
+
+    # This method must return a parser.
+    parser ||= RDoc::Parser::Simple
+
+    parser.new top_level, file_name, body, options, stats
+  end
+
+  ##
+  # Record which file types this parser can understand.
+
+  def self.parse_files_matching(regexp)
+    RDoc::Parser.parsers.unshift [regexp, self]
+  end
+
+  def initialize(top_level, file_name, content, options, stats)
+    @top_level = top_level
+    @file_name = file_name
+    @content = content
+    @options = options
+    @stats = stats
+  end
+
+end
+
+require 'rdoc/parser/simple'
+

data/rdoc/lib/rdoc/rdoc.rb

@@ -0,0 +1,375 @@
+require 'rdoc'
+
+require 'rdoc/parser'
+
+# Simple must come first
+require 'rdoc/parser/simple'
+require 'rdoc/parser/ruby'
+require 'rdoc/parser/c'
+require 'rdoc/parser/perl'
+
+require 'rdoc/stats'
+require 'rdoc/options'
+
+require 'rdoc/diagram'
+
+require 'find'
+require 'fileutils'
+require 'time'
+require 'thread'
+
+##
+# 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::RDoc
+
+  ##
+  # Generator instance used for creating output
+
+  attr_accessor :generator
+
+  ##
+  # RDoc options
+
+  attr_reader :options
+
+  ##
+  # Accessor for statistics.  Available after each call to parse_files
+
+  attr_reader :stats
+
+  ##
+  # This is the list of supported output generators
+
+  GENERATORS = {}
+
+  ##
+  # Add +klass+ that can generate output after parsing
+
+  def self.add_generator(klass)
+    name = klass.name.sub(/^RDoc::Generator::/, '').downcase
+    GENERATORS[name] = klass
+  end
+
+  ##
+  # Active RDoc::RDoc instance
+
+  def self.current
+    @current
+  end
+
+  ##
+  # Sets the active RDoc::RDoc instance
+
+  def self.current=(rdoc)
+    @current = rdoc
+  end
+
+  def initialize
+    @generator = nil
+    @options = nil
+    @stats = nil
+  end
+
+  ##
+  # Report an error message and exit
+
+  def error(msg)
+    raise RDoc::Error, msg
+  end
+
+  ##
+  # Turns RDoc from stdin into HTML
+
+  def handle_pipe
+    @html = RDoc::Markup::ToHtml.new
+
+    out = @html.convert $stdin.read
+
+    $stdout.write out
+  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 then
+      unless File.directory? op_dir then
+        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 explicitly.
+
+  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 rescue next
+
+      case type = stat.ftype
+      when "file"
+        next if @last_created and stat.mtime < @last_created
+
+        if force_doc or RDoc::Parser.can_parse(rel_file_name) then
+          file_list << rel_file_name.sub(/^\.\//, '')
+        end
+      when "directory"
+        next if rel_file_name == "CVS" || rel_file_name == ".svn"
+        dot_doc = File.join(rel_file_name, RDoc::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, options.exclude)
+
+    return [] if file_list.empty?
+
+    jobs = SizedQueue.new(@options.threads * 3)
+    workers = []
+    file_info = []
+    file_info_lock = Mutex.new
+
+    Thread.abort_on_exception = true
+    @stats = RDoc::Stats.new(file_list.size, options.verbosity)
+    @stats.begin_adding @options.threads
+
+    # Create worker threads.
+    @options.threads.times do
+      thread = Thread.new do
+        while (filename = jobs.pop)
+          @stats.add_file(filename)
+          content = read_file_contents(filename)
+          top_level = RDoc::TopLevel.new filename
+
+          parser = RDoc::Parser.for(top_level, filename, content, options,
+                                    @stats)
+          result = parser.scan
+
+          file_info_lock.synchronize do
+            file_info << result
+          end
+        end
+      end
+      workers << thread
+    end
+
+    # Feed filenames to the parser worker threads...
+    file_list.each do |filename|
+      jobs << filename
+    end
+    workers.size.times do
+      jobs << nil
+    end
+
+    # ...and wait until they're done.
+    workers.each do |thread|
+      thread.join
+    end
+
+    @stats.done_adding
+
+    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)
+    RDoc::TopLevel.reset
+
+    @options = RDoc::Options.new
+    @options.parse argv
+
+    if @options.pipe then
+      handle_pipe
+      exit
+    end
+
+    @last_created = setup_output_dir @options.op_dir, @options.force_update
+
+    start_time = Time.now
+
+    file_info = parse_files @options
+
+    @options.title = "RDoc Documentation"
+
+    if file_info.empty?
+      $stderr.puts "\nNo newer files." unless @options.quiet
+    else
+      gen_klass = @options.generator
+
+      unless @options.quiet then
+        $stderr.puts "\nGenerating #{gen_klass.name.sub(/^.*::/, '')}..."
+      end
+
+      @generator = gen_klass.for @options
+
+      pwd = Dir.pwd
+
+      Dir.chdir @options.op_dir
+
+      begin
+        self.class.current = self
+
+        RDoc::Diagram.new(file_info, @options).draw if @options.diagram
+        @generator.generate file_info
+        update_output_dir ".", start_time
+      ensure
+        self.class.current = nil
+        Dir.chdir pwd
+      end
+    end
+
+    unless @options.quiet or not @stats then
+      puts
+      @stats.print
+    end
+  end
+
+  private
+
+  def read_file_contents(filename)
+    content = if RUBY_VERSION >= '1.9' then
+                File.open(filename, "r:ascii-8bit") { |f| f.read }
+              else
+                File.read filename
+              end
+
+    if defined? Encoding then
+      if /coding:\s*(\S+)/ =~ content[/\A(?:.*\n){0,2}/]
+        if enc = ::Encoding.find($1)
+          content.force_encoding(enc)
+        end
+      end
+    end
+
+    content
+  end
+
+end
+
+if Gem.respond_to? :find_files then
+  rdoc_extensions = Gem.find_files 'rdoc/discover'
+
+  rdoc_extensions.each do |extension|
+    begin
+      load extension
+    rescue => e
+      warn "error loading #{extension.inspect}: #{e.message} (#{e.class})"
+    end
+  end
+end
+
+# require built-in generators after discovery in case they've been replaced
+require 'rdoc/generator/darkfish'
+require 'rdoc/generator/ri'
+

data/rdoc/lib/rdoc/require.rb

@@ -0,0 +1,32 @@
+require 'rdoc/code_object'
+
+##
+# A file loaded by \#require
+
+class RDoc::Require < RDoc::CodeObject
+
+  ##
+  # Name of the required file
+
+  attr_accessor :name
+
+  ##
+  # Creates a new Require that loads +name+ with +comment+
+
+  def initialize(name, comment)
+    super()
+    @name = name.gsub(/'|"/, "") #'
+    self.comment = comment
+  end
+
+  def inspect # :nodoc:
+    "#<%s:0x%x require '%s' in %s>" % [
+      self.class,
+      object_id,
+      @name,
+      parent_file_name,
+    ]
+  end
+
+end
+