Module: IHelp

Included in:
Object, Object
Defined in:
lib/ihelp.rb,
lib/ihelp.rb

Overview

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

Defined Under Namespace

Classes: IHelpAnalyzer, IHelpDriver, IHelpIndex, Renderer

Constant Summary collapse

HELP_VERSION = 
"0.4.4"

Class Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Class Attribute Details

.help_index ⇒ Object

Returns the value of attribute help_index.



343
344
345
 
# File 'lib/ihelp.rb', line 343

def help_index
  @help_index
end

.no_colors ⇒ Object

Don’t use colors for highlighting search results.



311
312
313
 
# File 'lib/ihelp.rb', line 311

def no_colors
  @no_colors
end

.renderer ⇒ Object

Help renderer to use.



305
306
307
 
# File 'lib/ihelp.rb', line 305

def renderer
  @renderer
end

.web_browser ⇒ Object

Web browser to use for html and rubydoc renderers.



308
309
310
 
# File 'lib/ihelp.rb', line 308

def web_browser
  @web_browser
end

Class Method Details

.generate_help_description(klass, meth = nil, instance = nil) ⇒ Object

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



363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
 
# File 'lib/ihelp.rb', line 363

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) ⇒ Object 



334
335
336
337
338
339
340
341
 
# File 'lib/ihelp.rb', line 334

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) ⇒ Object

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



352
353
354
 
# File 'lib/ihelp.rb', line 352

def render(info)
  IHelp::Renderer.new.send(renderer, info)
end

.renderers ⇒ Object

Returns list of available renderers.



120
121
122
 
# File 'lib/ihelp.rb', line 120

def self.renderers
  Renderer.instance_methods(false)
end

.ri_driver ⇒ Object 



356
357
358
 
# File 'lib/ihelp.rb', line 356

def ri_driver
  @ri_driver ||= IHelpDriver.new
end

.search(str, escape_query = true) ⇒ Object

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.



324
325
326
327
328
329
330
331
332
 
# File 'lib/ihelp.rb', line 324

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

Instance Method Details

#help(method_name = nil, instance = nil) ⇒ Object Also known as: ihelp

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



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/ihelp.rb', line 209

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

#help_description(method_name = nil, instance = nil) ⇒ Object

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



275
276
277
 
# File 'lib/ihelp.rb', line 275

def help_description(method_name=nil, instance=nil)
  IHelp.generate_help_description(self, method_name, instance)
end

#help_html(method_name = nil, instance = nil) ⇒ Object

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.



267
268
269
270
 
# File 'lib/ihelp.rb', line 267

def help_html(method_name=nil, instance=nil)
  info = help_description(method_name, instance)
  info.to_html if info
end

#help_search(str) ⇒ Object

Searches for str in the documentation of this object.



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
 
# File 'lib/ihelp.rb', line 281

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

#help_yaml(method_name = nil, instance = nil) ⇒ Object

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.



254
255
256
257
 
# File 'lib/ihelp.rb', line 254

def help_yaml(method_name=nil, instance=nil)
  info = help_description(method_name, instance)
  info.to_yaml if info
end

#instance_help(method_name = nil) ⇒ Object

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



242
243
244
 
# File 'lib/ihelp.rb', line 242

def instance_help(method_name = nil)
  help(method_name, true)
end