rdoc-f95 0.0.1

data/lib/rdoc-f95/ri/display.rb

@@ -0,0 +1,244 @@
+require 'rdoc-f95/ri'
+
+##
+# This is a kind of 'flag' module. If you want to write your own 'ri' display
+# module (perhaps because you'r writing an IDE or somesuch beast), you simply
+# write a class which implements the various 'display' methods in
+# 'DefaultDisplay', and include the 'RiDisplay' module in that class.
+#
+# To access your class from the command line, you can do
+#
+#    ruby -r <your source file>  ../ri ....
+
+module RDocF95::RI::Display
+
+  @@display_class = nil
+
+  def self.append_features(display_class)
+    @@display_class = display_class
+  end
+
+  def self.new(*args)
+    @@display_class.new(*args)
+  end
+
+end
+
+##
+# A paging display module. Uses the RDocF95::RI::Formatter class to do the actual
+# presentation.
+
+class RDocF95::RI::DefaultDisplay
+
+  include RDocF95::RI::Display
+
+  def initialize(formatter, width, use_stdout)
+    @use_stdout = use_stdout
+    @formatter = formatter.new $stdout, width, "     "
+  end
+
+  def display_method_info(method)
+    page do
+      @formatter.draw_line(method.full_name)
+      display_params(method)
+      @formatter.draw_line
+      display_flow(method.comment)
+      if method.aliases && !method.aliases.empty?
+        @formatter.blankline
+        aka = "(also known as "
+        aka << method.aliases.map {|a| a.name }.join(", ")
+        aka << ")"
+        @formatter.wrap(aka)
+      end
+    end
+  end
+
+  def display_class_info(klass, ri_reader)
+    page do
+      superclass = klass.superclass_string
+
+      if superclass
+        superclass = " < " + superclass
+      else
+        superclass = ""
+      end
+
+      @formatter.draw_line(klass.display_name + ": " +
+                           klass.full_name + superclass)
+
+      display_flow(klass.comment)
+      @formatter.draw_line
+
+      unless klass.includes.empty?
+        @formatter.blankline
+        @formatter.display_heading("Includes:", 2, "")
+        incs = []
+        klass.includes.each do |inc|
+          inc_desc = ri_reader.find_class_by_name(inc.name)
+          if inc_desc
+            str = inc.name + "("
+            str << inc_desc.instance_methods.map{|m| m.name}.join(", ")
+            str << ")"
+            incs << str
+          else
+            incs << inc.name
+          end
+      end
+        @formatter.wrap(incs.sort.join(', '))
+      end
+
+      unless klass.constants.empty?
+        @formatter.blankline
+        @formatter.display_heading("Constants:", 2, "")
+        len = 0
+        klass.constants.each { |c| len = c.name.length if c.name.length > len }
+        len += 2
+        klass.constants.each do |c|
+          @formatter.wrap(c.value,
+                          @formatter.indent+((c.name+":").ljust(len)))
+        end
+      end
+
+      unless klass.class_methods.empty?
+        @formatter.blankline
+        @formatter.display_heading("Class methods:", 2, "")
+        @formatter.wrap(klass.class_methods.map{|m| m.name}.sort.join(', '))
+      end
+
+      unless klass.class_method_extensions.empty?
+        @formatter.blankline
+        @formatter.display_heading("Class Method Extensions:", 2, "")
+        @formatter.wrap(klass.class_method_extensions.map{|m| m.name}.sort.join(', '))
+      end
+
+      unless klass.instance_methods.empty?
+        @formatter.blankline
+        @formatter.display_heading("Instance methods:", 2, "")
+        @formatter.wrap(klass.instance_methods.map{|m| m.name}.sort.join(', '))
+      end
+
+      unless klass.instance_method_extensions.empty?
+        @formatter.blankline
+        @formatter.display_heading("Instance Method Extensions:", 2, "")
+        @formatter.wrap(klass.instance_method_extensions.map{|m| m.name}.sort.join(', '))
+      end
+
+      unless klass.attributes.empty?
+        @formatter.blankline
+        @formatter.wrap("Attributes:", "")
+        @formatter.wrap(klass.attributes.map{|a| a.name}.sort.join(', '))
+      end
+    end
+  end
+
+  ##
+  # Display a list of method names
+
+  def display_method_list(methods)
+    page do
+      @formatter.raw_print_line("More than one method matched your request. You can refine")
+      @formatter.raw_print_line("your search by asking for information on one of:\n\n")
+      @formatter.wrap(methods.map {|m| m.full_name} .join(", "))
+    end
+  end
+
+  def display_class_list(namespaces)
+    page do
+      @formatter.raw_print_line("More than one class or module matched your request. You can refine")
+      @formatter.raw_print_line("your search by asking for information on one of:\n\n")
+      @formatter.wrap(namespaces.map {|m| m.full_name}.join(", "))
+    end
+  end
+
+  def list_known_classes(classes)
+    if classes.empty?
+      warn_no_database
+    else
+      page do
+        @formatter.draw_line("Known classes and modules")
+        @formatter.blankline
+        @formatter.wrap(classes.sort.join(", "))
+      end
+    end
+  end
+
+  def list_known_names(names)
+    if names.empty?
+      warn_no_database
+    else
+      page do
+        names.each {|n| @formatter.raw_print_line(n)}
+      end
+    end
+  end
+
+  private
+
+  def page
+    if pager = setup_pager then
+      begin
+        orig_output = @formatter.output
+        @formatter.output = pager
+        yield
+      ensure
+        @formatter.output = orig_output
+        pager.close
+      end
+    else
+      yield
+    end
+  rescue Errno::EPIPE
+  end
+
+  def setup_pager
+    unless @use_stdout then
+      for pager in [ ENV['PAGER'], "less", "more", 'pager' ].compact.uniq
+        return IO.popen(pager, "w") rescue nil
+      end
+      @use_stdout = true
+      nil
+    end
+  end
+
+  def display_params(method)
+    params = method.params
+
+    if params[0,1] == "("
+      if method.is_singleton
+        params = method.full_name + params
+      else
+        params = method.name + params
+      end
+    end
+    params.split(/\n/).each do |p|
+      @formatter.wrap(p)
+      @formatter.break_to_newline
+    end
+    if method.source_path then
+      @formatter.blankline
+      @formatter.wrap("Extension from #{method.source_path}")
+    end
+  end
+
+  def display_flow(flow)
+    if !flow || flow.empty?
+      @formatter.wrap("(no description...)")
+    else
+      @formatter.display_flow(flow)
+    end
+  end
+
+  def warn_no_database
+    puts "No ri data found"
+    puts
+    puts "If you've installed Ruby yourself, you need to generate documentation using:"
+    puts
+    puts "  make install-doc"
+    puts
+    puts "from the same place you ran `make` to build ruby."
+    puts
+    puts "If you installed Ruby from a packaging system, then you may need to"
+    puts "install an additional package, or ask the packager to enable ri generation."
+  end
+end
+

data/lib/rdoc-f95/ri/driver.rb

@@ -0,0 +1,435 @@
+require 'optparse'
+require 'yaml'
+
+require 'rdoc-f95/ri'
+require 'rdoc-f95/ri/paths'
+require 'rdoc-f95/ri/formatter'
+require 'rdoc-f95/ri/display'
+require 'fileutils'
+require 'rdoc-f95/markup'
+require 'rdoc-f95/markup/to_flow'
+
+class RDocF95::RI::Driver
+
+  def self.process_args(argv)
+    options = {}
+    options[:use_stdout] = !$stdout.tty?
+    options[:width] = 72
+    options[:formatter] = RDocF95::RI::Formatter.for 'plain'
+    options[:list_classes] = false
+    options[:list_names] = false
+
+    # By default all paths are used.  If any of these are true, only those
+    # directories are used.
+    use_system = false
+    use_site = false
+    use_home = false
+    use_gems = false
+    doc_dirs = []
+
+    opts = OptionParser.new do |opt|
+      opt.program_name = File.basename $0
+      opt.version = RDocF95::VERSION
+      opt.summary_indent = ' ' * 4
+
+      directories = [
+        RDocF95::RI::Paths::SYSDIR,
+        RDocF95::RI::Paths::SITEDIR,
+        RDocF95::RI::Paths::HOMEDIR
+      ]
+
+      if RDocF95::RI::Paths::GEMDIRS then
+        Gem.path.each do |dir|
+          directories << "#{dir}/doc/*/ri"
+        end
+      end
+
+      opt.banner = <<-EOT
+Usage: #{opt.program_name} [options] [names...]
+
+Where name can be:
+
+  Class | Class::method | Class#method | Class.method | method
+
+All class names may be abbreviated to their minimum unambiguous form. If a name
+is ambiguous, all valid options will be listed.
+
+The form '.' method matches either class or instance methods, while #method
+matches only instance and ::method matches only class methods.
+
+For example:
+
+    #{opt.program_name} Fil
+    #{opt.program_name} File
+    #{opt.program_name} File.new
+    #{opt.program_name} zip
+
+Note that shell quoting may be required for method names containing
+punctuation:
+
+    #{opt.program_name} 'Array.[]'
+    #{opt.program_name} compact\\!
+
+By default ri searches for documentation in the following directories:
+
+    #{directories.join "\n    "}
+
+Specifying the --system, --site, --home, --gems or --doc-dir options will
+limit ri to searching only the specified directories.
+
+Options may also be set in the 'RI' environment variable.
+      EOT
+
+      opt.separator nil
+      opt.separator "Options:"
+      opt.separator nil
+
+      opt.on("--classes", "-c",
+             "Display the names of classes and modules we",
+             "know about.") do |value|
+        options[:list_classes] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--doc-dir=DIRNAME", "-d", Array,
+             "List of directories to search for",
+             "documentation. If not specified, we search",
+             "the standard rdoc/ri directories. May be",
+             "repeated.") do |value|
+        value.each do |dir|
+          unless File.directory? dir then
+            raise OptionParser::InvalidArgument, "#{dir} is not a directory"
+          end
+        end
+
+        doc_dirs.concat value
+      end
+
+      opt.separator nil
+
+      opt.on("--fmt=FORMAT", "--format=FORMAT", "-f",
+             RDocF95::RI::Formatter::FORMATTERS.keys,
+             "Format to use when displaying output:",
+             "   #{RDocF95::RI::Formatter.list}",
+             "Use 'bs' (backspace) with most pager",
+             "programs. To use ANSI, either disable the",
+             "pager or tell the pager to allow control",
+             "characters.") do |value|
+        options[:formatter] = RDocF95::RI::Formatter.for value
+      end
+
+      opt.separator nil
+
+      unless RDocF95::RI::Paths::GEMDIRS.empty? then
+        opt.on("--[no-]gems",
+               "Include documentation from RubyGems.") do |value|
+          use_gems = value
+        end
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]home",
+             "Include documentation stored in ~/.rdoc.") do |value|
+        use_home = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]list-names", "-l",
+             "List all the names known to RDoc, one per",
+             "line.") do |value|
+        options[:list_names] = value
+      end
+
+      opt.separator nil
+
+      opt.on("--no-pager", "-T",
+             "Send output directly to stdout.") do |value|
+        options[:use_stdout] = !value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]site",
+             "Include documentation from libraries",
+             "installed in site_lib.") do |value|
+        use_site = value
+      end
+
+      opt.separator nil
+
+      opt.on("--[no-]system",
+             "Include documentation from Ruby's standard",
+             "library.") do |value|
+        use_system = value
+      end
+
+      opt.separator nil
+
+      opt.on("--width=WIDTH", "-w", OptionParser::DecimalInteger,
+             "Set the width of the output.") do |value|
+        options[:width] = value
+      end
+    end
+
+    argv = ENV['RI'].to_s.split.concat argv
+
+    opts.parse! argv
+
+    options[:names] = argv
+
+    options[:path] = RDocF95::RI::Paths.path(use_system, use_site, use_home,
+                                          use_gems, *doc_dirs)
+    options[:raw_path] = RDocF95::RI::Paths.raw_path(use_system, use_site,
+                                                  use_home, use_gems, *doc_dirs)
+
+    options
+
+  rescue OptionParser::InvalidArgument, OptionParser::InvalidOption => e
+    puts opts
+    puts
+    puts e
+    exit 1
+  end
+
+  def self.run(argv = ARGV)
+    options = process_args argv
+    ri = new options
+    ri.run
+  end
+
+  def initialize(options)
+    @names = options[:names]
+
+    @class_cache_name = 'classes'
+    @all_dirs = RDocF95::RI::Paths.path(true, true, true, true)
+    @homepath = RDocF95::RI::Paths.raw_path(false, false, true, false).first
+    @homepath = @homepath.sub(/\.rdoc/, '.ri')
+    @sys_dirs = RDocF95::RI::Paths.raw_path(true, false, false, false)
+
+    FileUtils.mkdir_p cache_file_path unless File.directory? cache_file_path
+
+    @class_cache = nil
+
+    @display = RDocF95::RI::DefaultDisplay.new(options[:formatter],
+                                            options[:width],
+                                            options[:use_stdout])
+  end
+
+  def class_cache
+    return @class_cache if @class_cache
+
+    newest = map_dirs('created.rid', :all) do |f|
+      File.mtime f if test ?f, f
+    end.max
+
+    up_to_date = (File.exist?(class_cache_file_path) and
+                  newest < File.mtime(class_cache_file_path))
+
+    @class_cache = if up_to_date then
+                     load_cache_for @class_cache_name
+                   else
+                     class_cache = {}
+
+                     classes = map_dirs('**/cdesc*.yaml', :sys) { |f| Dir[f] }
+                     populate_class_cache class_cache, classes
+
+                     classes = map_dirs('**/cdesc*.yaml') { |f| Dir[f] }
+                     warn "Updating class cache with #{classes.size} classes..."
+
+                     populate_class_cache class_cache, classes, true
+                     write_cache class_cache, class_cache_file_path
+                   end
+  end
+
+  def class_cache_file_path
+    File.join cache_file_path, @class_cache_name
+  end
+
+  def cache_file_for(klassname)
+    File.join cache_file_path, klassname.gsub(/:+/, "-")
+  end
+
+  def cache_file_path
+    File.join @homepath, 'cache'
+  end
+
+  def display_class(name)
+    klass = class_cache[name]
+    @display.display_class_info klass, class_cache
+  end
+
+  def load_cache_for(klassname)
+    path = cache_file_for klassname
+
+    if File.exist? path and
+       File.mtime(path) >= File.mtime(class_cache_file_path) then
+      File.open path, 'rb' do |fp|
+        Marshal.load fp.read
+      end
+    else
+      class_cache = nil
+
+      File.open class_cache_file_path, 'rb' do |fp|
+        class_cache = Marshal.load fp.read
+      end
+
+      klass = class_cache[klassname]
+      return nil unless klass
+
+      method_files = klass["sources"]
+      cache = {}
+
+      sys_dir = @sys_dirs.first
+      method_files.each do |f|
+        system_file = f.index(sys_dir) == 0
+        Dir[File.join(File.dirname(f), "*")].each do |yaml|
+          next unless yaml =~ /yaml$/
+          next if yaml =~ /cdesc-[^\/]+yaml$/
+          method = read_yaml yaml
+          name = method["full_name"]
+          ext_path = f
+          ext_path = "gem #{$1}" if f =~ %r%gems/[\d.]+/doc/([^/]+)%
+          method["source_path"] = ext_path unless system_file
+          cache[name] = method
+        end
+      end
+
+      write_cache cache, path
+    end
+  end
+
+  def map_dirs(file_name, system=false)
+    dirs = if system == :all then
+             @all_dirs
+           else
+             if system then
+               @sys_dirs
+             else
+               @all_dirs - @sys_dirs
+             end
+           end
+
+    dirs.map { |dir| yield File.join(dir, file_name) }.flatten.compact
+  end
+
+  def populate_class_cache(class_cache, classes, extension = false)
+    classes.each do |cdesc|
+      desc = read_yaml cdesc
+      klassname = desc["full_name"]
+
+      unless class_cache.has_key? klassname then
+        desc["display_name"] = "Class"
+        desc["sources"] = [cdesc]
+        desc["instance_method_extensions"] = []
+        desc["class_method_extensions"] = []
+        class_cache[klassname] = desc
+      else
+        klass = class_cache[klassname]
+
+        if extension then
+          desc["instance_method_extensions"] = desc.delete "instance_methods"
+          desc["class_method_extensions"] = desc.delete "class_methods"
+        end
+
+        klass.merge_enums desc
+        klass["sources"] << cdesc
+      end
+    end
+  end
+
+  def read_yaml(path)
+    YAML.load File.read(path).gsub(/ \!ruby\/(object|struct):(RDocF95::RI|RI|SM).*/, '')
+  end
+
+  def run
+    if @names.empty? then
+      @display.list_known_classes class_cache.keys.sort
+    else
+      @names.each do |name|
+        case name
+        when /::|\#|\./ then
+          if class_cache.key? name then
+            display_class name
+          else
+            meth = nil
+
+            parts = name.split(/::|\#|\./)
+            meth = parts.pop unless parts.last =~ /^[A-Z]/
+            klass = parts.join '::'
+
+            cache = load_cache_for klass
+            # HACK Does not support F.n
+            abort "Nothing known about #{name}" unless cache
+            method = cache[name.gsub(/\./, '#')]
+            abort "Nothing known about #{name}" unless method
+            @display.display_method_info method
+          end
+        else
+          if class_cache.key? name then
+            display_class name
+          else
+            methods = select_methods(/^#{name}/)
+            if methods.size == 0
+              abort "Nothing known about #{name}"
+            elsif methods.size == 1
+              @display.display_method_info methods.first
+            else
+              @display.display_method_list methods
+            end
+          end
+        end
+      end
+    end
+  end
+
+  def select_methods(pattern)
+    methods = []
+    class_cache.keys.sort.each do |klass|
+      class_cache[klass]["instance_methods"].map{|h|h["name"]}.grep(pattern) do |name|
+        method = load_cache_for(klass)[klass+'#'+name]
+        methods << method if method
+      end
+      class_cache[klass]["class_methods"].map{|h|h["name"]}.grep(pattern) do |name|
+        method = load_cache_for(klass)[klass+'::'+name]
+        methods << method if method
+      end
+    end
+    methods
+  end
+
+  def write_cache(cache, path)
+    File.open path, "wb" do |cache_file|
+      Marshal.dump cache, cache_file
+    end
+
+    cache
+  end
+
+end
+
+class Hash
+  def method_missing method, *args
+    self[method.to_s]
+  end
+
+  def merge_enums(other)
+    other.each do |k,v|
+      if self[k] then
+        case v
+        when Array then
+          self[k] += v
+        when Hash then
+          self[k].merge! v
+        else
+          # do nothing
+        end
+      else
+        self[k] = v
+      end
+    end
+  end
+end
+