pry-doc 0.4.2 → 0.4.3

data/lib/pry-doc.rb

@@ -20,20 +20,41 @@ class Pry
   end
 
   module MethodInfo
-    @doc_cache = {}
-    class << self; attr_reader :doc_cache; end
 
     # Convert a method object into the `Class#method` string notation.
     # @param [Method, UnboundMethod] meth
     # @return [String] The method in string receiver notation.
     def self.receiver_notation_for(meth)
-      if meth.owner.ancestors.first == meth.owner
-        "#{meth.owner.name}##{meth.name}"
-      else
+      if is_singleton?(meth)
         "#{meth.owner.to_s[/#<.+?:(.+?)>/, 1]}.#{meth.name}"
+      else
+        "#{meth.owner.name}##{meth.name}"
       end
     end
 
+    # Retrives aliases of a method
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [Array] The aliases of a method if it exists
+    #                 otherwise, return empty array
+    def self.aliases(meth)
+      host        = method_host(meth)
+      method_type = is_singleton?(meth) ? :method : :instance_method
+
+      methods = Pry::Method.send(:all_from_common, host, method_type, false).
+                            map { |m| m.instance_variable_get(:@method) }
+
+      methods.select { |m| host.send(method_type,m.name) == host.send(method_type,meth.name) }.
+              reject { |m| m.name == meth.name }.
+              map    { |m| host.send(method_type,m.name) }
+    end
+
+    # Checks whether method is a singleton (i.e class method)
+    # @param [Method, UnboundMethod] meth
+    # @param [Boolean] true if singleton
+    def self.is_singleton?(meth)
+      meth.owner.ancestors.first != meth.owner
+    end
+
     # Check whether the file containing the method is already cached.
     # @param [Method, UnboundMethod] meth The method object.
     # @return [Boolean] Whether the method is cached.
@@ -44,10 +65,14 @@ class Pry
     def self.registry_lookup(meth)
       obj = YARD::Registry.at(receiver_notation_for(meth))
 
-      # YARD thinks that some methods are on Object when
-      # they're actually on Kernel; so try again on Object if Kernel fails.
-      if obj.nil? && meth.owner == Kernel
-        obj = YARD::Registry.at("Object##{meth.name}")
+      if obj.nil?
+        if !(aliases = aliases(meth)).empty?
+          obj = YARD::Registry.at(receiver_notation_for(aliases.first))
+        elsif meth.owner == Kernel
+          # YARD thinks that some methods are on Object when
+          # they're actually on Kernel; so try again on Object if Kernel fails.
+          obj = YARD::Registry.at("Object##{meth.name}")
+        end
       end
       obj
     end
@@ -71,16 +96,116 @@ class Pry
       end
     end
 
+    # Attempts to find the c source files if method belongs to a gem
+    # and use YARD to parse and cache the source files for display
+    #
+    # @param [Method, UnboundMethod] meth The method object.
+    def self.parse_and_cache_if_gem_cext(meth)
+      if gem_dir = find_gem_dir(meth)
+        if c_files_found?(gem_dir)
+          warn "Scanning and caching *.c files..."
+          YARD.parse("#{gem_dir}/**/*.c")
+        end
+      end
+    end
+
+    # @param [String] root directory path of gem that method belongs to
+    # @return [Boolean] true if c files exist?
+    def self.c_files_found?(gem_dir)
+      Dir.glob("#{gem_dir}/**/*.c").count > 0
+    end
+
+    # @return [Object] The host of the method (receiver or owner).
+    def self.method_host(meth)
+      is_singleton?(meth) ? meth.receiver : meth.owner
+    end
+
+    # FIXME: this is unnecessarily limited to ext/ and lib/ folders
+    # @return [String] The root folder of a given gem directory.
+    def self.gem_root(dir)
+      dir.split(/\/(?:lib|ext)(?:\/|$)/).first
+    end
+
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String] root directory path of gem that method belongs to,
+    #                  nil if could not be found
+    def self.find_gem_dir(meth)
+      host = method_host(meth)
+
+      begin
+        host_source_location, _ =  WrappedModule.new(host).source_location
+        break if host_source_location != nil
+        host = eval(host.namespace_name)
+      end while host
+
+      # we want to exclude all source_locations that aren't gems (i.e
+      # stdlib)
+      if host_source_location && host_source_location =~ %r{/gems/}
+        gem_root(host_source_location)
+      else
+
+        # the WrappedModule approach failed, so try our backup approach
+        gem_dir_from_method(meth)
+      end
+    end
+
+    # Try to guess what the gem name will be based on the name of the module.
+    # We try a few approaches here depending on the `guess` parameter.
+    # @param [String] name The name of the module.
+    # @param [Fixnum] guess The current guessing approach to use.
+    # @return [String, nil] The guessed gem name, or `nil` if out of guesses.
+    def self.guess_gem_name_from_module_name(name, guess)
+      case guess
+      when 0
+        name.downcase
+      when 1
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_')
+      when 2
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_').sub("_", "-")
+      when 3
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('-')
+      when 4
+        name
+      else
+        nil
+      end
+    end
+
+    # Try to recover the gem directory of a gem based on a method object.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String, nil] The located gem directory.
+    def self.gem_dir_from_method(meth)
+      guess = 0
+
+      host = method_host(meth)
+      root_module_name = host.name.split("::").first
+      while gem_name = guess_gem_name_from_module_name(root_module_name, guess)
+        matches = $LOAD_PATH.grep %r{/gems/#{gem_name}} if !gem_name.empty?
+        if matches && matches.any?
+          return gem_root(matches.first)
+        else
+          guess += 1
+        end
+      end
+
+      nil
+    end
+
     # Cache the file that holds the method or return immediately if file is
     # already cached. Return if the method cannot be cached -
-    # i.e is a C method.
+    # i.e is a C stdlib method.
     # @param [Method, UnboundMethod] meth The method object.
     def self.cache(meth)
       file, _ = meth.source_location
-      return if !file
+
       return if is_eval_method?(meth)
       return if cached?(meth)
 
+      if !file
+        parse_and_cache_if_gem_cext(meth)
+        return
+      end
+
       log.enter_level(Logger::FATAL) do
         YARD.parse(file)
       end
@@ -88,4 +213,3 @@ class Pry
   end
 end
 
-

data/lib/pry-doc.rb.orig

@@ -0,0 +1,225 @@
+# pry-doc.rb
+# (C) John Mair (banisterfiend); MIT license
+
+direc = File.dirname(__FILE__)
+
+require "#{direc}/pry-doc/version"
+require "yard"
+
+if RUBY_VERSION =~ /1.9/
+  YARD::Registry.load_yardoc("#{File.dirname(__FILE__)}/pry-doc/core_docs_19")
+else
+  YARD::Registry.load_yardoc("#{File.dirname(__FILE__)}/pry-doc/core_docs_18")
+end
+
+class Pry
+
+  # do not use pry-doc if rbx is active
+  if !Object.const_defined?(:RUBY_ENGINE) || RUBY_ENGINE !~ /rbx/
+    self.config.has_pry_doc = true
+  end
+
+  module MethodInfo
+
+    # Convert a method object into the `Class#method` string notation.
+    # @param [Method, UnboundMethod] meth
+    # @return [String] The method in string receiver notation.
+    def self.receiver_notation_for(meth)
+      if is_singleton?(meth)
+        "#{meth.owner.to_s[/#<.+?:(.+?)>/, 1]}.#{meth.name}"
+      else
+        "#{meth.owner.name}##{meth.name}"
+      end
+    end
+
+    # Retrives aliases of a method
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [Array] The aliases of a method if it exists
+    #                 otherwise, return empty array
+    def self.aliases(meth)
+      host        = method_host(meth)
+      method_type = is_singleton?(meth) ? :method : :instance_method
+
+      methods = Pry::Method.send(:all_from_common, host, method_type, false).
+                            map { |m| m.instance_variable_get(:@method) }
+
+      methods.select { |m| host.send(method_type,m.name) == host.send(method_type,meth.name) }.
+              reject { |m| m.name == meth.name }.
+              map    { |m| host.send(method_type,m.name) }
+    end
+
+    # Checks whether method is a singleton (i.e class method)
+    # @param [Method, UnboundMethod] meth
+    # @param [Boolean] true if singleton
+    def self.is_singleton?(meth)
+      meth.owner.ancestors.first != meth.owner
+    end
+
+    # Check whether the file containing the method is already cached.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [Boolean] Whether the method is cached.
+    def self.cached?(meth)
+      !!registry_lookup(meth)
+    end
+
+    def self.registry_lookup(meth)
+      obj = YARD::Registry.at(receiver_notation_for(meth))
+
+      if obj.nil?
+        if !(aliases = aliases(meth)).empty?
+          obj = YARD::Registry.at(receiver_notation_for(aliases.first))
+        elsif meth.owner == Kernel
+          # YARD thinks that some methods are on Object when
+          # they're actually on Kernel; so try again on Object if Kernel fails.
+          obj = YARD::Registry.at("Object##{meth.name}")
+        end
+      end
+      obj
+    end
+
+    # Retrieve the YARD object that contains the method data.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [YARD::CodeObjects::MethodObject] The YARD data for the method.
+    def self.info_for(meth)
+      cache(meth)
+      registry_lookup(meth)
+    end
+
+    # Determine whether a method is an eval method.
+    # @return [Boolean] Whether the method is an eval method.
+    def self.is_eval_method?(meth)
+      file, _ = meth.source_location
+      if file =~ /(\(.*\))|<.*>/
+        true
+      else
+        false
+      end
+    end
+
+    # Attempts to find the c source files if method belongs to a gem
+    # and use YARD to parse and cache the source files for display
+    #
+    # @param [Method, UnboundMethod] meth The method object.
+    def self.parse_and_cache_if_gem_cext(meth)
+      if gem_dir = find_gem_dir(meth)
+        if c_files_found?(gem_dir)
+          warn "Scanning and caching *.c files..."
+          YARD.parse("#{gem_dir}/ext/**/*.c")
+        end
+      end
+    end
+
+    # @param [String] root directory path of gem that method belongs to
+    # @return [Boolean] true if c files exist?
+    def self.c_files_found?(gem_dir)
+      Dir.glob("#{gem_dir}/ext/**/*.c").count > 0
+    end
+
+    # @return [Object] The host of the method (receiver or owner).
+    def self.method_host(meth)
+      is_singleton?(meth) ? meth.receiver : meth.owner
+    end
+
+    # FIXME: this is unnecessarily limited to ext/ and lib/ folders
+    # @return [String] The root folder of a given gem directory.
+    def self.gem_root(dir)
+      dir.split(/\/(?:lib|ext)(?:\/|$)/).first
+    end
+
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String] root directory path of gem that method belongs to,
+    #                  nil if could not be found
+    def self.find_gem_dir(meth)
+      host = method_host(meth)
+
+      begin
+<<<<<<< HEAD
+        host_source_location, _ =  WrappedModule.new(host).source_location
+        break if host_source_location != nil
+=======
+        host_location, _ =  WrappedModule.new(host).source_location
+        break if host_location
+>>>>>>> 7f4d702f529aba494ca935a89409d579e3b7146c
+        host = eval(host.namespace_name)
+      end while host
+
+<<<<<<< HEAD
+      # we want to exclude all source_locations that aren't gems (i.e
+      # stdlib)
+      if host_source_location && host_source_location =~ %r{/gems/}
+        gem_root(host_source_location)
+=======
+      if host_location
+        gem_root(host_location)
+>>>>>>> 7f4d702f529aba494ca935a89409d579e3b7146c
+      else
+
+        # the WrappedModule approach failed, so try our backup approach
+        gem_dir_from_method(meth)
+      end
+    end
+
+    # Try to guess what the gem name will be based on the name of the module.
+    # We try a few approaches here depending on the `guess` parameter.
+    # @param [String] name The name of the module.
+    # @param [Fixnum] guess The current guessing approach to use.
+    # @return [String, nil] The guessed gem name, or `nil` if out of guesses.
+    def self.guess_gem_name_from_module_name(name, guess)
+      case guess
+      when 0
+        name.downcase
+      when 1
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_')
+      when 2
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('_').sub("_", "-")
+      when 3
+        name.scan(/[A-Z][a-z]+/).map(&:downcase).join('-')
+      when 4
+        name
+      else
+        nil
+      end
+    end
+
+    # Try to recover the gem directory of a gem based on a method object.
+    # @param [Method, UnboundMethod] meth The method object.
+    # @return [String, nil] The located gem directory.
+    def self.gem_dir_from_method(meth)
+      guess = 0
+
+      host = method_host(meth)
+      root_module_name = host.name.split("::").first
+      while gem_name = guess_gem_name_from_module_name(root_module_name, guess)
+        matches = $LOAD_PATH.grep %r{/gems/#{gem_name}} if !gem_name.empty?
+        if matches && matches.any?
+          return gem_root(matches.first)
+        else
+          guess += 1
+        end
+      end
+
+      nil
+    end
+
+    # Cache the file that holds the method or return immediately if file is
+    # already cached. Return if the method cannot be cached -
+    # i.e is a C stdlib method.
+    # @param [Method, UnboundMethod] meth The method object.
+    def self.cache(meth)
+      file, _ = meth.source_location
+
+      return if is_eval_method?(meth)
+      return if cached?(meth)
+
+      if !file
+        parse_and_cache_if_gem_cext(meth)
+        return
+      end
+
+      log.enter_level(Logger::FATAL) do
+        YARD.parse(file)
+      end
+    end
+  end
+end
+

data/lib/pry-doc/version.rb

@@ -1,3 +1,3 @@
 module PryDoc
-  VERSION = "0.4.2"
+  VERSION = "0.4.3"
 end

data/test/test.rb

@@ -4,13 +4,16 @@ require 'rubygems'
 require 'pry'
 require "#{direc}/../lib/pry-doc"
 require "#{direc}/test_helper"
+require "#{direc}/gem_with_cext/gems/sample"
 require 'bacon'
 require 'set'
+require 'fileutils'
 
 puts "Testing pry-doc version #{PryDoc::VERSION}..."
 puts "Ruby version: #{RUBY_VERSION}"
 
 describe PryDoc do
+
   describe "core C methods" do
     it 'should look up core (C) methods' do
       obj = Pry::MethodInfo.info_for(method(:puts))
@@ -66,11 +69,82 @@ describe PryDoc do
     end
   end
 
+  describe "C ext methods" do
+
+    it "should lookup C ext methods" do
+      obj = Pry::MethodInfo.info_for(Sample.instance_method(:unlink))
+      obj.should.not == nil
+    end
+
+    it "should lookup aliased C ext methods" do
+      obj = Pry::MethodInfo.info_for(Sample.instance_method(:remove))
+      obj.should.not == nil
+    end
+
+    it "should lookup C ext instance methods even when its owners don't have any ruby methods" do
+      obj = Pry::MethodInfo.info_for(Sample::A::B.instance_method(:unlink))
+      obj.should.not == nil
+    end
+
+    it "should lookup C ext class methods even when its owners don't have any ruby methods" do
+      obj = Pry::MethodInfo.info_for(Sample::A::B.method(:unlink))
+      obj.should.not == nil
+    end
+  end
+
   describe "C stdlib methods" do
     it "should return nil for C stdlib methods" do
       obj = Pry::MethodInfo.info_for(Readline.method(:readline))
       obj.should == nil
     end
   end
+
+  describe ".aliases" do
+    it "should return empty array if method does not have any alias" do
+      aliases = Pry::MethodInfo.aliases(Sample.instance_method(:some_meth))
+      aliases.should == []
+    end
+
+    it "should return aliases of a (C) method" do
+      orig = Sample.instance_method(:unlink)
+      copy = Sample.instance_method(:remove)
+
+      aliases = Pry::MethodInfo.aliases(orig)
+      aliases.should == [copy]
+
+      aliases = Pry::MethodInfo.aliases(copy)
+      aliases.should == [orig]
+    end
+
+    it "should return aliases of a ruby method" do
+      C.class_eval { alias msg message }
+
+      orig = C.instance_method(:message)
+      copy = C.instance_method(:msg)
+
+      aliases = Pry::MethodInfo.aliases(orig)
+      aliases.should == [copy]
+
+      aliases = Pry::MethodInfo.aliases(copy)
+      aliases.should == [orig]
+    end
+
+    it "should return aliases of protected method" do
+      orig = Sample.instance_method(:unlink_1)
+      copy = Sample.instance_method(:remove_1)
+
+      aliases = Pry::MethodInfo.aliases(orig)
+      aliases.should == [copy]
+    end
+
+    it "should return aliases of private method" do
+      orig = Sample.instance_method(:unlink_2)
+      copy = Sample.instance_method(:remove_2)
+
+      aliases = Pry::MethodInfo.aliases(orig)
+      aliases.should == [copy]
+    end
+  end
+
 end
 

data/test/test_helper.rb

@@ -1,3 +1,11 @@
+direc = File.dirname(__FILE__)
+
 class C
   def message; end
 end
+
+puts
+puts "Building Sample Gem with C Extensions for testing.."
+system("cd #{direc}/gem_with_cext/gems/ext/ && ruby extconf.rb && make")
+puts
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pry-doc
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.4.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-17 00:00:00.000000000 Z
+date: 2012-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70101923678800 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,15 @@ dependencies:
         version: 0.8.1
   type: :runtime
   prerelease: false
-  version_requirements: *70101923678800
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.1
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70101923689680 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +37,15 @@ dependencies:
         version: 0.9.0
   type: :runtime
   prerelease: false
-  version_requirements: *70101923689680
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 0.9.0
 - !ruby/object:Gem::Dependency
   name: bacon
-  requirement: &70101923687600 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,7 +53,12 @@ dependencies:
         version: 1.1.0
   type: :development
   prerelease: false
-  version_requirements: *70101923687600
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
 description: Provides YARD and extended documentation support for Pry
 email: jrmair@gmail.com
 executables: []
@@ -3083,6 +3098,7 @@ files:
 - lib/pry-doc/core_docs_19/proxy_types
 - lib/pry-doc/version.rb
 - lib/pry-doc.rb
+- lib/pry-doc.rb.orig
 - test/test.rb
 - test/test_helper.rb
 - HISTORY
@@ -3109,7 +3125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.16
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Provides YARD and extended documentation support for Pry