Module IHelp
In: lib/ihelp.rb

Ri bindings for interactive use from within Ruby. Does a bit of second-guessing (Instance method? Class method? Try both unless explicitly defined. Not found in this class? Try the ancestor classes.)

The goal is that help is given for all methods that have help.

Examples:

  require 'ihelp'

  a = "string"
  a.help
  a.help :reverse
  a.help :map
  String.help
  String.help :new
  String.help :reverse
  String.help :map
  String.instance_help :reverse
  String.instance_help :new # => No help found.
  a.help :new
  ihelp "String#reverse"
  ihelp "String.reverse"
  a.method(:reverse).help # gets help for Method
  ihelp "Hash#map"

You can also search for terms in the documentation:

  ihelp 'domain name lookup'
  String.help 'byte order'

Custom help renderers:

The help-method calls IHelp::Renderer‘s method defined by IHelp.renderer with the RI info object. You can print help out the way you want by defining your own renderer method in IHelp::Renderer and setting IHelp.renderer to the name of the method.

Example:

  require 'ihelp'

  IHelp.renderers
  # => ["emacs", "rubydoc", "ri", "source", "html"]

  class IHelp::Renderer
    def print_name(info)
      puts info.full_name
    end
  end

  IHelp.renderers
  # => ["emacs", "rubydoc", "ri", "source", "print_name", "html"]

  IHelp.renderer = :print_name

  [1,2,3].help:reject
  # Array#reject
  # => nil

The current renderers are:

  ri -- the default renderer
  html -- creates a HTML document for the help and opens it
          with the program named in IHelp.web_browser
  rubydoc -- opens the corresponding www.ruby-doc.org class
             documentation page with the program named in
             IHelp.web_browser
  emacs -- uses gnudoit and ri-emacs to display help in an Emacs buffer.
           The Emacs commands that I got it running with were:
              ;; make ri-emacs autoload according to its instructions
              M-x ruby-mode
              M-x gnuserv-start
              M-x run-ruby
              > IHelp.renderer = :emacs
              > String.help:center
  source -- uses RubyToRuby to print the source for the method
            (experimental)

Changelog:

0.4.5

  Use RI environment variable to pass config to ri (thanks to Parragh Szabolcs.)
  Bugfix for missing stringio (thanks to Marcel M. Cary.)
  Show first thousand hits instead of a mere ten.

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
  released version of RubyToRuby.

License: Ruby‘s

Author: Ilmari Heikkinen <kig misfiring net>

Methods

Classes and Modules

Class IHelp::IHelpAnalyzer
Class IHelp::IHelpDriver
Class IHelp::IHelpIndex
Class IHelp::Renderer

Constants

HELP_VERSION = "0.4.5"

Attributes

help_index  [RW] 
no_colors  [RW]  Don‘t use colors for highlighting search results.
renderer  [RW]  Help renderer to use.
web_browser  [RW]  Web browser to use for html and rubydoc renderers.

Public Class methods

Return RI::ClassDescription / RI::MethodDescription for klass or its method meth, or its instance method meth if instance == true.

[Source]

     # File lib/ihelp.rb, line 368
368:     def generate_help_description(klass, meth=nil, instance=nil)
369:       meth_str = nil
370:       double_colon = false
371:       if meth
372:         meth_str = meth.to_s
373:         if /::|\.|#/ === meth_str # called with e.g."Array#str","String.new"
374:           meth_str, klass_name, instance_help, double_colon =
375:             get_help_klass_info_for_name(meth_str)
376:             klass_ancs = find_ancestors(klass_name, instance)
377:         elsif (/\A[A-Z][a-zA-Z0-9_]*\Z/ === meth_str and # called with e.g. "Array"
378:                not (klass.methods+Kernel.methods).include? meth_str)
379:           meth_str, klass_name, instance_help, double_colon =
380:             get_help_klass_info_for_name(meth_str)
381:             klass_ancs = find_ancestors(klass_name, instance)
382:         else
383:           klass_name, klass_ancs, instance_help =
384:             get_help_klass_info(klass, instance)
385:         end
386:       else
387:         klass_name, klass_ancs, instance_help =
388:           get_help_klass_info(klass, instance)
389:       end
390:       info = get_help_info(meth_str, klass_name, klass_ancs, instance_help,
391:                            instance)
392:       # Retry with method as class if double_colon-splitted and no info
393:       if info.nil? and double_colon
394:         klass_name = [klass_name, meth_str].join("::")
395:         meth_str = nil
396:         klass_ancs = find_ancestors(klass_name, instance)
397:         info = get_help_info(
398:                  meth_str, klass_name, klass_ancs, instance_help, instance)
399:       end
400:       info
401:     end

[Source]

     # File lib/ihelp.rb, line 349
349:     def help_index
350:       @help_index ||= IHelpIndex.new
351:     end

[Source]

     # File lib/ihelp.rb, line 339
339:     def intersect_search_query(str)
340:       a = IHelpAnalyzer.new
341:       t = a.token_stream :content, str.to_s
342:       c = []
343:       n = nil
344:       c << n.text while n = t.next
345:       "(#{c.join(" AND ")})"
346:     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=.

[Source]

     # File lib/ihelp.rb, line 357
357:     def render(info)
358:       IHelp::Renderer.new.send(renderer, info)
359:     end

Returns list of available renderers.

[Source]

     # File lib/ihelp.rb, line 125
125:   def self.renderers
126:     Renderer.instance_methods(false)
127:   end

[Source]

     # File lib/ihelp.rb, line 361
361:     def ri_driver
362:       @ri_driver ||= IHelpDriver.new
363:     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.

[Source]

     # File lib/ihelp.rb, line 329
329:     def search(str, escape_query=true)
330:       raise "No search capability, do you have ferret installed? (gem install ferret)" unless $ihelp_full_text_search
331:       if escape_query
332:         help_index.search(intersect_search_query(str.to_s))
333:       else
334:         help_index.search(str)
335:       end
336:       nil
337:     end

Public Instance methods

Print out help for self.

  If method_name is given, prints help for that method.
  If instance is true, tries to find help only for the instance method.
  If instance is false, tries to find help for the object's method only.
  If instance is nil, checks object's method first, then instance method.

Uses help_description(method_name, instance).

[Source]

     # File lib/ihelp.rb, line 214
214:   def help(method_name=nil, instance=nil)
215:     if $ihelp_full_text_search and (
216:         method_name and method_name.class == String and
217:         self.class == Object and to_s == 'main' and
218:         not method_name =~ /::|\.|#/ and
219:         not method_name =~ /\A[A-Z][a-z0-9A-Z]*\Z/
220:       ) # calling for main
221:       IHelp.search method_name
222:       return
223:     end
224:     if $ihelp_full_text_search and method_name and method_name.to_s.include? " " # phrase search
225:       puts "Searching from docs..."
226:       help_search method_name
227:       return
228:     end
229:     info = help_description(method_name, instance)
230:     if not info
231:       if $ihelp_full_text_search and method_name
232:         puts "No help found for method of that name, searching from docs..."
233:         help_search method_name
234:       else
235:         puts "No help found."
236:       end
237:       return
238:     end
239:     IHelp.render(info)
240:   end

Return RI::ClassDescription / RI::MethodDescription for self or its method meth, or its instance method meth if instance == true.

[Source]

     # File lib/ihelp.rb, line 280
280:   def help_description(method_name=nil, instance=nil)
281:     IHelp.generate_help_description(self, method_name, instance)
282:   end

Returns help string as a HTML REXML::Document with a DIV element as the root.

  If method_name is given, prints help for that method.
  If instance is true, tries to find help only for the instance method.
  If instance is false, tries to find help for the object's method only.
  If instance is nil, checks object's method first, then instance method.
  Returns nil if there is no help to be found.

[Source]

     # File lib/ihelp.rb, line 272
272:   def help_html(method_name=nil, instance=nil)
273:     info = help_description(method_name, instance)
274:     info.to_html if info
275:   end

Searches for str in the documentation of this object.

[Source]

     # File lib/ihelp.rb, line 286
286:   def help_search(str)
287:     raise "No search capability, do you have ferret installed? (gem install ferret)" unless $ihelp_full_text_search
288:     ms = if is_a? Module
289:       instance_methods.map{|im| instance_method im } +
290:       methods.map{|m| method m }
291:     else
292:       methods.map{|m| method m }
293:     end
294:     phrases = ms.map do |m|
295:       mod, met = m.inspect.split(" ",2)[1][0..-2].split(/#|\./)
296:       rmod = mod.scan(/\(([^\)]+)\)/).flatten[0]
297:       rmod ||= mod
298:       rmod.gsub(/[^a-z0-9]/i){|c| "\\"+c }
299:     end.uniq
300:     phrases.delete ""
301:     name_query = phrases.join(" OR ")
302:     query = "(name:(#{name_query})) AND (*:#{IHelp.intersect_search_query str})"
303:     IHelp.search query, false
304:   end

Returns help string in YAML for self.

  If method_name is given, prints help for that method.
  If instance is true, tries to find help only for the instance method.
  If instance is false, tries to find help for the object's method only.
  If instance is nil, checks object's method first, then instance method.
  Returns nil if there is no help to be found.

[Source]

     # File lib/ihelp.rb, line 259
259:   def help_yaml(method_name=nil, instance=nil)
260:     info = help_description(method_name, instance)
261:     info.to_yaml if info
262:   end
ihelp(method_name=nil, instance=nil)

Alias for help

Print out help for instance method method_name. If no method_name given, behaves like help.

[Source]

     # File lib/ihelp.rb, line 247
247:   def instance_help(method_name = nil)
248:     help(method_name, true)
249:   end

[Validate]