Class: Pry::WrappedModule::Candidate

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
CodeObject::Helpers, Helpers::DocumentationHelpers
Defined in:
lib/pry/wrapped_module/candidate.rb

Overview

This class represents a single candidate for a module/class definition. It provides access to the source, documentation, line and file for a monkeypatch (reopening) of a class/module.

Constant Summary

Constants included from Helpers::DocumentationHelpers

Helpers::DocumentationHelpers::YARD_TAGS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Forwardable

def_private_delegators

Methods included from CodeObject::Helpers

#c_method?, #c_module?, #command?, #module_with_yard_docs?, #real_method_object?

Methods included from Helpers::DocumentationHelpers

#get_comment_content, get_comment_content, process_comment_markup, #process_comment_markup, process_rdoc, #process_rdoc, #process_yardoc, process_yardoc, process_yardoc_tag, #process_yardoc_tag, #strip_comments_from_c_code, strip_comments_from_c_code, #strip_leading_whitespace, strip_leading_whitespace

Constructor Details

#initialize(wrapper, rank) ⇒ Candidate

Returns a new instance of Candidate.

Parameters:

  • wrapper (Pry::WrappedModule) —

    The associated Pry::WrappedModule instance that owns the candidates.

  • rank (Fixnum) —

    The rank of the candidate to retrieve. Passing 0 returns 'primary candidate' (the candidate with largest number of methods), passing 1 retrieves candidate with second largest number of methods, and so on, up to Pry::WrappedModule#number_of_candidates() - 1

Raises:



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/pry/wrapped_module/candidate.rb', line 38

def initialize(wrapper, rank)
  @wrapper = wrapper

  if number_of_candidates <= 0
    raise CommandError, "Cannot find a definition for #{name} module!"
  end

  if rank > (number_of_candidates - 1)
    raise CommandError,
          "No such module candidate. Allowed candidates range is " \
          "from 0 to #{number_of_candidates - 1}"
  end

  @source = @source_location = nil
  @rank = rank
  @file, @line = source_location
end

Instance Attribute Details

#file ⇒ String (readonly) Also known as: source_file

Returns The file where the module definition is located.

Returns:

  • (String) —

    The file where the module definition is located.



14
15
16
 
# File 'lib/pry/wrapped_module/candidate.rb', line 14

def file
  @file
end

#line ⇒ Fixnum (readonly) Also known as: source_line

Returns The line where the module definition is located.

Returns:

  • (Fixnum) —

    The line where the module definition is located.



18
19
20
 
# File 'lib/pry/wrapped_module/candidate.rb', line 18

def line
  @line
end

Instance Method Details

#doc ⇒ String

Returns The documentation for the candidate.

Returns:

  • (String) —

    The documentation for the candidate.

Raises:



70
71
72
73
74
 
# File 'lib/pry/wrapped_module/candidate.rb', line 70

def doc
  return nil if file.nil?

  @doc ||= get_comment_content(Pry::Code.from_file(file).comment_describing(line))
end

#first_line_of_module_definition(file, line) ⇒ Fixnum (private)

Locate the first line of the module definition.

Parameters:

  • file (String) —

    The file that contains the module definition (somewhere).

  • line (Fixnum) —

    The module definition should appear before this line (if it exists).

Returns:

  • (Fixnum) —

    The line where the module is defined. This line number is one-indexed.



99
100
101
102
 
# File 'lib/pry/wrapped_module/candidate.rb', line 99

def first_line_of_module_definition(file, line)
  searchable_lines = lines_for_file(file)[0..(line - 2)]
  searchable_lines.rindex { |v| module_definition_first_line?(v) } + 1
end

#first_method_source_location ⇒ Array (private)

This method is used by Candidate#source_location as a starting point for the search for the candidate's definition.

Returns:

  • (Array) —

    The source location of the base method used to calculate the source location of the candidate.



116
117
118
 
# File 'lib/pry/wrapped_module/candidate.rb', line 116

def first_method_source_location
  @first_method_source_location ||= method_candidates[@rank].first.source_location
end

#last_method_source_location ⇒ Array (private)

Returns The source location of the last method in this candidate's module definition.

Returns:

  • (Array) —

    The source location of the last method in this candidate's module definition.



122
123
124
 
# File 'lib/pry/wrapped_module/candidate.rb', line 122

def last_method_source_location
  @last_method_source_location ||= method_candidates[@rank].last.source_location
end

#module_definition_first_line?(line) ⇒ Boolean (private)

Returns:

  • (Boolean) 


104
105
106
107
108
109
110
 
# File 'lib/pry/wrapped_module/candidate.rb', line 104

def module_definition_first_line?(line)
  mod_type_string = wrapped.class.to_s.downcase
  wrapped_name_last = wrapped.name.split(/::/).last
  /(^|=)\s*#{mod_type_string}\s+(?:(?:\w*)::)*?#{wrapped_name_last}/ =~ line ||
    /^\s*(::)?#{wrapped_name_last}\s*?=\s*?#{wrapped.class}/ =~ line ||
    /^\s*(::)?#{wrapped_name_last}\.(class|instance)_eval/ =~ line
end

#number_of_lines_in_first_chunk ⇒ Integer (private)

Return the number of lines between the start of the class definition and the start of the last method. We use this value so we can quickly grab these lines from the file (without having to check each intervening line for validity, which is expensive) speeding up source extraction.

Returns:

  • (Integer) —

    number of lines.



132
133
134
135
136
 
# File 'lib/pry/wrapped_module/candidate.rb', line 132

def number_of_lines_in_first_chunk
  end_method_line = last_method_source_location.last

  end_method_line - line
end

#source ⇒ String

Returns The source for the candidate, i.e the complete module/class definition.

Returns:

  • (String) —

    The source for the candidate, i.e the complete module/class definition.

Raises:



59
60
61
62
63
64
65
66
 
# File 'lib/pry/wrapped_module/candidate.rb', line 59

def source
  return nil if file.nil?
  return @source if @source

  @source ||= strip_leading_whitespace(
    Pry::Code.from_file(file).expression_at(line, number_of_lines_in_first_chunk)
  )
end

#source_location ⇒ Array?

Returns A [String, Fixnum] pair representing the source location (file and line) for the candidate or nil if no source location found.

Returns:

  • (Array, nil) —

    A [String, Fixnum] pair representing the source location (file and line) for the candidate or nil if no source location found.



79
80
81
82
83
84
85
86
87
88
 
# File 'lib/pry/wrapped_module/candidate.rb', line 79

def source_location
  return @source_location if @source_location

  file, line = first_method_source_location
  return nil unless file.is_a?(String)

  @source_location = [file, first_line_of_module_definition(file, line)]
rescue Pry::RescuableException
  nil
end