desc_method 0.1.5

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/lib/desc_method.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'sane'
+require_rel 'method_describer'

data/lib/method_describer/class_desc.rb

@@ -0,0 +1,56 @@
+require_rel 'method_desc'
+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
+
+=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.desc_method(:strip)
+
+doctest_require: '../method_desc'
+=end

data/lib/method_describer/kernel_new_methods_list.rb

@@ -0,0 +1,20 @@
+=begin rdoc
+ Supplement [monkey patch] Kernel#methods 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 methods 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/method_describer/method_desc.rb

@@ -0,0 +1,186 @@
+# originally gleaned from http://p.ramaze.net/17901
+require 'rubygems'
+require 'rdoc'
+require 'rdoc/ri/driver'
+require 'sane'
+begin
+  gem 'arguments' # TODO why is this necessary?
+  require 'arguments' # rogerdpack-arguments
+rescue LoadError
+  require 'arguments' # 1.9
+end
+require 'ruby2ruby'
+
+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 desc want_just_summary = false, want_the_description_returned = false
+    doc = []
+    #_dbg
+    # 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}"
+    puts "sig: #{to_s}      arity: #{arity}"
+    # TODO add to doc, I want it before ri for now though, and only once, so not there yet :)
+
+    # 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
+    end
+    puts '(end ri)'
+
+    # now gather up any other information we now about it, in case there are no rdocs
+
+    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 == '#'
+          doc << RubyToRuby.new.process(ParseTree.translate(klass, method_name))
+        else
+          doc << RubyToRuby.new.process(ParseTree.translate(klass.singleton_class, method_name))
+        end
+        args = Arguments.names( klass, method_name) rescue Arguments.names(klass.singleton_class, method_name)
+        out = []
+        args.each{|arg_pair|
+          out << arg_pair.join(' = ')
+        } if args
+        out = out.join(', ')
+        return out if want_just_summary
+
+        param_string = "Parameters: #{method_name}(" + out + ")" 
+        doc << param_string unless want_the_description_returned
+      rescue Exception => e
+
+        puts "fail to parse tree: #{class_name} #{e} #{e.backtrace}" if $VERBOSE
+      end
+    else
+      # 1.9.x
+      file, line = source_location
+      if file
+        # then it's a pure ruby method
+        doc << "at #{file}:#{line}"
+        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
+
+        # 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
+        }
+        # how do I get the rest now?
+        return sig + "\n" + head[0] if want_just_summary
+      else
+        doc << 'appears to be a c method'
+      end
+      param_string = to_s
+      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]
+
+    if want_the_description_returned # give them something they can examine
+      doc
+    else
+      param_string
+    end
+  end
+
+  named_args_for :desc # just for fun, tests use it too, plus it should actually wurk without interfering...I think
+
+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 desc_method name, options = {}
+    if self.is_a? Class
+      # i.e. String.strip
+      instance_method(name).desc(options) rescue method(name).desc(options) # rescue allows for Class.instance_method_name
+    else
+      method(name).desc(options)
+    end
+  end
+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>"]
+
+and arity
+>> Pathname.instance_method(:children).desc(:want_the_description_returned => true).grep(/arity/)
+=> ["#<UnboundMethod: Pathname#children>     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.desc_method(:go)
+>> A.desc_method(:go2)
+
+>> File.desc_method :delete
+
+=end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification 
+name: desc_method
+version: !ruby/object:Gem::Version 
+  version: 0.1.5
+platform: ruby
+authors: 
+- Roger Pack
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-29 00:00:00 -06: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: rogerdpack-arguments
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: rogerdpack-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: 
+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: []
+
+files: 
+- README
+- lib/desc_method.rb
+- lib/method_describer/class_desc.rb
+- lib/method_describer/kernel_new_methods_list.rb
+- lib/method_describer/method_desc.rb
+has_rdoc: true
+homepage: http://github.com/rogerdpack/method_describer
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+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: []
+