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