pry 0.12.0 → 0.14.0

data/lib/pry/pager.rb

@@ -1,111 +1,116 @@
-require 'pry/terminal'
+# frozen_string_literal: true
 
 # A pager is an `IO`-like object that accepts text and either prints it
 # immediately, prints it one page at a time, or streams it to an external
 # program to print one page at a time.
-class Pry::Pager
-  class StopPaging < StandardError
-  end
-
-  attr_reader :_pry_
-
-  def initialize(_pry_)
-    @_pry_ = _pry_
-  end
-
-  # Send the given text through the best available pager (if `Pry.config.pager` is
-  # enabled). If you want to send text through in chunks as you generate it, use `open`
-  # to get a writable object instead.
-  #
-  # @param [String] text
-  #   Text to run through a pager.
-  #
-  def page(text)
-    open do |pager|
-      pager << text
+class Pry
+  class Pager
+    class StopPaging < StandardError
     end
-  end
 
-  # Yields a pager object (`NullPager`, `SimplePager`, or `SystemPager`).  All
-  # pagers accept output with `#puts`, `#print`, `#write`, and `#<<`.
-  def open
-    pager = best_available
-    yield pager
-  rescue StopPaging
-  ensure
-    pager.close if pager
-  end
+    attr_reader :pry_instance
 
-  private
-
-  def enabled?; !!@enabled; end
-
-  def output; @output; end
-
-  # Return an instance of the "best" available pager class -- `SystemPager` if
-  # possible, `SimplePager` if `SystemPager` isn't available, and `NullPager`
-  # if the user has disabled paging. All pagers accept output with `#puts`,
-  # `#print`, `#write`, and `#<<`. You must call `#close` when you're done
-  # writing output to a pager, and you must rescue `Pry::Pager::StopPaging`.
-  # These requirements can be avoided by using `.open` instead.
-  def best_available
-    if !_pry_.config.pager
-      NullPager.new(_pry_.output)
-    elsif !SystemPager.available? || Helpers::Platform.jruby?
-      SimplePager.new(_pry_.output)
-    else
-      SystemPager.new(_pry_.output)
+    def initialize(pry_instance)
+      @pry_instance = pry_instance
     end
-  end
 
-  # `NullPager` is a "pager" that actually just prints all output as it comes
-  # in. Used when `Pry.config.pager` is false.
-  class NullPager
-    def initialize(out)
-      @out = out
+    # Send the given text through the best available pager (if
+    # `Pry.config.pager` is enabled). If you want to send text through in
+    # chunks as you generate it, use `open` to get a writable object
+    # instead.
+    #
+    # @param [String] text
+    #   Text to run through a pager.
+    #
+    def page(text)
+      open do |pager|
+        pager << text
+      end
     end
 
-    def puts(str)
-      print "#{str.chomp}\n"
+    # Yields a pager object (`NullPager`, `SimplePager`, or `SystemPager`).
+    # All pagers accept output with `#puts`, `#print`, `#write`, and `#<<`.
+    def open
+      pager = best_available
+      yield pager
+    rescue StopPaging # rubocop:disable Lint/HandleExceptions
+    ensure
+      pager.close if pager
     end
 
-    def print(str)
-      write str
-    end
-    alias << print
+    private
 
-    def write(str)
-      @out.write str
+    def enabled?
+      !!@enabled
     end
 
-    def close
+    attr_reader :output
+
+    # Return an instance of the "best" available pager class --
+    # `SystemPager` if possible, `SimplePager` if `SystemPager` isn't
+    # available, and `NullPager` if the user has disabled paging. All
+    # pagers accept output with `#puts`, `#print`, `#write`, and `#<<`. You
+    # must call `#close` when you're done writing output to a pager, and
+    # you must rescue `Pry::Pager::StopPaging`. These requirements can be
+    # avoided by using `.open` instead.
+    def best_available
+      if !pry_instance.config.pager
+        NullPager.new(pry_instance.output)
+      elsif !SystemPager.available? || Helpers::Platform.jruby?
+        SimplePager.new(pry_instance.output)
+      else
+        SystemPager.new(pry_instance.output)
+      end
     end
 
-    private
+    # `NullPager` is a "pager" that actually just prints all output as it
+    # comes in. Used when `Pry.config.pager` is false.
+    class NullPager
+      def initialize(out)
+        @out = out
+      end
 
-    def height
-      @height ||= Pry::Terminal.height!
-    end
+      def puts(str)
+        print "#{str.chomp}\n"
+      end
 
-    def width
-      @width ||= Pry::Terminal.width!
-    end
-  end
+      def print(str)
+        write str
+      end
+      alias << print
+
+      def write(str)
+        @out.write str
+      end
+
+      def close; end
+
+      private
+
+      def height
+        @height ||= @out.height
+      end
 
-  # `SimplePager` is a straightforward pure-Ruby pager. We use it on JRuby and
-  # when we can't find a usable external pager.
-  class SimplePager < NullPager
-    def initialize(*)
-      super
-      @tracker = PageTracker.new(height - 3, width)
+      def width
+        @width ||= @out.width
+      end
     end
 
-    def write(str)
-      str.lines.each do |line|
-        @out.print line
-        @tracker.record line
+    # `SimplePager` is a straightforward pure-Ruby pager. We use it on
+    # JRuby and when we can't find a usable external pager.
+    class SimplePager < NullPager
+      def initialize(*)
+        super
+        @tracker = PageTracker.new(height - 3, width)
+      end
+
+      def write(str)
+        str.lines.each do |line|
+          @out.print line
+          @tracker.record line
+
+          next unless @tracker.page?
 
-        if @tracker.page?
           @out.print "\n"
           @out.print "\e[0m"
           @out.print "<page break> --- Press enter to continue " \
@@ -116,128 +121,129 @@ class Pry::Pager
         end
       end
     end
-  end
-
-  # `SystemPager` buffers output until we're pretty sure it's at least a page
-  # long, then invokes an external pager and starts streaming output to it. If
-  # `#close` is called before then, it just prints out the buffered content.
-  class SystemPager < NullPager
-    def self.default_pager
-      pager = ENV["PAGER"] || ""
 
-      # Default to less, and make sure less is being passed the correct options
-      if pager.strip.empty? or pager =~ /^less\b/
-        pager = "less -R -F -X"
-      end
+    # `SystemPager` buffers output until we're pretty sure it's at least a
+    # page long, then invokes an external pager and starts streaming output
+    # to it. If `#close` is called before then, it just prints out the
+    # buffered content.
+    class SystemPager < NullPager
+      def self.default_pager
+        pager = Pry::Env['PAGER'] || ''
 
-      pager
-    end
+        # Default to less, and make sure less is being passed the correct
+        # options
+        pager = "less -R -F -X" if pager.strip.empty? || pager =~ /^less\b/
 
-    @system_pager = nil
+        pager
+      end
 
-    def self.available?
-      if @system_pager.nil?
-        @system_pager = begin
-          pager_executable = default_pager.split(' ').first
-          if Helpers::Platform.windows? || Helpers::Platform.windows_ansi?
-            `where /Q #{pager_executable}`
-          else
-            `which #{pager_executable}`
-          end
-          $?.success?
-        rescue
-          false
+      @system_pager = nil
+
+      def self.available?
+        if @system_pager.nil?
+          @system_pager =
+            begin
+              pager_executable = default_pager.split(' ').first
+              if Helpers::Platform.windows? || Helpers::Platform.windows_ansi?
+                `where /Q #{pager_executable}`
+              else
+                `which #{pager_executable}`
+              end
+              $CHILD_STATUS.success?
+            rescue StandardError
+              false
+            end
+        else
+          @system_pager
         end
-      else
-        @system_pager
       end
-    end
 
-    def initialize(*)
-      super
-      @tracker = PageTracker.new(height, width)
-      @buffer  = ""
-      @pager   = nil
-    end
+      def initialize(*)
+        super
+        @tracker = PageTracker.new(height, width)
+        @buffer  = ""
+        @pager   = nil
+      end
 
-    def write(str)
-      if invoked_pager?
-        write_to_pager str
-      else
-        @tracker.record str
-        @buffer << str
+      def write(str)
+        if invoked_pager?
+          write_to_pager str
+        else
+          @tracker.record str
+          @buffer += str
 
-        if @tracker.page?
-          write_to_pager @buffer
+          write_to_pager @buffer if @tracker.page?
         end
+      rescue Errno::EPIPE
+        raise StopPaging
       end
-    rescue Errno::EPIPE
-      raise StopPaging
-    end
 
-    def close
-      if invoked_pager?
-        pager.close
-      else
-        @out.puts @buffer
+      def close
+        if invoked_pager?
+          pager.close
+        else
+          @out.puts @buffer
+        end
       end
-    end
 
-    private
+      private
 
-    def write_to_pager(text)
-      pager.write @out.decolorize_maybe(text)
-    end
+      def write_to_pager(text)
+        pager.write @out.decolorize_maybe(text)
+      end
 
-    def invoked_pager?
-      @pager
-    end
+      def invoked_pager?
+        @pager
+      end
 
-    def pager
-      @pager ||= IO.popen(self.class.default_pager, 'w')
+      def pager
+        @pager ||= IO.popen(self.class.default_pager, 'w')
+      end
     end
-  end
 
-  # `PageTracker` tracks output to determine whether it's likely to take up a
-  # whole page. This doesn't need to be super precise, but we can use it for
-  # `SimplePager` and to avoid invoking the system pager unnecessarily.
-  #
-  # One simplifying assumption is that we don't need `#page?` to return `true`
-  # on the basis of an incomplete line. Long lines should be counted as
-  # multiple lines, but we don't have to transition from `false` to `true`
-  # until we see a newline.
-  class PageTracker
-    def initialize(rows, cols)
-      @rows, @cols = rows, cols
-      reset
-    end
+    # `PageTracker` tracks output to determine whether it's likely to take
+    # up a whole page. This doesn't need to be super precise, but we can
+    # use it for `SimplePager` and to avoid invoking the system pager
+    # unnecessarily.
+    #
+    # One simplifying assumption is that we don't need `#page?` to return
+    # `true` on the basis of an incomplete line. Long lines should be
+    # counted as multiple lines, but we don't have to transition from
+    # `false` to `true` until we see a newline.
+    class PageTracker
+      def initialize(rows, cols)
+        @rows = rows
+        @cols = cols
+        reset
+      end
 
-    def record(str)
-      str.lines.each do |line|
-        if line.end_with? "\n"
-          @row += ((@col + line_length(line) - 1) / @cols) + 1
-          @col  = 0
-        else
-          @col += line_length(line)
+      def record(str)
+        str.lines.each do |line|
+          if line.end_with? "\n"
+            @row += ((@col + line_length(line) - 1) / @cols) + 1
+            @col  = 0
+          else
+            @col += line_length(line)
+          end
         end
       end
-    end
 
-    def page?
-      @row >= @rows
-    end
+      def page?
+        @row >= @rows
+      end
 
-    def reset
-      @row = 0
-      @col = 0
-    end
+      def reset
+        @row = 0
+        @col = 0
+      end
 
-    private
+      private
 
-    # Approximation of the printable length of a given line, without the
-    # newline and without ANSI color codes.
-    def line_length(line)
-      line.chomp.gsub(/\e\[[\d;]*m/, '').length
+      # Approximation of the printable length of a given line, without the
+      # newline and without ANSI color codes.
+      def line_length(line)
+        line.chomp.gsub(/\e\[[\d;]*m/, '').length
+      end
     end
   end
 end

data/lib/pry/prompt.rb

@@ -1,14 +1,16 @@
+# frozen_string_literal: true
+
 class Pry
   # Prompt represents the Pry prompt, which can be used with Readline-like
   # libraries. It defines a few default prompts (default prompt, simple prompt,
-  # etc) and also provides an API to add custom prompts.
+  # etc) and also provides an API for adding and implementing custom prompts.
   #
-  # @example
+  # @example Registering a new Pry prompt
   #   Pry::Prompt.add(
   #     :ipython,
   #     'IPython-like prompt', [':', '...:']
-  #   ) do |_context, _nesting, _pry_, sep|
-  #     sep == ':' ? "In [#{_pry_.input_ring.count}]: " : '   ...: '
+  #   ) do |_context, _nesting, pry_instance, sep|
+  #     sep == ':' ? "In [#{pry_instance.input_ring.count}]: " : '   ...: '
   #   end
   #
   #   # Produces:
@@ -17,20 +19,23 @@ class Pry
   #   #    ...: end
   #   # => :foo
   #   # In [4]:
+  #
+  # @example Manually instantiating the Prompt class
+  #   prompt_procs = [
+  #     proc { '#{rand(1)}>" },
+  #     proc { "#{('a'..'z').to_a.sample}*" }
+  #   ]
+  #   prompt = Pry::Prompt.new(
+  #     :random,
+  #     'Random number or letter prompt.',
+  #     prompt_procs
+  #   )
+  #   prompt.wait_proc.call(...) #=>
+  #   prompt.incomplete_proc.call(...)
+  #
   # @since v0.11.0
   # @api public
-  module Prompt
-    # @return [String]
-    DEFAULT_NAME = 'pry'.freeze
-
-    # @return [Array<Object>] the list of objects that are known to have a
-    #   1-line #inspect output suitable for prompt
-    SAFE_CONTEXTS = [String, Numeric, Symbol, nil, true, false].freeze
-
-    # @deprecated Use {Pry::Prompt.add} instead.
-    MAP = {}
-    deprecate_constant(:MAP) if respond_to?(:deprecate_constant)
-
+  class Prompt
     # A Hash that holds all prompts. The keys of the Hash are prompt
     # names, the values are Hash instances of the format {:description, :value}.
     @prompts = {}
@@ -39,13 +44,13 @@ class Pry
       # Retrieves a prompt.
       #
       # @example
-      #   Prompt[:my_prompt][:value]
+      #   Prompt[:my_prompt]
       #
-      # @param [Symbol] prompt_name The name of the prompt you want to access
+      # @param [Symbol] name The name of the prompt you want to access
       # @return [Hash{Symbol=>Object}]
       # @since v0.12.0
-      def [](prompt_name)
-        all[prompt_name.to_s]
+      def [](name)
+        @prompts[name.to_s]
       end
 
       # @return [Hash{Symbol=>Hash}] the duplicate of the internal prompts hash
@@ -57,89 +62,153 @@ class Pry
 
       # Adds a new prompt to the prompt hash.
       #
-      # @param [Symbol] prompt_name
+      # @param [Symbol] name
       # @param [String] description
       # @param [Array<String>] separators The separators to differentiate
       #   between prompt modes (default mode and class/method definition mode).
       #   The Array *must* have a size of 2.
-      # @yield [context, nesting, _pry_, sep]
+      # @yield [context, nesting, pry_instance, sep]
       # @yieldparam context [Object] the context where Pry is currently in
       # @yieldparam nesting [Integer] whether the context is nested
-      # @yieldparam _pry_ [Pry] the Pry instance
+      # @yieldparam pry_instance [Pry] the Pry instance
       # @yieldparam separator [String] separator string
       # @return [nil]
       # @raise [ArgumentError] if the size of `separators` is not 2
+      # @raise [ArgumentError] if `prompt_name` is already occupied
       # @since v0.12.0
-      def add(prompt_name, description = '', separators = %w[> *])
+      def add(name, description = '', separators = %w[> *])
+        name = name.to_s
+
         unless separators.size == 2
           raise ArgumentError, "separators size must be 2, given #{separators.size}"
         end
 
-        @prompts[prompt_name.to_s] = {
-          description: description,
-          value: separators.map do |sep|
-            proc { |context, nesting, _pry_| yield(context, nesting, _pry_, sep) }
+        if @prompts.key?(name)
+          raise ArgumentError, "the '#{name}' prompt was already added"
+        end
+
+        @prompts[name] = new(
+          name,
+          description,
+          separators.map do |sep|
+            proc do |context, nesting, pry_instance|
+              yield(context, nesting, pry_instance, sep)
+            end
           end
-        }
+        )
 
         nil
       end
+    end
 
-      private
+    # @return [String]
+    attr_reader :name
 
-      def prompt_name(name)
-        return name unless name.is_a?(Pry::Config::Lazy)
+    # @return [String]
+    attr_reader :description
+
+    # @return [Array<Proc>] the array of procs that hold
+    #   `[wait_proc, incomplete_proc]`
+    attr_reader :prompt_procs
+
+    # @param [String] name
+    # @param [String] description
+    # @param [Array<Proc>] prompt_procs
+    def initialize(name, description, prompt_procs)
+      @name = name
+      @description = description
+      @prompt_procs = prompt_procs
+    end
+
+    # @return [Proc] the proc which builds the wait prompt (`>`)
+    def wait_proc
+      @prompt_procs.first
+    end
+
+    # @return [Proc] the proc which builds the prompt when in the middle of an
+    #   expression such as open method, etc. (`*`)
+    def incomplete_proc
+      @prompt_procs.last
+    end
 
-        name.call
+    # @deprecated Use a `Pry::Prompt` instance directly
+    def [](key)
+      key = key.to_s
+      if %w[name description].include?(key)
+        Pry::Warning.warn(
+          "`Pry::Prompt[:#{@name}][:#{key}]` is deprecated. " \
+          "Use `#{self.class}##{key}` instead"
+        )
+        public_send(key)
+      elsif key.to_s == 'value'
+        Pry::Warning.warn(
+          "`#{self.class}[:#{@name}][:value]` is deprecated. Use " \
+          "`#{self.class}#prompt_procs` instead or an instance of " \
+          "`#{self.class}` directly"
+        )
+        @prompt_procs
       end
     end
 
-    add(:default, <<DESC) do |context, nesting, _pry_, sep|
-The default Pry prompt. Includes information about the current expression
-number, evaluation context, and nesting level, plus a reminder that you're
-using Pry.
-DESC
+    add(
+      :default,
+      "The default Pry prompt. Includes information about the current expression \n" \
+      "number, evaluation context, and nesting level, plus a reminder that you're \n" \
+      'using Pry.'
+    ) do |context, nesting, pry_instance, sep|
       format(
         "[%<in_count>s] %<name>s(%<context>s)%<nesting>s%<separator>s ",
-        in_count: _pry_.input_ring.count,
-        name: prompt_name(_pry_.config.prompt_name),
+        in_count: pry_instance.input_ring.count,
+        name: pry_instance.config.prompt_name,
         context: Pry.view_clip(context),
         nesting: (nesting > 0 ? ":#{nesting}" : ''),
         separator: sep
       )
     end
 
-    add(:simple, "A simple `>>`.\n", ['>> ', ' | ']) do |_, _, _, sep|
+    add(
+      :simple,
+      "A simple `>>`.",
+      ['>> ', ' | ']
+    ) do |_, _, _, sep|
       sep
     end
 
-    add(:nav, <<DESC, %w[> *]) do |context, nesting, _pry_, sep|
-A prompt that displays the binding stack as a path and includes information
-about #{Helpers::Text.bold('_in_')} and #{Helpers::Text.bold('_out_')}.
-DESC
-      tree = _pry_.binding_stack.map { |b| Pry.view_clip(b.eval('self')) }
+    add(
+      :nav,
+      "A prompt that displays the binding stack as a path and includes information \n" \
+      "about #{Helpers::Text.bold('_in_')} and #{Helpers::Text.bold('_out_')}.",
+      %w[> *]
+    ) do |_context, _nesting, pry_instance, sep|
+      tree = pry_instance.binding_stack.map { |b| Pry.view_clip(b.eval('self')) }
       format(
         "[%<in_count>s] (%<name>s) %<tree>s: %<stack_size>s%<separator>s ",
-        in_count: _pry_.input_ring.count,
-        name: prompt_name(_pry_.config.prompt_name),
+        in_count: pry_instance.input_ring.count,
+        name: pry_instance.config.prompt_name,
         tree: tree.join(' / '),
-        stack_size: _pry_.binding_stack.size - 1,
+        stack_size: pry_instance.binding_stack.size - 1,
         separator: sep
       )
     end
 
-    add(:shell, <<DESC, %w[$ *]) do |context, nesting, _pry_, sep|
-A prompt that displays `$PWD` as you change it.
-DESC
+    add(
+      :shell,
+      'A prompt that displays `$PWD` as you change it.',
+      %w[$ *]
+    ) do |context, _nesting, pry_instance, sep|
       format(
         "%<name>s %<context>s:%<pwd>s %<separator>s ",
-        name: prompt_name(_pry_.config.prompt_name),
+        name: pry_instance.config.prompt_name,
         context: Pry.view_clip(context),
         pwd: Dir.pwd,
         separator: sep
       )
     end
 
-    add(:none, 'Wave goodbye to the Pry prompt.', Array.new(2)) { '' }
+    add(
+      :none,
+      'Wave goodbye to the Pry prompt.',
+      Array.new(2)
+    ) { '' }
   end
 end