ihelp 0.3.2 → 0.4.0

data/lib/ihelp.rb

@@ -1,5 +1,16 @@
 require 'rdoc/ri/ri_driver'
 require 'rexml/document'
+begin
+  if $ihelp_full_text_search != false
+    require 'rubygems'
+    require 'ferret'
+    require 'fileutils'
+    $ihelp_full_text_search = true
+  end
+rescue Exception
+  $ihelp_full_text_search = false
+end
+
 
 # Ri bindings for interactive use from within Ruby.
 # Does a bit of second-guessing (Instance method? Class method?
@@ -23,10 +34,15 @@ require 'rexml/document'
 #   String.instance_help :reverse
 #   String.instance_help :new # => No help found.
 #   a.help :new
-#   help "String#reverse"
-#   help "String.reverse"
+#   ihelp "String#reverse"
+#   ihelp "String.reverse"
 #   a.method(:reverse).help # gets help for Method
-#   help "Hash#map"
+#   ihelp "Hash#map"
+#
+# You can also search for terms in the documentation:
+#
+#   ihelp 'domain name lookup'
+#   String.help 'byte order'
 #
 #
 # Custom help renderers:
@@ -81,6 +97,9 @@ require 'rexml/document'
 #
 # Changelog:
 #
+# 0.4.0
+#   Full-text documentation search using Ferret.
+#
 # 0.3.2
 #   Added support for ruby 1.8.5, added emacs renderer from
 #   rubykitch <rubykitch@ruby-lang.org>, made source renderer use the
@@ -91,7 +110,7 @@ require 'rexml/document'
 # Author: Ilmari Heikkinen <kig misfiring net>
 #
 module IHelp
-  HELP_VERSION = "0.3.2"
+  HELP_VERSION = "0.4.0"
 end
 
 
@@ -188,14 +207,35 @@ module IHelp
   # Uses help_description(method_name, instance).
   #
   def help(method_name=nil, instance=nil)
+    if $ihelp_full_text_search and (
+        method_name and method_name.class == String and
+        self.class == Object and to_s == 'main' and
+        not method_name =~ /::|\.|#/ and
+        not method_name =~ /\A[A-Z][a-z0-9A-Z]*\Z/
+      ) # calling for main
+      IHelp.search method_name
+      return
+    end
+    if $ihelp_full_text_search and method_name and method_name.to_s.include? " " # phrase search
+      puts "Searching from docs..."
+      help_search method_name
+      return
+    end
     info = help_description(method_name, instance)
     if not info
-      puts "No help found."
+      if $ihelp_full_text_search and method_name
+        puts "No help found for method of that name, searching from docs..."
+        help_search method_name
+      else
+        puts "No help found."
+      end
       return
     end
     IHelp.render(info)
   end
 
+  alias_method :ihelp, :help
+
   # Print out help for instance method method_name.
   # If no method_name given, behaves like #help.
   #
@@ -236,6 +276,28 @@ module IHelp
     IHelp.generate_help_description(self, method_name, instance)
   end
 
+  # Searches for str in the documentation of this object.
+  #
+  def help_search(str)
+    raise "No search capability, do you have ferret installed? (gem install ferret)" unless $ihelp_full_text_search
+    ms = if is_a? Module
+      instance_methods.map{|im| instance_method im } +
+      methods.map{|m| method m }
+    else
+      methods.map{|m| method m }
+    end
+    phrases = ms.map do |m|
+      mod, met = m.inspect.split(" ",2)[1][0..-2].split(/#|\./)
+      rmod = mod.scan(/\(([^\)]+)\)/).flatten[0]
+      rmod ||= mod
+      rmod.gsub(/[^a-z0-9]/i){|c| "\\"+c }
+    end.uniq
+    phrases.delete ""
+    name_query = phrases.join(" OR ")
+    query = "(name:(#{name_query})) AND (*:#{IHelp.intersect_search_query str})"
+    IHelp.search query, false
+  end
+
 
   class << self
 
@@ -245,6 +307,9 @@ module IHelp
     # Web browser to use for html and rubydoc renderers.
     attr_accessor :web_browser
 
+    # Don't use colors for highlighting search results.
+    attr_accessor :no_colors
+
     IHelp.renderer ||= :ri
     IHelp.web_browser ||= 'firefox'
 
@@ -253,6 +318,38 @@ module IHelp
       IHelp::RI_ARGS = ENV["RI"].split.concat(ARGV)
     end
 
+    # Searches for str from available documentation and prints out the
+    # results.
+    #
+    # Creates a search index if you don't already have one. Creating the index
+    # may take a couple of minutes.
+    #
+    # See IHelpIndex.
+    #
+    def search(str, escape_query=true)
+      raise "No search capability, do you have ferret installed? (gem install ferret)" unless $ihelp_full_text_search
+      if escape_query
+        help_index.search(intersect_search_query(str.to_s))
+      else
+        help_index.search(str)
+      end
+      nil
+    end
+
+    def intersect_search_query(str)
+      a = IHelpAnalyzer.new
+      t = a.token_stream :content, str.to_s
+      c = []
+      n = nil
+      c << n.text while n = t.next
+      "(#{c.join(" AND ")})"
+    end
+
+    attr_accessor :help_index
+    def help_index
+      @help_index ||= IHelpIndex.new
+    end
+
     # Render the RI info object a renderer method in IHelp::Renderer.
     # The name of the renderer method to use is returned by IHelp.renderer,
     # and can be set with IHelp.renderer=.
@@ -277,6 +374,11 @@ module IHelp
           meth_str, klass_name, instance_help, double_colon =
             get_help_klass_info_for_name(meth_str)
             klass_ancs = find_ancestors(klass_name, instance)
+        elsif (/\A[A-Z][a-zA-Z0-9_]*\Z/ === meth_str and # called with e.g. "Array"
+               not (klass.methods+Kernel.methods).include? meth_str)
+          meth_str, klass_name, instance_help, double_colon =
+            get_help_klass_info_for_name(meth_str)
+            klass_ancs = find_ancestors(klass_name, instance)
         else
           klass_name, klass_ancs, instance_help =
             get_help_klass_info(klass, instance)
@@ -388,6 +490,8 @@ module IHelp
   #
   class IHelpDriver < RiDriver
 
+    attr_accessor :ri_reader, :display
+
     # Create new IHelpDriver, with the given args
     # passed to @options, which is a RI::Options.instance
     #
@@ -418,7 +522,7 @@ module IHelp
       }
       return nil if namespaces.empty?
       if method_name.nil?
-        get_class_info_str(namespaces)
+        get_class_info_str(namespaces, klass_name)
       else
         methods = @ri_reader.find_methods(
                     method_name, is_class_method, namespaces)
@@ -441,11 +545,13 @@ module IHelp
 
     # Get info for the class in the given namespaces.
     #
-    def get_class_info_str(namespaces)
+    def get_class_info_str(namespaces, klass_name)
       return nil if namespaces.empty?
+      klass_name_last = klass_name.split("::").last
       klass = nil
       namespaces.find{|ns|
         begin
+          ns.name == klass_name_last and
           klass = @ri_reader.get_class(ns)
         rescue TypeError
           nil
@@ -471,6 +577,240 @@ module IHelp
   end
 
 
+  # IHelpIndex uses Ferret to index all available RI documentation
+  # and lets you do full text searches over the index.
+  #
+  # E.g. IHelpIndex.new.search("domain name lookup")
+  #
+  # See Ferret::QueryParser for query string format.
+  #
+  class IHelpIndex
+
+    class << self
+      attr_accessor :reindex_when_needed
+    end
+
+    # The search index, is a Ferret::Index::Index
+    attr_accessor :index
+
+    attr_accessor :log_level
+
+    # Default place to save and load the index from.
+    GLOBAL_INDEX_PATH = File.join(File.dirname(__FILE__), "ihelp.index")
+    LOCAL_INDEX_PATH = File.join(ENV["HOME"], ".ihelp.index")
+    DEFAULT_LOG_LEVEL = 2
+
+    def initialize(use_global_index = (ENV["USER"] == "root"))
+      @log_level = DEFAULT_LOG_LEVEL
+      if use_global_index
+        @index_path = GLOBAL_INDEX_PATH
+      else
+        @index_path = LOCAL_INDEX_PATH
+        if not File.exist?(@index_path) and File.exist?(GLOBAL_INDEX_PATH)
+          FileUtils.cp_r(GLOBAL_INDEX_PATH, @index_path) rescue nil
+        end
+      end
+      analyzer = IHelpAnalyzer.new
+      have_index = File.exist? @index_path
+      if have_index
+        log "Loading existing index from #{@index_path}", 1
+        @index = Ferret::I.new(
+          :key => :full_name,
+          :path => @index_path,
+          :analyzer => analyzer
+        )
+      else
+        log "Creating new index in #{@index_path}", 2
+        field_infos = Ferret::Index::FieldInfos.new(:term_vector => :no)
+        field_infos.add_field(:name,
+                          :store => :yes,
+                          :index => :yes,
+                          :boost => 10.0)
+        field_infos.add_field(:full_name,
+                          :store => :yes,
+                          :index => :untokenized,
+                          :boost => 0.0)
+        field_infos.add_field(:content,
+                          :boost => 1.0,
+                          :store => :yes,
+                          :index => :yes,
+                          :term_vector => :with_positions_offsets)
+        @index = Ferret::I.new(
+          :key => :full_name,
+          :field_infos => field_infos,
+          :analyzer => analyzer
+        )
+      end
+      reindex! if self.class.reindex_when_needed and need_reindexing?
+      unless have_index
+        @index.persist(@index_path)
+        log "Saved index.", 2
+      end
+    end
+
+    def log str, level = 1
+      STDERR.puts str if level >= @log_level
+    end
+
+    def time
+      t = Time.now
+      rv = yield
+      log "Took #{Time.now - t}"
+      rv
+    end
+
+    # Returns true if there already is an object named full_name
+    #
+    def already_indexed? full_name
+      @index[full_name]
+    end
+
+    def format_time(t)
+      sec = t % 60
+      min = (t / 60) % 60
+      hour = (t / 3600)
+      str = sec.to_i.to_s.rjust(2,'0')
+      str = min.to_i.to_s.rjust(2,'0') + ":" + str
+      str = hour.to_i.to_s.rjust(2,'0') + ":" + str if hour >= 1
+      str
+    end
+
+    def all_names
+      IHelp.ri_driver.ri_reader.all_names.uniq
+    end
+
+    def need_reindexing?
+      all_names.size > @index.size
+    end
+
+    # Reindexes any non-indexed help documents.
+    #
+    def reindex!
+      start_size = @index.size
+      names = all_names
+      log "Indexing...", 2
+      nsz = names.size.to_s
+      i = 0
+      names.each{|n|
+        i += 1
+        next if (start_size > 0) and (already_indexed?(n))
+        if @log_level == DEFAULT_LOG_LEVEL
+          amt_done = (i.to_f / names.size)
+          pct = ("%.1f" % [100*amt_done]).rjust(5)
+          STDERR.write "\r #{pct}% (#{i.to_s.rjust(nsz.size)}/#{nsz}) #{n}".ljust(80)[0,80]
+          STDERR.flush
+        end
+        hd = if n.include? "#"
+          IHelp.ri_driver.get_info_str(*(n.split("#") + [true]))
+        elsif n.include? "::"
+          IHelp.ri_driver.get_info_str(n) or
+          IHelp.ri_driver.get_info_str(*n.reverse.split("::",2).reverse.map{|r| r.reverse })
+        else
+          IHelp.ri_driver.get_info_str n
+        end
+        if hd.nil?
+          log "skipping #{n} (not found)"
+          next
+        else
+          log "indexing #{n}"
+        end
+        @index << {
+          :name => hd.full_name,
+          :full_name => n,
+          :content => hd.to_text
+        }
+      }
+      if @log_level == DEFAULT_LOG_LEVEL
+        amt_done = (i.to_f / names.size)
+        pct = ("%.1f" % [100*amt_done]).rjust(5)
+        STDERR.write "\r #{pct}% (#{i.to_s.rjust(nsz.size)}/#{nsz}) #{names.last}".ljust(80)[0,80]
+        STDERR.flush
+      end
+      if start_size != @index.size
+        log "Optimizing index... (old size #{start_size}, current size #{@index.size})"
+        @index.optimize
+      end
+    end
+
+    def display
+      return @display if @display
+      @display = RI::Options.instance.displayer.clone
+      if ENV["PAGER"].to_s.size > 0
+        unless ENV["PAGER"] =~ /(^|\/)less\b.* -[a-zA-Z]*[rR]/
+          IHelp.no_colors = true
+        end
+      else
+        ENV["PAGER"] = "less -R"
+      end
+      class << @display
+        public :page
+        attr_accessor :formatter
+      end
+      @display
+    end
+
+    def page(*a,&b)
+      display.page(*a,&b)
+    end
+
+    def wrap(str)
+      display.formatter.wrap(str)
+    end
+
+    def init_display
+      display
+    end
+
+    # Searches for the terms in query and prints out first ten hits
+    #
+    # See Ferret::QueryParser for query string format.
+    #
+    def search(query, *a)
+      result = @index.search(query, *a)
+      init_display
+      if IHelp.no_colors or `which less`.strip.empty?
+        pre_tag = "<<"
+        post_tag = ">>"
+      else
+        name_start = "\033[32m"
+        name_end = "\033[0m"
+        pre_tag = "\033[36m"
+        post_tag = "\033[0m"
+      end
+      page do
+        puts
+        puts "=== #{result.total_hits} hits#{", showing first 10" if result.total_hits > 10} ".ljust(72,"=")
+        puts
+        result.hits.each_with_index do |hit, i|
+          id, score = hit.doc, hit.score
+          #puts hit.score
+          puts "#{name_start}#{@index[id][:full_name]}#{name_end}"
+          puts
+          wrap @index.highlight(query, id, :field => :content,
+                                :pre_tag => pre_tag,
+                                :post_tag => post_tag).to_s
+          puts
+          display.formatter.draw_line
+          puts
+        end
+        puts
+      end
+      p result.hits.map{|hit| @index[hit.doc][:full_name] }
+      result
+    end
+
+  end
+
+
+  if defined? Ferret
+    class IHelpAnalyzer < Ferret::Analysis::StandardAnalyzer
+      def token_stream(*a)
+        Ferret::Analysis::StemFilter.new(super)
+      end
+    end
+  end
+
+
 end
 
 
@@ -490,15 +830,16 @@ module RI
       header = root.add_element(header_tag)
       header.add_text(full_name)
       comment.each{|c|
-        tag = c.class.to_s.split("::").last
-        tag = "PRE" if tag == "VERB"
-        xmlstr = "<#{tag}>#{c.body}</#{tag}>"
-        c_doc = REXML::Document.new(xmlstr)
-        root.add_element( c_doc.root )
+        root.add_element( c.to_html.root )
       }
       doc
     end
 
+    def to_text
+      name + " -- " + params.to_s + block_params.to_s + "\n" +
+      (comment || []).map{|c| c.to_text }.join("\n")
+    end
+
   end
 
 
@@ -520,11 +861,7 @@ module RI
       header = root.add_element(header_tag)
       header.add_text(full_name)
       comment.each{|c|
-        tag = c.class.to_s.split("::").last
-        tag = "PRE" if tag == "VERB"
-        xmlstr = "<#{tag}>#{c.body}</#{tag}>"
-        c_doc = REXML::Document.new(xmlstr)
-        root.add_element( c_doc.root )
+        root.add_element( c.to_html.root )
       }
       root.add_element(methods_header_tag).add_text("Class Methods")
       cmethods = root.add_element(methods_tag)
@@ -543,6 +880,34 @@ module RI
       doc
     end
 
+    def to_text
+      segs = [full_name]
+      segs += (comment || []).map{|c| c.to_text }
+      segs << "" << "Class methods: " << (class_methods || []).map{|m| m.to_text }.join(", ")
+      segs << "" << "Instance methods: " << (instance_methods || []).map{|m| m.to_text }.join(", ")
+      segs << "" << "Constants: " << (constants || []).map{|m| m.to_text }.join("\n")
+      segs << "" << "Attributes: " << (attributes || []).map{|m| m.to_text }.join("\n")
+      segs.join("\n")
+    end
+
+  end
+
+
+  class Attribute
+
+    def to_text
+      "#{name} [#{rw}] #{(comment || []).map{|c| c.to_text }.join("\n")}"
+    end
+
+  end
+
+
+  class Constant
+
+    def to_text
+      "#{name} = #{value} #{(comment || []).map{|c| c.to_text }.join("\n")}"
+    end
+
   end
 
 
@@ -560,6 +925,44 @@ module RI
       doc
     end
 
+    def to_text
+      name
+    end
+
+  end
+
+
+end
+
+
+module SM::Flow
+  constants.each{|c|
+    const_get(c).__send__(:include, self)
+  }
+
+  def to_text
+    RI::TextFormatter.allocate.conv_html(
+      if respond_to? :body
+        body
+      else
+        ""
+      end +
+      if respond_to? :contents
+        contents.map{|c| c.to_text }.join("\n\n")
+      else
+        ""
+      end
+    ).gsub(/<\/?..>/, '')
+  end
+
+  def to_html
+    tag = self.class.to_s.split("::").last
+    tag = "PRE" if tag == "VERB"
+    xmlstr = %Q(<#{tag}>
+      #{body if respond_to? :body}
+      #{contents.map{|c|c.to_html} if respond_to? :content}
+    </#{tag}>)
+    REXML::Document.new(xmlstr)
   end
 
 end

data/lib/ihelp_reindex.rb

@@ -0,0 +1,12 @@
+load File.join(File.expand_path(File.dirname(__FILE__)), 'ihelp.rb')
+
+IHelp::IHelpIndex.reindex_when_needed = true
+IHelp::IHelpIndex.new(true)
+begin
+  path = IHelp::IHelpIndex::GLOBAL_INDEX_PATH
+  STDERR.puts
+  STDERR.puts 'Making global index at '+path+' readable'
+  Dir[File.join(path,"*")].each{|n| File.chmod 0644, n }
+  File.open("Makefile",'w'){|f| f.puts "install:" }
+end
+

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11
 specification_version: 1
 name: ihelp
 version: !ruby/object:Gem::Version 
-  version: 0.3.2
-date: 2006-11-13 00:00:00 +02:00
+  version: 0.4.0
+date: 2006-11-16 00:00:00 +02:00
 summary: Interactive help
 require_paths: 
 - lib
@@ -37,9 +37,17 @@ extra_rdoc_files: []
 
 executables: []
 
-extensions: []
-
+extensions: 
+- lib/ihelp_reindex.rb
 requirements: []
 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ferret
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.10.13
+    version: