pry-doc 0.9.0 → 0.10.0

data/lib/pry-doc/pry_ext/method_info.rb

@@ -0,0 +1,188 @@
+class Pry
+  module MethodInfo
+    class << self
+      ##
+      # 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 info_for(meth)
+        cache(meth)
+        registry_lookup(meth)
+      end
+
+      ##
+      # Retrieves aliases of the given method.
+      #
+      # @param [Method, UnboundMethod] meth The method object
+      # @return [Array<UnboundMethod>] the aliases of the given method if they
+      #   exist, otherwise an empty array
+      def aliases(meth)
+        owner = meth.owner
+        name = meth.name
+
+        (owner.instance_methods + owner.private_instance_methods).uniq.map do |m|
+          aliased_method = owner.__send__(:instance_method, m)
+
+          next unless aliased_method == owner.__send__(:instance_method, name)
+          next if m == name
+          aliased_method
+        end.compact!
+      end
+
+      ##
+      # FIXME: this is unnecessarily limited to ext/ and lib/ directories.
+      #
+      # @return [String] the root directory of a given gem directory
+      def gem_root(dir)
+        return unless (index = dir.rindex(%r(/(?:lib|ext)(?:/|$))))
+        dir[0..index-1]
+      end
+
+      private
+
+      ##
+      # Convert a method object into the `Class#method` string notation.
+      #
+      # @param [Method, UnboundMethod] meth
+      # @return [String] the method in string receiver notation
+      # @note This mess is needed to support all the modern Rubies. Somebody has
+      #   to figure out a better way to distinguish between class methods and
+      #   instance methods.
+      def receiver_notation_for(meth)
+        match = meth.inspect.match(/\A#<(?:Unbound)?Method: (.+)([#\.].+?)(?:\(.+\))?>\z/)
+        owner = meth.owner.to_s.sub(/#<.+?:(.+?)>/, '\1')
+        name = match[2]
+        name.sub!('#', '.') if match[1] =~ /\A#<Class:/
+        owner + name
+      end
+
+      ##
+      # Checks whether `meth` is a class method.
+      #
+      # @param [Method, UnboundMethod] meth The method to check
+      # @return [Boolean] true if singleton, otherwise false
+      def is_singleton?(meth)
+        receiver_notation_for(meth).include?('.')
+      end
+
+      def registry_lookup(meth)
+        if (obj = YARD::Registry.at(receiver_notation_for(meth)))
+          return obj
+        end
+
+        if (aliases = aliases(meth)).any?
+          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.
+          YARD::Registry.at("Object##{meth.name}")
+        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 parse_and_cache_if_gem_cext(meth)
+        return unless (gem_dir = find_gem_dir(meth))
+
+        path = "#{gem_dir}/**/*.c"
+        return if Dir.glob(path).none?
+
+        puts "Scanning and caching *.c files..."
+        YARD.parse(path)
+      end
+
+      ##
+      # @return [Object] the host of the method (receiver or owner)
+      def method_host(meth)
+        is_singleton?(meth) && Module === meth.receiver ? meth.receiver : meth.owner
+      end
+
+      ##
+      # @param [Method, UnboundMethod] meth The method object
+      # @return [String, nil] root directory path of gem that method belongs to
+      #   or nil if could not be found
+      def find_gem_dir(meth)
+        host = method_host(meth)
+
+        begin
+          host_source_location, _ =  WrappedModule.new(host).source_location
+          break if host_source_location != nil
+          return unless host.name
+          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.
+      #
+      # @param [String] name The name of the module
+      # @return [Enumerator] the enumerator which enumerates on possible names
+      #   we try to guess
+      def guess_gem_name(name)
+        scanned_name = name.scan(/[A-z]+/).map(&:downcase)
+
+        Enumerator.new do |y|
+          y << name.downcase
+          y << scanned_name.join('_')
+          y << scanned_name.join('_').sub('_', '-')
+          y << scanned_name.join('-')
+          y << name
+        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 gem_dir_from_method(meth)
+        return unless (host = method_host(meth)).name
+
+        guess_gem_name(host.name.split('::').first).each do |guess|
+          matches = $LOAD_PATH.grep(%r(/gems/#{guess}))
+          return gem_root(matches.first) if matches.any?
+        end
+
+        nil
+      end
+
+      ##
+      # Caches the file that holds the method.
+      #
+      # Cannot cache C stdlib and eval methods.
+      #
+      # @param [Method, UnboundMethod] meth The method object.
+      def cache(meth)
+        file, _ = meth.source_location
+
+        # Eval methods can't be cached.
+        return if file =~ /(\(.*\))|<.*>/
+
+        # No need to cache already cached methods.
+        return if registry_lookup(meth)
+
+        unless file
+          parse_and_cache_if_gem_cext(meth)
+          return
+        end
+
+        log.enter_level(Logger::FATAL) do
+          YARD.parse(file)
+        end
+      end
+    end
+  end
+end

data/lib/pry-doc/version.rb

@@ -1,3 +1,3 @@
 module PryDoc
-  VERSION = '0.9.0'
+  VERSION = '0.10.0'
 end

data/pry-doc.gemspec

@@ -20,9 +20,9 @@ DESCR
   s.require_paths = ["lib"]
   s.files = `git ls-files`.split("\n")
 
-  s.add_dependency 'yard', "~> 0.8"
+  s.add_dependency 'yard', "~> 0.9"
   s.add_dependency 'pry', "~> 0.9"
-  s.add_development_dependency 'latest_ruby', "~> 0.0"
-  s.add_development_dependency 'bacon', "~> 1.1"
+  s.add_development_dependency 'latest_ruby', '~> 0.0'
+  s.add_development_dependency 'rspec', '~> 3.5'
   s.add_development_dependency 'rake', "~> 10.0"
 end

data/spec/helper.rb

@@ -1,3 +1,11 @@
+require 'pry-doc'
+
+RSpec.configure do |c|
+  c.order = 'random'
+  c.color = true
+  c.disable_monkey_patching!
+end
+
 direc = File.dirname(__FILE__)
 
 class C
@@ -8,4 +16,3 @@ puts
 puts "Building Sample Gem with C Extensions for testing.."
 system("cd #{direc}/gem_with_cext/gems/ext/ && ruby extconf.rb && make")
 puts
-

data/spec/pry-doc_spec.rb

@@ -1,11 +1,9 @@
 direc = File.dirname(__FILE__)
 
-require 'rubygems'
 require 'pry'
 require "#{direc}/../lib/pry-doc"
 require "#{direc}/helper"
 require "#{direc}/gem_with_cext/gems/sample"
-require 'bacon'
 require 'set'
 require 'fileutils'
 require 'readline'
@@ -13,33 +11,33 @@ require 'readline'
 puts "Testing pry-doc version #{PryDoc::VERSION}..."
 puts "Ruby version: #{RUBY_VERSION}"
 
-describe PryDoc do
+RSpec.describe PryDoc do
 
   describe "core C methods" do
     it 'should look up core (C) methods' do
       obj = Pry::MethodInfo.info_for(method(:puts))
-      obj.source.should.not == nil
+      expect(obj.source).not_to be_nil
     end
 
     it 'should look up core (C) instance methods' do
-      Module.module_eval do
-        obj = Pry::MethodInfo.info_for(instance_method(:include))
-        obj.source.should.not == nil
+      obj = Module.module_eval do
+        Pry::MethodInfo.info_for(instance_method(:include))
       end
+      expect(obj.source).not_to be_nil
     end
 
     it 'should look up core (C) class method (by Method object)' do
-      Module.module_eval do
-        obj = Pry::MethodInfo.info_for(Dir.method(:glob))
-        obj.source.should.not == nil
+      obj = Module.module_eval do
+        Pry::MethodInfo.info_for(Dir.method(:glob))
       end
+      expect(obj.source).not_to be_nil
     end
 
     it 'should look up core (C) class method (by UnboundMethod object)' do
-      Module.module_eval do
-        obj = Pry::MethodInfo.info_for(class << Dir; instance_method(:glob); end)
-        obj.source.should.not == nil
+      obj = Module.module_eval do
+        Pry::MethodInfo.info_for(class << Dir; instance_method(:glob); end)
       end
+      expect(obj.source).not_to be_nil
     end
   end
 
@@ -47,26 +45,26 @@ describe PryDoc do
     it 'should return nil for eval methods' do
       TOPLEVEL_BINDING.eval("def hello; end")
       obj = Pry::MethodInfo.info_for(method(:hello))
-      obj.should == nil
+      expect(obj).to be_nil
     end
   end
 
   describe "pure ruby methods" do
     it 'should look up ruby methods' do
       obj = Pry::MethodInfo.info_for(C.new.method(:message))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
 
     it 'should look up ruby instance methods' do
       obj = Pry::MethodInfo.info_for(C.instance_method(:message))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
   end
 
   describe "Ruby stdlib methods" do
     it "should look up ruby stdlib method" do
       obj = Pry::MethodInfo.info_for(Set.instance_method(:union))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
   end
 
@@ -74,42 +72,42 @@ describe PryDoc do
 
     it "should lookup C ext methods" do
       obj = Pry::MethodInfo.info_for(Sample.instance_method(:gleezor))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
 
     it "should lookup aliased C ext methods" do
       obj = Pry::MethodInfo.info_for(Sample.instance_method(:remove))
-      obj.should.not == nil
+      expect(obj).not_to be_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(:gleezor))
-      obj.should.not == nil
+      expect(obj).not_to be_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(:gleezor))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
   end
 
   describe "C stdlib methods" do
     it "finds them" do
       obj = Pry::MethodInfo.info_for(Readline.method(:readline))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
 
     it "finds well hidden docs like BigDecimal docs" do
       require 'bigdecimal'
       obj = Pry::MethodInfo.info_for(BigDecimal.instance_method(:finite?))
-      obj.should.not == nil
+      expect(obj).not_to be_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 == []
+      expect(aliases).to be_empty
     end
 
     it "should return aliases of a (C) method" do
@@ -117,10 +115,10 @@ describe PryDoc do
       copy = Sample.instance_method(:remove)
 
       aliases = Pry::MethodInfo.aliases(orig)
-      aliases.should == [copy]
+      expect(aliases).to eq([copy])
 
       aliases = Pry::MethodInfo.aliases(copy)
-      aliases.should == [orig]
+      expect(aliases).to eq([orig])
     end
 
     it "should return aliases of a ruby method" do
@@ -130,10 +128,10 @@ describe PryDoc do
       copy = C.instance_method(:msg)
 
       aliases = Pry::MethodInfo.aliases(orig)
-      aliases.should == [copy]
+      expect(aliases).to eq([copy])
 
       aliases = Pry::MethodInfo.aliases(copy)
-      aliases.should == [orig]
+      expect(aliases).to eq([orig])
     end
 
     it "should return aliases of protected method" do
@@ -141,7 +139,7 @@ describe PryDoc do
       copy = Sample.instance_method(:remove_1)
 
       aliases = Pry::MethodInfo.aliases(orig)
-      aliases.should == [copy]
+      expect(aliases).to eq([copy])
     end
 
     it "should return aliases of private method" do
@@ -149,7 +147,7 @@ describe PryDoc do
       copy = Sample.instance_method(:remove_2)
 
       aliases = Pry::MethodInfo.aliases(orig)
-      aliases.should == [copy]
+      expect(aliases).to eq([copy])
     end
 
     it 'does not error when given a singleton method' do
@@ -157,16 +155,15 @@ describe PryDoc do
         def self.my_method; end
       end
 
-      lambda { Pry::MethodInfo.aliases(c.method(:my_method)) }.should.not.raise NameError
+      expect { Pry::MethodInfo.aliases(c.method(:my_method)) }.not_to raise_error
     end
   end
 
   describe ".gem_root" do
     it "should return the path to the gem" do
       path = Pry::WrappedModule.new(Sample).source_location[0]
-
-      Pry::MethodInfo.gem_root(path).should ==
-        File.expand_path("gem_with_cext/gems", direc)
+      expect(Pry::MethodInfo.gem_root(path)).
+        to eq(File.expand_path("gem_with_cext/gems", direc))
     end
 
     it "should not be fooled by a parent 'lib' or 'ext' dir" do
@@ -174,16 +171,16 @@ describe PryDoc do
              "1.9.1/gems/activesupport-4.0.2/lib/active_support/"\
              "core_ext/kernel/reporting.rb"
 
-      Pry::MethodInfo.gem_root(path).should ==
-        "/foo/.rbenv/versions/1.9.3-p429/lib/ruby/"\
-        "gems/1.9.1/gems/activesupport-4.0.2"
+      expect(Pry::MethodInfo.gem_root(path))
+        .to eq('/foo/.rbenv/versions/1.9.3-p429/lib/ruby/' \
+               'gems/1.9.1/gems/activesupport-4.0.2')
     end
   end
 
   describe "1.9 and higher specific docs" do
     it "finds Kernel#require_relative" do
       obj = Pry::MethodInfo.info_for(Kernel.instance_method(:require_relative))
-      obj.should.not == nil
+      expect(obj).not_to be_nil
     end
   end
 
@@ -192,7 +189,7 @@ describe PryDoc do
     describe "2.0 specific docs" do
       it "finds Module#refine" do
         obj = Pry::MethodInfo.info_for(Module.instance_method(:refine))
-        obj.should.not == nil
+        expect(obj).not_to be_nil
       end
     end
   end