| 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'
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>
| HELP_VERSION | = | "0.4.5" |
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
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
# 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=.
# File lib/ihelp.rb, line 357
357: def render(info)
358: IHelp::Renderer.new.send(renderer, info)
359: 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.
# 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
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
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.
# 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.
# 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.
# 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.
# 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