rogerdpack-desc_method 0.1.2

data/README

@@ -0,0 +1,63 @@
+A "ruby method describer"--this gem allows you to introspect methods while within irb or ruby-debug.  It reveals everything conceivably known about that method.  This includes source, ri, arity, rdoc comments (on 1.9), etc. etc.
+
+For me it has proved quite useful, and I wouldn't leave home without it [try it--you might really like it].
+
+Examples:
+>>
+ class A; 
+    def go(a); end; 
+  end
+>> A.desc_method :go
+   # it outputs everything it knows about it...arity, source, RI, etc.
+ri for A#go
+Nothing known about A
+(end ri)
+#<UnboundMethod: A#go>     arity: 1
+A#go a
+proc { |a|
+  # do nothing
+}
+
+an example in 1.9:
+>> 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]] )
+
+========= Installation/usage:=====
+Installation:
+$ gem install rogerdpack-desc_method
+Usage:
+>> require 'desc_method'
+>> Class.desc_method :method_name # class or instance method name
+...
+>> instance.desc_method :instance_method_name
+...
+
+other goodies also included:
+Class.desc_class  method # outputs descriptive information about that class--ex:
+>> Object.desc_class
+# outputs RI, methods, etc.
+or 
+>> Object.desc_class :verbose => true
+# outputs RI, method lists including inherited methods, ancestors, constants
+
+Kernel#method is monkey patched to output a "separator" between its inherited and non inherited methods--i.e.
+>> method
+=> [:first, :second, :after_this_are_inherited>>>>>, :some_inherited_method, :another_inherited_method] # adds in the separator
+
+
+This gem wraps (in a very convenient way) functionality provided by Method#source_location, ruby2ruby, etc. Also thanks to manvenu for some original code inspiration, SourceRef (MBARI), and ruby-debug, who made this possible. Thanks guys!
+
+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,170 @@
+# 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 = []
+
+    # 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, created_on: datetime, shipped_on: datetime, order_user_id: integer, order_status_code_id: integer, notes: text, referer: string, order_shipping_type_id: integer, product_cost: float, shipping_cost: float, tax: float, auth_transaction_id: string, promotion_id: integer, shipping_address_id: integer, billing_address_id: integer, order_account_id: integer).get_cc_processor>"
+
+    string = to_s
+
+    if string.include? ')#'
+      # case #<Method: GiftCertsControllerTest(Test::Unit::TestCase)#get>
+      string =~ /\((.*)\)/ # extract out what is between parentheses for the classname
+      class_name = $1
+    elsif string.include?( '(' ) && string.include?( ').' )
+      # case "Method: Order(id:...).class_method"
+      string =~ /Method: (.*)\(/
+      class_name = $1
+    elsif string =~ /Method: (.*)\..*>/
+      # case "#<Method: A.go>"
+      class_name = $1
+    else
+      # case "#<Method: String#strip>"
+      string =~ /Method: (.*)#.*/
+      class_name = $1
+    end
+
+    # now get method name, type
+    string =~ /Method: .*([#\.])(.*)>/ # include the # or .
+    joiner = $1
+    method_name = $2
+    full_name = "#{class_name}#{joiner}#{method_name}"
+    puts "#{to_s}      arity: #{arity}" # TODO add to doc, I want it before ri for now though :)
+
+    # now run default RI for it
+    begin
+      puts '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(' = ')
+        }
+        out = out.join(', ')
+        return out if want_just_summary
+
+        doc << "Parameters: #{method_name}(" + out + ")"
+      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
+      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]
+
+    doc if want_the_description_returned # give them something they can examine
+  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,118 @@
+--- !ruby/object:Gem::Specification 
+name: rogerdpack-desc_method
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- Roger Pack
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-05-16 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: 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: false
+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: 2
+summary: ruby method describer to make it possible to inspect methods [rdoc, signature, etc.] at runtime, for example while debugging.
+test_files: []
+