pry 0.10.4 → 0.13.0

data/lib/pry/commands/show_source.rb

@@ -1,50 +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.new(code_object.source, start_line_for(code_object)).
-        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

data/lib/pry/commands/stat.rb

@@ -1,40 +1,44 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::Stat < Pry::ClassCommand
-    match 'stat'
-    group 'Introspection'
-    description 'View method information and set _file_ and _dir_ locals.'
-    command_options :shellwords => false
+  class Command
+    class Stat < Pry::ClassCommand
+      match 'stat'
+      group 'Introspection'
+      description 'View method information and set _file_ and _dir_ locals.'
+      command_options shellwords: false
 
-    banner <<-'BANNER'
-        Usage: stat [OPTIONS] [METH]
+      banner <<-'BANNER'
+          Usage: stat [OPTIONS] [METH]
 
-        Show method information for method METH and set _file_ and _dir_ locals.
+          Show method information for method METH and set _file_ and _dir_ locals.
 
-        stat hello_method
-    BANNER
+          stat hello_method
+      BANNER
 
-    def options(opt)
-      method_options(opt)
-    end
+      def options(opt)
+        method_options(opt)
+      end
+
+      def process
+        meth = method_object
+        aliases = meth.aliases
 
-    def process
-      meth = method_object
-      aliases = meth.aliases
-
-      output.puts unindent <<-EOS
-        Method Information:
-        --
-        Name: #{meth.name}
-        Alias#{ "es" if aliases.length > 1 }: #{ aliases.any? ? aliases.join(", ") : "None." }
-        Owner: #{meth.owner ? meth.owner : "Unknown"}
-        Visibility: #{meth.visibility}
-        Type: #{meth.is_a?(::Method) ? "Bound" : "Unbound"}
-        Arity: #{meth.arity}
-        Method Signature: #{meth.signature}
-        Source Location: #{meth.source_location ? meth.source_location.join(":") : "Not found."}
-      EOS
+        output.puts(unindent(<<-OUTPUT))
+          Method Information:
+          --
+          Name: #{meth.name}
+          Alias#{'es' if aliases.length > 1}: #{aliases.any? ? aliases.join(', ') : 'None.'}
+          Owner: #{meth.owner || 'Unknown'}
+          Visibility: #{meth.visibility}
+          Type: #{meth.is_a?(::Method) ? 'Bound' : 'Unbound'}
+          Arity: #{meth.arity}
+          Method Signature: #{meth.signature}
+          Source Location: #{meth.source_location ? meth.source_location.join(':') : 'Not found.'}
+        OUTPUT
+      end
     end
-  end
 
-  Pry::Commands.add_command(Pry::Command::Stat)
+    Pry::Commands.add_command(Pry::Command::Stat)
+  end
 end

data/lib/pry/commands/switch_to.rb

@@ -1,23 +1,29 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::SwitchTo < Pry::ClassCommand
-    match 'switch-to'
-    group 'Navigating Pry'
-    description 'Start a new subsession on a binding in the current stack.'
+  class Command
+    class SwitchTo < Pry::ClassCommand
+      match 'switch-to'
+      group 'Navigating Pry'
+      description 'Start a new subsession on a binding in the current stack.'
 
-    banner <<-'BANNER'
-      Start a new subsession on a binding in the current stack (numbered by nesting).
-    BANNER
+      banner <<-'BANNER'
+        Start a new subsession on a binding in the current stack (numbered by nesting).
+      BANNER
 
-    def process(selection)
-      selection = selection.to_i
+      def process(selection)
+        selection = selection.to_i
 
-      if selection < 0 || selection > _pry_.binding_stack.size - 1
-        raise CommandError, "Invalid binding index #{selection} - use `nesting` command to view valid indices."
-      else
-        Pry.start(_pry_.binding_stack[selection])
+        if selection < 0 || selection > pry_instance.binding_stack.size - 1
+          raise CommandError,
+                "Invalid binding index #{selection} - use `nesting` command " \
+                "to view valid indices."
+        else
+          Pry.start(pry_instance.binding_stack[selection])
+        end
       end
     end
-  end
 
-  Pry::Commands.add_command(Pry::Command::SwitchTo)
+    Pry::Commands.add_command(Pry::Command::SwitchTo)
+  end
 end

data/lib/pry/commands/toggle_color.rb

@@ -1,24 +1,28 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::ToggleColor < Pry::ClassCommand
-    match 'toggle-color'
-    group 'Misc'
-    description 'Toggle syntax highlighting.'
+  class Command
+    class ToggleColor < Pry::ClassCommand
+      match 'toggle-color'
+      group 'Misc'
+      description 'Toggle syntax highlighting.'
 
-    banner <<-'BANNER'
-      Usage: toggle-color
+      banner <<-'BANNER'
+        Usage: toggle-color
 
-      Toggle syntax highlighting.
-    BANNER
+        Toggle syntax highlighting.
+      BANNER
 
-    def process
-      _pry_.color = color_toggle
-      output.puts "Syntax highlighting #{_pry_.color ? "on" : "off"}"
-    end
+      def process
+        pry_instance.color = color_toggle
+        output.puts "Syntax highlighting #{pry_instance.color ? 'on' : 'off'}"
+      end
 
-    def color_toggle
-      !_pry_.color
-    end
+      def color_toggle
+        !pry_instance.color
+      end
 
-    Pry::Commands.add_command(self)
+      Pry::Commands.add_command(self)
+    end
   end
 end

data/lib/pry/commands/watch_expression/expression.rb

@@ -1,37 +1,42 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::WatchExpression
-    class Expression
-      attr_reader :target, :source, :value, :previous_value, :_pry_
+  class Command
+    class WatchExpression
+      class Expression
+        attr_reader :target, :source, :value, :previous_value, :pry_instance
 
-      def initialize(_pry_, target, source)
-        @_pry_ = _pry_
-        @target = target
-        @source = Code.new(source).strip
-      end
+        def initialize(pry_instance, target, source)
+          @pry_instance = pry_instance
+          @target = target
+          @source = Code.new(source).strip
+        end
 
-      def eval!
-        @previous_value = @value
-        @value = Pry::ColorPrinter.pp(target_eval(target, source), "")
-      end
+        def eval!
+          @previous_value = value
+          @value = Pry::ColorPrinter.pp(target_eval(target, source), ''.dup)
+        end
 
-      def to_s
-        "#{Code.new(source).highlighted.strip} => #{value}"
-      end
+        def to_s
+          "#{Code.new(source).highlighted.strip} => #{value}"
+        end
 
-      # Has the value of the expression changed?
-      #
-      # We use the pretty-printed string represenation to detect differences
-      # as this avoids problems with dup (causes too many differences) and == (causes too few)
-      def changed?
-        (value != previous_value)
-      end
+        # Has the value of the expression changed?
+        #
+        # We use the pretty-printed string represenation to detect differences
+        # as this avoids problems with dup (causes too many differences) and ==
+        # (causes too few)
+        def changed?
+          (value != previous_value)
+        end
 
-      private
+        private
 
-      def target_eval(target, source)
-        target.eval(source)
-      rescue => e
-        e
+        def target_eval(target, source)
+          target.eval(source)
+        rescue StandardError => e
+          e
+        end
       end
     end
   end

data/lib/pry/commands/watch_expression.rb

@@ -1,105 +1,110 @@
+# frozen_string_literal: true
+
 class Pry
-  class Command::WatchExpression < Pry::ClassCommand
-    require 'pry/commands/watch_expression/expression.rb'
-
-    match 'watch'
-    group 'Context'
-    description 'Watch the value of an expression and print a notification whenever it changes.'
-    command_options :use_prefix => false
-
-    banner <<-'BANNER'
-      Usage: watch [EXPRESSION]
-             watch
-             watch --delete [INDEX]
-
-      watch [EXPRESSION] adds an expression to the list of those being watched.
-      It will be re-evaluated every time you hit enter in pry. If its value has
-      changed, the new value will be printed to the console.
-
-      This is useful if you are step-through debugging and want to see how
-      something changes over time.  It's also useful if you're trying to write
-      a method inside pry and want to check that it gives the right answers
-      every time you redefine it.
-
-      watch on its own displays all the currently watched expressions and their
-      values, and watch --delete [INDEX] allows you to delete expressions from
-      the list being watched.
-    BANNER
-
-    def options(opt)
-      opt.on :d, :delete,
-        "Delete the watch expression with the given index. If no index is given; clear all watch expressions.",
-        :optional_argument => true, :as => Integer
-      opt.on :l, :list,
-        "Show all current watch expressions and their values.  Calling watch with no expressions or options will also show the watch expressions."
-    end
+  class Command
+    class WatchExpression < Pry::ClassCommand
+      match 'watch'
+      group 'Context'
+      description 'Watch the value of an expression and print a notification ' \
+                  'whenever it changes.'
+      command_options use_prefix: false
+
+      banner <<-'BANNER'
+        Usage: watch [EXPRESSION]
+               watch
+               watch --delete [INDEX]
+
+        watch [EXPRESSION] adds an expression to the list of those being watched.
+        It will be re-evaluated every time you hit enter in pry. If its value has
+        changed, the new value will be printed to the console.
+
+        This is useful if you are step-through debugging and want to see how
+        something changes over time.  It's also useful if you're trying to write
+        a method inside pry and want to check that it gives the right answers
+        every time you redefine it.
+
+        watch on its own displays all the currently watched expressions and their
+        values, and watch --delete [INDEX] allows you to delete expressions from
+        the list being watched.
+      BANNER
 
-    def process
-      case
-      when opts.present?(:delete)
-        delete opts[:delete]
-      when opts.present?(:list) || args.empty?
-        list
-      else
-        add_hook
-        add_expression(args)
+      def options(opt)
+        opt.on :d, :delete,
+               "Delete the watch expression with the given index. If no index " \
+               "is given; clear all watch expressions.",
+               optional_argument: true, as: Integer
+        opt.on :l, :list,
+               "Show all current watch expressions and their values. Calling " \
+               "watch with no expressions or options will also show the watch " \
+               "expressions."
       end
-    end
 
-    private
+      def process
+        if opts.present?(:delete)
+          delete opts[:delete]
+        elsif opts.present?(:list) || args.empty?
+          list
+        else
+          add_hook
+          add_expression(args)
+        end
+      end
 
-    def expressions
-      _pry_.config.watch_expressions ||= []
-    end
+      private
 
-    def delete(index)
-      if index
-        output.puts "Deleting watch expression ##{index}: #{expressions[index-1]}"
-        expressions.delete_at(index-1)
-      else
-        output.puts "Deleting all watched expressions"
-        expressions.clear
+      def expressions
+        state.watch_expressions ||= []
       end
-    end
 
-    def list
-      if expressions.empty?
-        output.puts "No watched expressions"
-      else
-        _pry_.pager.open do |pager|
-          pager.puts "Listing all watched expressions:"
-          pager.puts ""
-          expressions.each_with_index do |expr, index|
-            pager.print text.with_line_numbers(expr.to_s, index+1)
+      def delete(index)
+        if index
+          output.puts "Deleting watch expression ##{index}: #{expressions[index - 1]}"
+          expressions.delete_at(index - 1)
+        else
+          output.puts "Deleting all watched expressions"
+          expressions.clear
+        end
+      end
+
+      def list
+        if expressions.empty?
+          output.puts "No watched expressions"
+        else
+          pry_instance.pager.open do |pager|
+            pager.puts "Listing all watched expressions:"
+            pager.puts ""
+            expressions.each_with_index do |expr, index|
+              pager.print with_line_numbers(expr.to_s, index + 1)
+            end
+            pager.puts ""
           end
-          pager.puts ""
         end
       end
-    end
 
-    def eval_and_print_changed(output)
-      expressions.each do |expr|
-        expr.eval!
-        if expr.changed?
-          output.puts "#{text.blue "watch"}: #{expr.to_s}"
+      def eval_and_print_changed(output)
+        expressions.each do |expr|
+          expr.eval!
+          output.puts "#{blue 'watch'}: #{expr}" if expr.changed?
         end
       end
-    end
 
-    def add_expression(arguments)
-      expressions << Expression.new(_pry_, target, arg_string)
-      output.puts "Watching #{Code.new(arg_string).highlighted}"
-    end
+      # TODO: fix arguments.
+      # https://github.com/pry/pry/commit/b031df2f2f5850ee6e9018f33d35f3485a9b0423
+      def add_expression(_arguments)
+        expressions << Expression.new(pry_instance, target, arg_string)
+        output.puts "Watching #{Code.new(arg_string).highlighted}"
+      end
+
+      def add_hook
+        hook = [:after_eval, :watch_expression]
+        return if pry_instance.hooks.hook_exists?(*hook)
 
-    def add_hook
-      hook = [:after_eval, :watch_expression]
-      unless _pry_.hooks.hook_exists?(*hook)
-        _pry_.hooks.add_hook(*hook) do |_, _pry_|
-          eval_and_print_changed _pry_.output
+        pry_instance.hooks.add_hook(*hook) do |_, pry_instance|
+          eval_and_print_changed pry_instance.output
         end
       end
     end
-  end
 
-  Pry::Commands.add_command(Pry::Command::WatchExpression)
+    Pry::Commands.add_command(Pry::Command::WatchExpression)
+  end
 end