In Files

Files

IHelp

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>

Constants

HELP_VERSION

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

generate_help_description(klass, meth=nil, instance=nil) click to toggle source

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

# File lib/ihelp.rb, line 368
def generate_help_description(klass, meth=nil, instance=nil)
  meth_str = nil
  double_colon = false
  if meth
    meth_str = meth.to_s
    if /::|\.|#/ === meth_str # called with e.g."Array#str","String.new"
      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)
    end
  else
    klass_name, klass_ancs, instance_help =
      get_help_klass_info(klass, instance)
  end
  info = get_help_info(meth_str, klass_name, klass_ancs, instance_help,
                       instance)
  # Retry with method as class if double_colon-splitted and no info
  if info.nil? and double_colon
    klass_name = [klass_name, meth_str].join("::")
    meth_str = nil
    klass_ancs = find_ancestors(klass_name, instance)
    info = get_help_info(
             meth_str, klass_name, klass_ancs, instance_help, instance)
  end
  info
end
intersect_search_query(str) click to toggle source
# File lib/ihelp.rb, line 339
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
render(info) click to toggle source

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=.

# File lib/ihelp.rb, line 357
def render(info)
  IHelp::Renderer.new.send(renderer, info)
end
renderers() click to toggle source

Returns list of available renderers.

# File lib/ihelp.rb, line 125
def self.renderers
  Renderer.instance_methods(false)
end
ri_driver() click to toggle source
# File lib/ihelp.rb, line 361
def ri_driver
  @ri_driver ||= IHelpDriver.new
end
search(str, escape_query=true) click to toggle source

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.

# File lib/ihelp.rb, line 329
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

Public Instance Methods

help(method_name=nil, instance=nil) click to toggle source

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).

# File lib/ihelp.rb, line 214
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
    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
Also aliased as: ihelp
help_description(method_name=nil, instance=nil) click to toggle source

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

# File lib/ihelp.rb, line 280
def help_description(method_name=nil, instance=nil)
  IHelp.generate_help_description(self, method_name, instance)
end
help_html(method_name=nil, instance=nil) click to toggle source

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.
# File lib/ihelp.rb, line 272
def help_html(method_name=nil, instance=nil)
  info = help_description(method_name, instance)
  info.to_html if info
end
help_search(str) click to toggle source

Searches for str in the documentation of this object.

# File lib/ihelp.rb, line 286
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]/){|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
help_yaml(method_name=nil, instance=nil) click to toggle source

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.
# File lib/ihelp.rb, line 259
def help_yaml(method_name=nil, instance=nil)
  info = help_description(method_name, instance)
  info.to_yaml if info
end
ihelp(method_name=nil, instance=nil) click to toggle source
Alias for: help
instance_help(method_name = nil) click to toggle source

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

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

[Validate]

Generated with the Darkfish Rdoc Generator 2.