Convert a string to a module.
@param [String] mod_name @param [Binding] target The binding where the lookup takes place. @return [Module, nil] The module or `nil` (if conversion failed). @example
Pry::WrappedModule.from_str("Pry::Code")
# File lib/pry/wrapped_module.rb, line 29 def self.from_str(mod_name, target=TOPLEVEL_BINDING) if safe_to_evaluate?(mod_name, target) Pry::WrappedModule.new(target.eval(mod_name)) else nil end rescue RescuableException nil end
@raise [ArgumentError] if the argument is not a `Module` @param [Module] mod
# File lib/pry/wrapped_module.rb, line 58 def initialize(mod) raise ArgumentError, "Tried to initialize a WrappedModule with a non-module #{mod.inspect}" unless ::Module === mod @wrapped = mod @memoized_candidates = [] @host_file_lines = nil @source = nil @source_location = nil @doc = nil end
Return a candidate for this module of specified rank. A `rank` of 0 is equivalent to the 'primary candidate', which is the module definition with the highest number of methods. A `rank` of 1 is the module definition with the second highest number of methods, and so on. Module candidates are necessary as modules can be reopened multiple times and in multiple places in Ruby, the candidate API gives you access to the module definition representing each of those reopenings. @raise [Pry::CommandError] If the `rank` is out of range. That
is greater than `number_of_candidates - 1`.
@param [Fixnum] rank @return [Pry::WrappedModule::Candidate]
# File lib/pry/wrapped_module.rb, line 240 def candidate(rank) @memoized_candidates[rank] ||= Candidate.new(self, rank) end
@note On JRuby 1.9 and higher, in certain conditions, this method chucks
away its ability to be quick (when there are lots of monkey patches, like in Rails). However, it should be efficient enough on other rubies.
@see github.com/jruby/jruby/issues/525 @return [Enumerator, Array] on JRuby 1.9 and higher returns Array, on
other rubies returns Enumerator
# File lib/pry/wrapped_module.rb, line 256 def candidates enum = generator.new do |y| (0...number_of_candidates).each do |num| y.yield candidate(num) end end Pry::Helpers::BaseHelpers.jruby_19? ? enum.to_a : enum end
Is this strictly a class? @return [Boolean]
# File lib/pry/wrapped_module.rb, line 134 def class? wrapped.instance_of?(Class) end
Returns an array of the names of the constants accessible in the wrapped module. This provides a consistent interface between 1.8 and 1.9 and also avoids the problem of accidentally calling the singleton method `Module.constants`. @param [Boolean] inherit (true) Include the names of constants from
included modules?
# File lib/pry/wrapped_module.rb, line 74 def constants(inherit = true) method = Module.instance_method(:constants).bind(@wrapped) # If we're on 1.8, we have to manually remove ancestors' constants. If # we're on 1.9, though, it's better to use the built-in `inherit` param, # since it doesn't do things like incorrectly remove Pry::Config. if method.arity == 0 consts = method.call if !inherit consts -= (@wrapped.ancestors - [@wrapped]).map(&:constants).flatten end else consts = method.call(inherit) end consts end
Returns documentation for the module. This documentation is for the primary candidate, if you would like documentation for other candidates use `#candidate` to select the candidate you're interested in. @raise [Pry::CommandError] If documentation cannot be found. @return [String] The documentation for the module.
# File lib/pry/wrapped_module.rb, line 196 def doc @doc ||= primary_candidate.doc end
@return [String, nil] The associated file for the module (i.e
the primary candidate: highest ranked monkeypatch).
# File lib/pry/wrapped_module.rb, line 177 def file Array(source_location).first end
@return [Fixnum, nil] The associated line for the module (i.e
the primary candidate: highest ranked monkeypatch).
# File lib/pry/wrapped_module.rb, line 184 def line Array(source_location).last end
Forward method invocations to the wrapped module
# File lib/pry/wrapped_module.rb, line 154 def method_missing(method_name, *args, &block) wrapped.send(method_name, *args, &block) end
The prefix that would appear before methods defined on this class.
i.e. the "String." or "String#" in String.new and String#initialize.
@return String
# File lib/pry/wrapped_module.rb, line 97 def method_prefix if singleton_class? if Module === singleton_instance "#{WrappedModule.new(singleton_instance).nonblank_name}." else "self." end else "#{nonblank_name}#" end end
Is this strictly a module? (does not match classes) @return [Boolean]
# File lib/pry/wrapped_module.rb, line 128 def module? wrapped.instance_of?(Module) end
The name of the Module if it has one, otherwise #<Class:0xf00>.
@return [String]
# File lib/pry/wrapped_module.rb, line 112 def nonblank_name if name.to_s == "" wrapped.inspect else name end end
@return [Fixnum] The number of candidate definitions for the
current module.
# File lib/pry/wrapped_module.rb, line 246 def number_of_candidates method_candidates.count end
# File lib/pry/wrapped_module.rb, line 158 def respond_to?(method_name) super || wrapped.respond_to?(method_name) end
Is this a singleton class? @return [Boolean]
# File lib/pry/wrapped_module.rb, line 122 def singleton_class? wrapped != wrapped.ancestors.first end
Get the instance associated with this singleton class.
@raise ArgumentError: tried to get instance of non singleton class
@return [Object]
# File lib/pry/wrapped_module.rb, line 143 def singleton_instance raise ArgumentError, "tried to get instance of non singleton class" unless singleton_class? if Helpers::BaseHelpers.jruby? wrapped.to_java.attached else @singleton_instance ||= ObjectSpace.each_object(wrapped).detect{ |x| (class << x; self; end) == wrapped } end end
Returns the source for the module. This source is for the primary candidate, if you would like source for other candidates use `#candidate` to select the candidate you're interested in. @raise [Pry::CommandError] If source cannot be found. @return [String] The source for the module.
# File lib/pry/wrapped_module.rb, line 207 def source @source ||= primary_candidate.source end
Retrieve the source location of a module. Return value is in same format as Pry::Method#source_location. If the source location cannot be found this method returns `nil`.
@param [Module] mod The module (or class). @return [Array<String, Fixnum>, nil] The source location of the
module (or class), or %xnil` if no source location found.
# File lib/pry/wrapped_module.rb, line 169 def source_location @source_location ||= primary_candidate.source_location rescue Pry::RescuableException nil end
@param [Fixnum] times How far to travel up the ancestor chain. @return [Pry::WrappedModule, nil] The wrapped module that is the
superclass. When %xself` is a %xModule` then return the nth ancestor, otherwise (in the case of classes) return the nth ancestor that is a class.
# File lib/pry/wrapped_module.rb, line 276 def super(times=1) return self if times.zero? if wrapped.is_a?(Class) sup = ancestors.select { |v| v.is_a?(Class) }[times] else sup = ancestors[times] end Pry::WrappedModule(sup) if sup end
@return [String] Return the YARD docs for this module.
# File lib/pry/wrapped_module.rb, line 224 def yard_doc YARD::Registry.at(name).docstring.to_s if yard_docs? end
@return [Boolean] Whether YARD docs are available for this module.
# File lib/pry/wrapped_module.rb, line 266 def yard_docs? !!(defined?(YARD) && YARD::Registry.at(name)) end
@return [String] Return the associated file for the
module from YARD, if one exists.
# File lib/pry/wrapped_module.rb, line 213 def yard_file YARD::Registry.at(name).file if yard_docs? end
@return [Fixnum] Return the associated line for the
module from YARD, if one exists.
# File lib/pry/wrapped_module.rb, line 219 def yard_line YARD::Registry.at(name).line if yard_docs? end