ri_for 0.3.0

data/README

@@ -0,0 +1,101 @@
+A "run time RI for ruby methods", this gem allows you to query for information about objects' methods at runtime--for example within irb or ruby-debug.  It reveals everything known about the method.  This includes source, ri, arity, rdoc comments (1.9 only), etc.
+
+For me it has proved quite useful, and I wouldn't do a ruby-debug session without it--you might really like it.
+
+Examples:
+
+>> class A; 
+    def go(a); end; 
+   end
+
+>> A.desc_method :go
+#<UnboundMethod: A#go>      arity: 1
+ri for A#go
+Nothing known about A
+(end ri)
+def go(a)
+  # do nothing
+end
+Parameters: go(a)
+
+>> File.desc_method :delete
+ri for File.delete
+----------------------------------------------------------- File::delete
+     File.delete(file_name, ...)  => integer
+     File.unlink(file_name, ...)  => integer
+
+     From Ruby 1.9.1
+------------------------------------------------------------------------
+     Deletes the named files, returning the number of names passed as
+     arguments. Raises an exception on any error. See also +Dir::rmdir+.
+
+(end ri)
+#<Method: File.delete>     arity: -1
+appears to be a c method
+#parameters signature: delete( [[:rest]] )
+
+Or (my favorite) a debug session:
+
+(rdb:1) l=
+...
+ 74       assert(assigns['order'].order_line_items.map(:unit_price).min >= -5)
+...
+(rdb:1) desc_method :assert
+#<Method: StoreControllerTest(Test::Unit::Assertions)#assert>      arity: -2
+ri for Test::Unit::Assertions#assert
+------------------------------------------ Test::Unit::Assertions#assert
+     assert(boolean, message=nil)
+
+     From gem test-unit-2.0.1
+------------------------------------------------------------------------
+     Asserts that +boolean+ is not false or nil.
+
+     Example:
+
+       assert [1, 2].include?(5)
+
+(end ri)
+def assert(boolean, message = nil)
+  _wrap_assertion do
+    assert_block("assert should not be called with a block.") do
+      (not block_given?)
+    end
+    assert_block(build_message(message, "<?> is not true.", boolean)) { boolean }
+  end
+end
+Parameters: assert(boolean, message = nil)
+
+Thus, you can look at methods' source/rdocs without having to step into them.  Deftly convenient.
+
+========= How to Install=====
+$ gem install rogerdpack-desc_method
+or
+$ gem install rogerdpack-desc_method --source http://gems.github.com 
+if you don't have gems.github.com as a gem source.
+
+Usage:
+>> require 'desc_method'
+>> Class.desc_method :method_name # class or instance method name
+...
+>> some_instance.desc_method :method_name
+
+Other goodies included:
+
+Class#desc_class method
+
+An example:
+>> Object.desc_class
+# outputs descriptive info about that class--RI, method list, etc.
+>> Object.desc_class :verbose => true
+# outputs RI, method lists including inherited methods, ancestors, all constants etc.
+
+Kernel#methods has been monkey patched to output a "separator" between its inherited and non inherited methods--i.e.
+>> instance.methods
+=> [:first, :second, :after_this_are_inherited>>>>>, :some_inherited_method, :another_inherited_method] # adds in that separator
+
+I'll probably remove that in a future release since it turns out you can just run Kernel#methods(false) for about much.
+
+=== Thanks ===
+This gem wraps for convenience the functionality of Method#source_location, ruby2ruby, et al, and also contains some code inspiration from manvenu, SourceRef (MBARI), and Python's Method#desc.  It also wouldn't be useful without irb and the ruby-debug folks. Thanks!
+
+Comments/suggestions welcome rogerdpack on gmail or github

data/Rakefile

@@ -0,0 +1,17 @@
+require 'jeweler'
+Jeweler::Tasks.new do |s|
+  s.name = %q{ri_for}
+  s.authors = ["Roger Pack"]
+  s.description = s.summary = %q{ruby method describer to make it possible to inspect methods [rdoc, signature, etc.] at runtime, for example while debugging.}
+  s.email = ["rogerdpack@gmail.comm"]
+
+  s.homepage = %q{http://github.com/rogerdpack/method_describer}
+  s.add_dependency(%q<rdoc>, [">= 2.3"]) # for sane ri lookup times
+  s.add_dependency(%q<require_all>, [">= 1.1"]) # require_rel
+  s.add_dependency(%q<rdp-arguments>, [">= 0.6.4"])
+  s.add_dependency(%q<sane>, ['>= 0.1.2'])
+  s.add_dependency(%q<ParseTree>) # these next two for 1.8 only...
+  s.add_dependency(%q<ruby2ruby>)
+  s.add_development_dependency("rubydoctest")
+end
+

data/TODO

@@ -0,0 +1 @@
+see issues

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/ri_for/class_desc.rb

@@ -0,0 +1,31 @@
+require_rel 'method_ri'
+
+class Class
+  # just runs ri against the class, outputs a big
+  def desc_class options = {}
+    # want_output = false, verbose = false
+    begin
+      puts "begin RI"
+      RDoc::RI::Driver.run [to_s, '--no-pager']
+      puts 'end ri'
+    rescue SystemExit
+      # not found
+    end
+
+    class_methods = methods(false)
+    for ancestor in ancestors[1..-1] # skip the first one, which is yourself
+      class_methods -= ancestor.methods(false)
+    end
+
+    doc = []
+    doc << to_s
+    doc += ["non inherited methods:", instance_methods(false).sort.join(", ")]
+    doc += ['non inherited class methods:', class_methods.sort.join(', ')]
+    doc += ["ancestors:", ancestors.join(', ')] if options[:verbose]
+    doc += ["Constants (possible sub classes):",  constants.join(', ')] if constants.length > 0 && options[:verbose]
+    puts doc
+    doc if options[:want_output]
+  end
+
+end
+

data/lib/ri_for/kernel_new_methods_list.rb

@@ -0,0 +1,20 @@
+=begin rdoc
+ add method methods2 so that it returns lists that are split into two kind of [adds a marker where the inherited methods begin].
+=end
+module Kernel
+  alias :methods_old :methods
+  def methods2 all = true
+    if all
+      # give some marker designating when the inherited methods start
+      (public_methods(false) << :"inherited methods after this point >>") + (public_methods(true) - public_methods(false))
+    else
+      public_methods(false)
+    end
+  end
+end
+
+if $0 == __FILE__
+  class A; end
+  puts 'A.methods', A.methods(true).inspect, A.methods(false).inspect
+  puts 'A.new.methods', A.new.methods.inspect
+end

data/lib/ri_for/method_ri.rb

@@ -0,0 +1,176 @@
+require 'rubygems'
+require 'rdoc'
+require 'rdoc/ri/driver'
+require 'sane'
+
+if RUBY_VERSION < '1.9'
+  require 'ruby2ruby'
+  require 'parse_tree'
+  gem 'rdp-arguments' # TODO why is this necessary?
+  require 'arguments' # rogerdpack-arguments
+end
+
+module SourceLocationDesc
+
+  # add a Method#desc which spits out all it knows about that method
+  # ri, location, local ri, etc.
+  # TODO does this work with class methods?
+  def ri options = {}
+    want_just_summary = options[:want_just_summary]
+    want_the_description_returned = options[:want_the_description_returned]
+    doc = []
+    # to_s is something like "#<Method: String#strip>"
+    # or #<Method: GiftCertsControllerTest(Test::Unit::TestCase)#get>
+    # or "#<Method: A.go>"
+    # or "#<Method: Order(id: integer, order_number: integer).get_cc_processor>"
+    # or "#<Method: Order(id: integer, order_number: integer)(ActiveRecord::Base).get_cc_processor>"
+
+    string = to_s
+
+    # derive class_name
+    parenthese_count = string.count '('
+
+    if parenthese_count== 1
+      # case #<Method: GiftCertsControllerTest(Test::Unit::TestCase)#get>
+      # case #<Method: Order(id: integer, order_number: integer).get_cc_processor>
+      if string.include? "id: " # TODO huh?
+        string =~ /Method: (.+)\(/
+      else
+        string =~ /\(([^\(]+)\)[\.#]/ # extract out what is between last parentheses
+      end
+      class_name = $1
+    elsif parenthese_count == 0
+      # case "#<Method: A.go>"
+      string =~ /Method: ([^#\.]+)/
+      class_name = $1
+    elsif parenthese_count == 2
+      # case "#<Method: Order(id: integer, order_number: integer)(ActiveRecord::Base).get_cc_processor>"
+      string =~ /\(([^\(]+)\)[\.#]/
+      class_name = $1
+    else
+      raise 'bad ' + string
+    end
+
+    # now get method name, type
+    string =~ /Method: .*([#\.])(.*)>/ # include the # or .
+    joiner = $1
+    method_name = $2
+    full_name = "#{class_name}#{joiner}#{method_name} arity #{arity}"
+    sig =  "sig: #{full_name}      arity: #{arity}"
+    doc << sig
+    param_string = sig
+    
+    # now gather up any other information we now about it, in case there are no rdocs, so we can see it early...
+
+    if !(respond_to? :source_location)
+      # pull out names for 1.8
+      begin
+        klass = eval(class_name)
+        # we don't call to_ruby to overcome ruby2ruby bug http://rubyforge.org/tracker/index.php?func=detail&aid=26891&group_id=1513&atid=5921
+        if joiner == '#'
+          raw_code = ParseTree.new.parse_tree_for_method(klass, method_name)
+        else
+          raw_code = ParseTree.new.parse_tree_for_method(klass.singleton_class, method_name)
+        end
+        doc << Ruby2Ruby.new.process(ParseTree.new.process(raw_code))
+        
+        args = Arguments.names(klass, method_name, false) rescue Arguments.names(klass.singleton_class, method_name, false)
+        out = []
+        args.each{|arg_pair|
+          out << arg_pair.join(' = ')
+        } if args
+        out = out.join(', ')
+        param_string = out
+        return out if want_just_summary
+
+        param_string = "Parameters: #{method_name}(" + out + ")" 
+        doc << param_string unless want_the_description_returned
+      rescue Exception => e
+        doc << "appears to be a c method"
+        puts "fail to parse tree: #{class_name} #{e} #{e.backtrace}" if $VERBOSE
+      end
+    else
+      # 1.9.x
+      file, line = source_location
+      param_string = to_s
+      if file
+        # then it's a pure ruby method
+        all_lines = File.readlines(file)
+        head_and_sig = all_lines[0...line]
+        sig = head_and_sig[-1]
+        head = head_and_sig[0..-2]
+
+        doc << sig
+        head.reverse_each do |line|
+          break unless line =~ /^\s*#(.*)/
+          doc.unshift "     " + $1.strip
+        end
+        doc.unshift " at #{file}:#{line}"
+
+        # now the real code will end with 'end' same whitespace as the first
+        sig_white_space = sig.scan(/\W+/)[0]
+        body = all_lines[line..-1]
+        body.each{|line|
+          doc << line
+          if line.start_with?(sig_white_space + "end")
+            break
+          end
+        }
+        already_got_ri = true
+        param_string = sig
+        return sig + "\n" + head[0] if want_just_summary
+      else
+        doc << 'appears to be a c method'
+      end
+      if respond_to? :parameters
+        doc << "Original code signature: %s" % sig.to_s.strip if sig
+        doc << "#parameters signature: %s( %p )" % [name, parameters]
+      end
+    end
+
+    puts doc # always output it since RI does currently [todo make optional I suppose, and non out-putty]
+
+
+    # now run default RI for it
+    begin
+      puts 'Searching ri for ' + full_name + "..."
+      RDoc::RI::Driver.run [full_name, '--no-pager'] unless want_just_summary
+    rescue *[StandardError, SystemExit]
+      # not found
+    ensure
+      puts '(end ri)'
+    end unless already_got_ri
+
+    if want_the_description_returned # give them something they can examine
+      doc
+    else
+      param_string # one liner
+    end
+  end
+
+  alias :desc :ri
+end
+
+class Method; include SourceLocationDesc; end
+class UnboundMethod; include SourceLocationDesc; end
+
+# TODO mixin from a separate module
+class Object
+  # currently rather verbose, but will attempt to describe all it knows about a method
+  def ri_for name, options = {}
+    if self.is_a?(Class) || self.is_a?(Module)
+      # i.e. String.strip
+      begin
+        instance_method(name).ri(options) 
+      rescue NameError => e #allows for Class.instance_method_name
+        puts e, e.backtrace
+        method(name).ri(options) 
+      end
+    else
+      method(name).desc(options)
+    end
+  end
+end
+
+# attribution
+# originally gleaned from http://p.ramaze.net/17901

data/lib/ri_for.rb

@@ -0,0 +1,2 @@
+require 'sane'
+require_rel 'ri_for'

data/test/test_big_name.rb

@@ -0,0 +1,51 @@
+# this comment should never be shown
+module M
+ def go_here
+   345
+ end
+end
+
+class A
+ def self.inspect 
+    "A(id: integer, b: integer)"
+ end
+ # this should never be shown with go2
+ def go
+  33
+ end
+ # some suh-weet rdoc
+ def self.go2
+   34
+ end
+ 
+ include M
+end
+
+
+
+class B
+ def self.go2
+    35
+ end
+end
+
+=begin
+doctest: should parse funky inspect classes [railsy], too
+
+doctest_require: '../lib/ri_for'
+>> $VERBOSE = true
+>> A.ri_for(:go, :want_the_description_returned => true).join('..')
+>> A.ri_for(:go2, :want_the_description_returned => true).join('..')
+>> B.ri_for(:go2, :want_the_description_returned => true).join('..').include?('35')
+=> true
+>> RUBY_VERSION > '1.8' || A.ri_for(:go2, :want_the_description_returned => true).join('..').include?('suh-weet rdoc')
+=> true
+>> A.ri_for(:go2, :want_the_description_returned => true).join('..').include? 'never be shown'
+=> false
+
+# dual whammy... TODO do these test provide full coverage?
+
+>> RUBY_VERSION > '1.8' || A.ri_for(:go_here, :want_the_description_returned => true).join('..').include?('345')
+>> RUBY_VERSION > '1.8' || A.ri_for(:go_here, :want_the_description_returned => true).join('..').include?('345')
+
+=end

data/test/test_method.rb

@@ -0,0 +1,104 @@
+require 'rubygems'
+require 'ffi'
+
+$VERBOSE = true
+
+class A
+ # a suh-weet rdoc
+ def go(a=5)
+  a = 33
+ end
+
+ def self.go22(b=5)
+   b = 3
+ end
+end
+
+=begin
+doctest_require: '../lib/ri_for'
+>> $VERBOSE = true
+>> output = A.ri_for(:go, :want_the_description_returned => true).join(' ')
+>> output.include? 'a = 33'
+=> true
+>> RUBY_VERSION < '1.9' || output.include?('suh-weet')
+=> true
+
+>> output = A.new.ri_for(:go, :want_the_description_returned => true).join(' ')
+>> output.include? 'a = 33'
+=> true
+>> RUBY_VERSION < '1.9' || output.include?('suh-weet')
+=> true
+
+>> output = A.ri_for(:go22, :want_the_description_returned => true).join(' ')
+>> output.include? 'b = 3'
+=> true
+
+it should return you something useful
+
+>> A.ri_for(:go22) == nil
+=> false
+>> A.ri_for(:go) == nil
+=> false
+
+it should work with Module, too
+
+>> FFI::Library.ri_for(:attach_function) == nil
+=> false
+
+=end
+
+
+=begin
+doctest:
+
+it should return true if you run it against a "real" class
+>> String.desc_class(:want_output => true).length > 1
+=> true
+>> class A; end
+>> A.desc_class(:want_output => true).length > 1
+=>  true
+
+it shouldn't report itself as an ancestor of itself
+>> A.desc_class(:want_output => true).grep(/ancestors/).include? '[A]'
+=> false
+
+also lists constants
+>> A.desc_class(:want_output => true, :verbose => true).grep(/constants/i)
+=> [] # should be none since we didn't add any constants to A
+>> class A; B = 3; end
+>> A.desc_class(:want_output => true, :verbose => true).grep(/constants/i).length
+=> 1 # should be none since we didn't add any constants to A
+
+should work with sub methods
+>> String.ri_for(:strip)
+
+doctest_require: '../lib/ri_for'
+=end
+
+=begin 
+doctest:
+>> require 'pathname'
+
+it should display the name
+
+>> Pathname.instance_method(:children).desc(:want_the_description_returned => true).grep(/children/).size > 0
+=>  true # ["#<UnboundMethod: Pathname#children>"]
+
+>> Pathname.instance_method(:children).desc(:want_the_description_returned => true).grep(/Dir.foreach/).size > 0
+=> true  # the code itself
+
+and arity
+>> Pathname.instance_method(:children).desc(:want_the_description_returned => true).grep(/arity/)
+=> ["sig: Pathname#children arity -1      arity: -1"]
+
+# todo: one that is guaranteed to exit you early [no docs at all ever]
+
+wurx with class methods
+>> class A; def self.go(a = 3); a=5; end; end
+>> class A; def go2(a=4) a =7; end; end
+>> A.ri_for(:go)
+>> A.ri_for(:go2)
+
+>> File.ri_for :delete
+
+=end

data/todo

@@ -0,0 +1 @@
+see issues

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification 
+name: ri_for
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Roger Pack
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-02 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdoc
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "2.3"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: require_all
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "1.1"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rdp-arguments
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.6.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: sane
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.1.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ParseTree
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: ruby2ruby
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rubydoctest
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: ruby method describer to make it possible to inspect methods [rdoc, signature, etc.] at runtime, for example while debugging.
+email: 
+- rogerdpack@gmail.comm
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- TODO
+files: 
+- README
+- Rakefile
+- VERSION
+- lib/ri_for.rb
+- lib/ri_for/class_desc.rb
+- lib/ri_for/kernel_new_methods_list.rb
+- lib/ri_for/method_ri.rb
+- test/test_big_name.rb
+- test/test_method.rb
+- todo
+- TODO
+has_rdoc: true
+homepage: http://github.com/rogerdpack/method_describer
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: ruby method describer to make it possible to inspect methods [rdoc, signature, etc.] at runtime, for example while debugging.
+test_files: 
+- test/test_big_name.rb
+- test/test_method.rb