pry 0.12.2 → 0.13.0

data/lib/pry/commands/show_info.rb

@@ -1,215 +1,233 @@
-class Pry
-  class Command::ShowInfo < Pry::ClassCommand
-    extend Pry::Helpers::BaseHelpers
-
-    command_options shellwords: false, interpolate: false
+# frozen_string_literal: true
 
-    def initialize(*)
-      super
+class Pry
+  class Command
+    class ShowInfo < Pry::ClassCommand
+      extend Pry::Helpers::BaseHelpers
 
-      @used_super = nil
-    end
+      command_options shellwords: false, interpolate: false
 
-    def options(opt)
-      opt.on :s, :super, "Select the 'super' method. Can be repeated to traverse the ancestors", as: :count
-      opt.on :l, "line-numbers", "Show line numbers"
-      opt.on :b, "base-one", "Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)"
-      opt.on :a, :all, "Show all definitions and monkeypatches of the module/class"
-    end
+      def initialize(*)
+        super
 
-    def process
-      code_object = Pry::CodeObject.lookup(obj_name, _pry_, super: opts[:super])
-      raise CommandError, no_definition_message if !code_object
+        @used_super = nil
+      end
 
-      @original_code_object = code_object
+      def options(opt)
+        opt.on :s, :super, "Select the 'super' method. Can be repeated to " \
+                           "traverse the ancestors", as: :count
+        opt.on :l, "line-numbers", "Show line numbers"
+        opt.on :b, "base-one", "Show line numbers but start numbering at 1 " \
+                               "(useful for `amend-line` and `play` commands)"
+        opt.on :a, :all, "Show all definitions and monkeypatches of the " \
+                         "module/class"
+      end
 
-      if !obj_name && code_object.c_module? && !opts[:all]
-        result = "Warning: You're inside an object, whose class is defined by means\n" +
-                 "         of the C Ruby API. Pry cannot display the information for\n" +
-                 "         this class."
-        if code_object.candidates.any?
-          result += "\n         However, you can view monkey-patches applied to this class.\n" +
-                    "         Just execute the same command with the '--all' switch."
+      def process
+        code_object = Pry::CodeObject.lookup(obj_name, pry_instance, super: opts[:super])
+        raise CommandError, no_definition_message unless code_object
+
+        @original_code_object = code_object
+
+        if !obj_name && code_object.c_module? && !opts[:all]
+          result = "You're inside an object, whose class is defined by means of " \
+                   "the C Ruby API.\nPry cannot display the information for this " \
+                   "class."
+          if code_object.candidates.any?
+            result += "\nHowever, you can view monkey-patches applied to this " \
+                      "class.\n.Just execute the same command with the '--all' " \
+                      "switch."
+          end
+        elsif show_all_modules?(code_object)
+          # show all monkey patches for a module
+
+          result = content_and_headers_for_all_module_candidates(code_object)
+        else
+          # show a specific code object
+          co = code_object_with_accessible_source(code_object)
+          result = content_and_header_for_code_object(co)
         end
-      elsif show_all_modules?(code_object)
-        # show all monkey patches for a module
 
-        result = content_and_headers_for_all_module_candidates(code_object)
-      else
-        # show a specific code object
-        co = code_object_with_accessible_source(code_object)
-        result = content_and_header_for_code_object(co)
+        set_file_and_dir_locals(code_object.source_file)
+        pry_instance.pager.page result
       end
 
-      set_file_and_dir_locals(code_object.source_file)
-      _pry_.pager.page result
-    end
+      # This method checks whether the `code_object` is a WrappedModule, if it
+      # is, then it returns the first candidate (monkeypatch) with accessible
+      # source (or docs). If `code_object` is not a WrappedModule (i.e a method
+      # or a command) then the `code_object` itself is just returned.
+      #
+      # @return [Pry::WrappedModule, Pry::Method, Pry::Command]
+      def code_object_with_accessible_source(code_object)
+        return code_object unless code_object.is_a?(WrappedModule)
 
-    # This method checks whether the `code_object` is a WrappedModule,
-    # if it is, then it returns the first candidate (monkeypatch) with
-    # accessible source (or docs). If `code_object` is not a WrappedModule (i.e a
-    # method or a command) then the `code_object` itself is just
-    # returned.
-    #
-    # @return [Pry::WrappedModule, Pry::Method, Pry::Command]
-    def code_object_with_accessible_source(code_object)
-      if code_object.is_a?(WrappedModule)
         candidate = code_object.candidates.find(&:source)
-        if candidate
-          return candidate
-        else
-          raise CommandError, no_definition_message if !valid_superclass?(code_object)
+        return candidate if candidate
 
-          @used_super = true
-          code_object_with_accessible_source(code_object.super)
-        end
-      else
-        code_object
+        raise CommandError, no_definition_message unless valid_superclass?(code_object)
+
+        @used_super = true
+        code_object_with_accessible_source(code_object.super)
       end
-    end
 
-    def valid_superclass?(code_object)
-      code_object.super && code_object.super.wrapped != Object
-    end
+      def valid_superclass?(code_object)
+        code_object.super && code_object.super.wrapped != Object
+      end
 
-    def content_and_header_for_code_object(code_object)
-      header(code_object) << content_for(code_object)
-    end
+      def content_and_header_for_code_object(code_object)
+        header(code_object) + content_for(code_object)
+      end
 
-    def content_and_headers_for_all_module_candidates(mod)
-      result = "Found #{mod.number_of_candidates} candidates for `#{mod.name}` definition:\n"
-      mod.number_of_candidates.times do |v|
-        candidate = mod.candidate(v)
-        begin
-          result << "\nCandidate #{v + 1}/#{mod.number_of_candidates}: #{candidate.source_file} @ line #{candidate.source_line}:\n"
-          content = content_for(candidate)
-
-          result << "Number of lines: #{content.lines.count}\n\n" << content
-        rescue Pry::RescuableException
-          result << "\nNo content found.\n"
-          next
+      def content_and_headers_for_all_module_candidates(mod)
+        result = "Found #{mod.number_of_candidates} candidates for " \
+                 "`#{mod.name}` definition:\n"
+        mod.number_of_candidates.times do |v|
+          candidate = mod.candidate(v)
+          begin
+            result += "\nCandidate #{v + 1}/#{mod.number_of_candidates}: " \
+                      "#{candidate.source_file}:#{candidate.source_line}\n"
+            content = content_for(candidate)
+
+            result += "Number of lines: #{content.lines.count}\n\n" + content
+          rescue Pry::RescuableException
+            result += "\nNo content found.\n"
+            next
+          end
         end
+        result
       end
-      result
-    end
 
-    def no_definition_message
-      "Couldn't locate a definition for #{obj_name}"
-    end
+      def no_definition_message
+        "Couldn't locate a definition for #{obj_name}"
+      end
 
-    # Generate a header (meta-data information) for all the code
-    # object types: methods, modules, commands, procs...
-    def header(code_object)
-      file_name, line_num = file_and_line_for(code_object)
-      content = content_for(code_object)
+      # Generate a header (meta-data information) for all the code
+      # object types: methods, modules, commands, procs...
+      def header(code_object)
+        file_name, line_num = file_and_line_for(code_object)
+        content = content_for(code_object)
+
+        h = "\n#{bold('From:')} #{file_name}"
+        h += code_object_header(code_object, line_num)
+        h += "\n#{bold('Number of lines:')} " + "#{content.lines.count}\n\n"
+        if @used_super
+          h += bold('** Warning:')
+          h += " Cannot find code for #{@original_code_object.nonblank_name}. " \
+               "Showing superclass #{code_object.nonblank_name} instead. **\n\n"
+        end
 
-      h = "\n#{bold('From:')} #{file_name} "
-      h << code_object_header(code_object, line_num)
-      h << "\n#{bold('Number of lines:')} " << "#{content.lines.count}\n\n"
-      h << bold('** Warning:') << " Cannot find code for #{@original_code_object.nonblank_name}. Showing superclass #{code_object.nonblank_name} instead. **\n\n" if @used_super
+        if content.lines.none?
+          h += bold('** Warning:')
+          h += " Cannot find code for '#{code_object.name}' (source_location is nil)"
+        end
 
-      if content.lines.none?
-        h << bold('** Warning:') << " Cannot find code for '#{code_object.name}' (source_location is nil)"
+        h
       end
 
-      h
-    end
-
-    def code_object_header(code_object, line_num)
-      if code_object.real_method_object?
-        method_header(code_object, line_num)
+      def code_object_header(code_object, line_num)
+        if code_object.real_method_object?
+          method_header(code_object, line_num)
 
-        # It sucks we have to test for both Pry::WrappedModule and WrappedModule::Candidate,
-        # probably indicates a deep refactor needs to happen in those classes.
-      elsif code_object.is_a?(Pry::WrappedModule) || code_object.is_a?(Pry::WrappedModule::Candidate)
-        module_header(code_object, line_num)
-      else
-        ""
+          # It sucks we have to test for both Pry::WrappedModule and
+          # WrappedModule::Candidate, probably indicates a deep refactor needs
+          # to happen in those classes.
+        elsif code_object.is_a?(Pry::WrappedModule) ||
+              code_object.is_a?(Pry::WrappedModule::Candidate)
+          module_header(code_object, line_num)
+        else
+          ""
+        end
       end
-    end
 
-    def method_header(code_object, line_num)
-      h = ""
-      h << (code_object.c_method? ? "(C Method):" : "@ line #{line_num}:")
-      h << method_sections(code_object)[:owner]
-      h << method_sections(code_object)[:visibility]
-      h << method_sections(code_object)[:signature]
-      h
-    end
+      def method_header(code_object, line_num)
+        h = ""
+        h += (code_object.c_method? ? ' (C Method):' : ":#{line_num}:")
+        h += method_sections(code_object)[:owner]
+        h += method_sections(code_object)[:visibility]
+        h += method_sections(code_object)[:signature]
+        h
+      end
 
-    def module_header(code_object, line_num)
-      h = ""
-      h << "@ line #{line_num}:\n"
-      h << bold(code_object.module? ? "Module" : "Class")
-      h << " #{bold('name:')} #{code_object.nonblank_name}"
+      def module_header(code_object, line_num)
+        h = ""
+        h += ":#{line_num}\n"
+        h += bold(code_object.module? ? "Module" : "Class")
+        h += " #{bold('name:')} #{code_object.nonblank_name}"
 
-      if code_object.number_of_candidates > 1
-        h << (bold("\nNumber of monkeypatches: ") << code_object.number_of_candidates.to_s)
-        h << ". Use the `-a` option to display all available monkeypatches"
+        if code_object.number_of_candidates > 1
+          h += bold("\nNumber of monkeypatches: ")
+          h += code_object.number_of_candidates.to_s
+          h += ". Use the `-a` option to display all available monkeypatches"
+        end
+        h
       end
-      h
-    end
 
-    def method_sections(code_object)
-      {
-        owner: "\n#{bold("Owner:")} #{code_object.owner || "N/A"}\n",
-        visibility: "#{bold("Visibility:")} #{code_object.visibility}",
-        signature: "\n#{bold("Signature:")} #{code_object.signature}"
-      }.merge(header_options) { |key, old, new| (new && old).to_s }
-    end
+      def method_sections(code_object)
+        {
+          owner: "\n#{bold('Owner:')} #{code_object.owner || 'N/A'}\n",
+          visibility: "#{bold('Visibility:')} #{code_object.visibility}",
+          signature: "\n#{bold('Signature:')} #{code_object.signature}"
+        }.merge(header_options) { |_key, old, new| (new && old).to_s }
+      end
 
-    def header_options
-      {
-        owner: true,
-        visibility: true,
-        signature: nil
-      }
-    end
+      def header_options
+        {
+          owner: true,
+          visibility: true,
+          signature: nil
+        }
+      end
 
-    def show_all_modules?(code_object)
-      code_object.is_a?(Pry::WrappedModule) && opts.present?(:all)
-    end
+      def show_all_modules?(code_object)
+        code_object.is_a?(Pry::WrappedModule) && opts.present?(:all)
+      end
 
-    def obj_name
-      @obj_name ||= args.empty? ? nil : args.join(' ')
-    end
+      def obj_name
+        @obj_name ||= args.empty? ? nil : args.join(' ')
+      end
 
-    def use_line_numbers?
-      opts.present?(:b) || opts.present?(:l)
-    end
+      def use_line_numbers?
+        opts.present?(:b) || opts.present?(:l)
+      end
 
-    def start_line_for(code_object)
-      if opts.present?(:'base-one')
-        1
-      else
-        code_object.source_line || 1
+      def start_line_for(code_object)
+        if opts.present?(:'base-one')
+          1
+        else
+          code_object.source_line || 1
+        end
       end
-    end
 
-    # takes into account possible yard docs, and returns yard_file / yard_line
-    # Also adjusts for start line of comments (using start_line_for), which it has to infer
-    # by subtracting number of lines of comment from start line of code_object
-    def file_and_line_for(code_object)
-      if code_object.module_with_yard_docs?
-        [code_object.yard_file, code_object.yard_line]
-      else
-        [code_object.source_file, start_line_for(code_object)]
+      # takes into account possible yard docs, and returns yard_file / yard_line
+      # Also adjusts for start line of comments (using start_line_for), which it
+      # has to infer by subtracting number of lines of comment from start line
+      # of code_object
+      def file_and_line_for(code_object)
+        if code_object.module_with_yard_docs?
+          [code_object.yard_file, code_object.yard_line]
+        else
+          [code_object.source_file, start_line_for(code_object)]
+        end
       end
-    end
 
-    def complete(input)
-      if input =~ /([^ ]*)#([a-z0-9_]*)\z/
-        prefix, search = [$1, $2]
-        methods = begin
-                    Pry::Method.all_from_class(binding.eval(prefix))
-                  rescue RescuableException
-                    return super
-                  end
-        methods.map do |method|
-          [prefix, method.name].join('#') if method.name.start_with?(search)
-        end.compact
-      else
-        super
+      def complete(input)
+        if input =~ /([^ ]*)#([a-z0-9_]*)\z/
+          prefix = Regexp.last_match(1)
+          search = Regexp.last_match(2)
+          methods =
+            begin
+              # rubocop:disable Security/Eval
+              Pry::Method.all_from_class(binding.eval(prefix))
+              # rubocop:enable Security/Eval
+            rescue RescuableException
+              return super
+            end
+          methods.map do |method|
+            [prefix, method.name].join('#') if method.name.start_with?(search)
+          end.compact
+        else
+          super
+        end
       end
     end
   end

data/lib/pry/commands/show_input.rb

@@ -1,17 +1,22 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::ShowInput < Pry::ClassCommand
-    match 'show-input'
-    group 'Editing'
-    description 'Show the contents of the input buffer for the current multi-line expression.'
+  class Command
+    class ShowInput < Pry::ClassCommand
+      match 'show-input'
+      group 'Editing'
+      description 'Show the contents of the input buffer for the current ' \
+                  'multi-line expression.'
 
-    banner <<-'BANNER'
-      Show the contents of the input buffer for the current multi-line expression.
-    BANNER
+      banner <<-'BANNER'
+        Show the contents of the input buffer for the current multi-line expression.
+      BANNER
 
-    def process
-      output.puts Code.new(eval_string).with_line_numbers
+      def process
+        output.puts Code.new(eval_string).with_line_numbers
+      end
     end
-  end
 
-  Pry::Commands.add_command(Pry::Command::ShowInput)
+    Pry::Commands.add_command(Pry::Command::ShowInput)
+  end
 end

data/lib/pry/commands/show_source.rb

@@ -1,53 +1,117 @@
-require 'pry/commands/show_info'
+# frozen_string_literal: true
 
 class Pry
-  class Command::ShowSource < Command::ShowInfo
-    match 'show-source'
-    group 'Introspection'
-    description 'Show the source for a method or class.'
-
-    banner <<-'BANNER'
-      Usage:   show-source [OPTIONS] [METH|CLASS]
-      Aliases: $, show-method
-
-      Show the source for a method or class. Tries instance methods first and then
-      methods by default.
-
-      show-source hi_method
-      show-source hi_method
-      show-source Pry#rep     # source for Pry#rep method
-      show-source Pry         # for Pry class
-      show-source Pry -a      # for all Pry class definitions (all monkey patches)
-      show-source Pry.foo -e  # for class of the return value of expression `Pry.foo`
-      show-source Pry --super # for superclass of Pry (Object class)
-
-      https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method
-    BANNER
-
-    def options(opt)
-      opt.on :e, :eval, "evaluate the command's argument as a ruby expression and show the class its return value"
-      super(opt)
-    end
+  class Command
+    class ShowSource < Command::ShowInfo
+      include Pry::Helpers::DocumentationHelpers
+
+      match 'show-source'
+      group 'Introspection'
+      description 'Show the source for a method or class.'
+
+      banner <<-'BANNER'
+        Usage:   show-source [OPTIONS] [METH|CLASS]
+        Aliases: $, show-method
+
+        Show the source for a method or class. Tries instance methods first and then
+        methods by default.
 
-    def process
-      if opts.present?(:e)
-        obj = target.eval(args.first)
-        self.args = Array.new(1) { Module === obj ? obj.name : obj.class.name }
+        show-source hi_method
+        show-source hi_method
+        show-source Pry#rep     # source for Pry#rep method
+        show-source Pry         # for Pry class
+        show-source Pry -a      # for all Pry class definitions (all monkey patches)
+        show-source Pry.foo -e  # for class of the return value of expression `Pry.foo`
+        show-source Pry --super # for superclass of Pry (Object class)
+        show-source Pry -d      # include documentation
+
+        https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method
+      BANNER
+
+      def options(opt)
+        opt.on :e, :eval, "evaluate the command's argument as a ruby " \
+                          "expression and show the class its return value"
+        opt.on :d, :doc, 'include documentation in the output'
+        super(opt)
+      end
+
+      def process
+        if opts.present?(:e)
+          obj = target.eval(args.first)
+          self.args = Array.new(1) { obj.is_a?(Module) ? obj.name : obj.class.name }
+        end
+
+        super
+      end
+
+      # The source for code_object prepared for display.
+      def content_for(code_object)
+        content = ''
+        if opts.present?(:d)
+          code = Code.new(
+            render_doc_markup_for(code_object), start_line_for(code_object), :text
+          )
+          content += code.with_line_numbers(use_line_numbers?).to_s
+          content += "\n"
+        end
+
+        code = Code.new(
+          code_object.source || [], start_line_for(code_object)
+        )
+        content += code.with_line_numbers(use_line_numbers?).highlighted
+        content
       end
-      super
-    end
 
-    # The source for code_object prepared for display.
-    def content_for(code_object)
-      code = Code.new(
-        code_object.source || [],
-        start_line_for(code_object)
-      )
-      code.with_line_numbers(use_line_numbers?).highlighted
+      # process the markup (if necessary) and apply colors
+      def render_doc_markup_for(code_object)
+        docs = docs_for(code_object)
+
+        if code_object.command?
+          # command '--help' shouldn't use markup highlighting
+          docs
+        else
+          if docs.empty?
+            raise CommandError, "No docs found for: #{obj_name || 'current context'}"
+          end
+
+          process_comment_markup(docs)
+        end
+      end
+
+      # Return docs for the code_object, adjusting for whether the code_object
+      # has yard docs available, in which case it returns those.
+      # (note we only have to check yard docs for modules since they can
+      # have multiple docs, but methods can only be doc'd once so we
+      # dont need to check them)
+      def docs_for(code_object)
+        if code_object.module_with_yard_docs?
+          # yard docs
+          code_object.yard_doc
+        else
+          # normal docs (i.e comments above method/module/command)
+          code_object.doc
+        end
+      end
+
+      # Which sections to include in the 'header', can toggle: :owner,
+      # :signature and visibility.
+      def header_options
+        super.merge signature: true
+      end
+
+      # figure out start line of docs by back-calculating based on
+      # number of lines in the comment and the start line of the code_object
+      # @return [Fixnum] start line of docs
+      def start_line_for(code_object)
+        return 1 if code_object.command? || opts.present?(:'base-one')
+        return 1 unless code_object.source_line
+
+        code_object.source_line - code_object.doc.lines.count
+      end
     end
-  end
 
-  Pry::Commands.add_command(Pry::Command::ShowSource)
-  Pry::Commands.alias_command 'show-method', 'show-source'
-  Pry::Commands.alias_command '$', 'show-source'
+    Pry::Commands.add_command(Pry::Command::ShowSource)
+    Pry::Commands.alias_command 'show-method', 'show-source'
+    Pry::Commands.alias_command '$', 'show-source'
+  end
 end