Class: Pry

Inherits:
Object show all
Extended by:
Forwardable, Config::Convenience
Defined in:
lib/pry/pry_instance.rb,
lib/pry.rb,
lib/pry/cli.rb,
lib/pry/code.rb,
lib/pry/repl.rb,
lib/pry/hooks.rb,
lib/pry/method.rb,
lib/pry/editor.rb,
lib/pry/indent.rb,
lib/pry/version.rb,
lib/pry/command.rb,
lib/pry/rubygem.rb,
lib/pry/plugins.rb,
lib/pry/history.rb,
lib/pry/rbx_path.rb,
lib/pry/code/loc.rb,
lib/pry/pry_class.rb,
lib/pry/input_lock.rb,
lib/pry/exceptions.rb,
lib/pry/commands/cd.rb,
lib/pry/code_object.rb,
lib/pry/commands/ls.rb,
lib/pry/commands/ri.rb,
lib/pry/command_set.rb,
lib/pry/helpers/text.rb,
lib/pry/commands/cat.rb,
lib/pry/commands/wtf.rb,
lib/pry/color_printer.rb,
lib/pry/commands/gist.rb,
lib/pry/commands/stat.rb,
lib/pry/history_array.rb,
lib/pry/commands/edit.rb,
lib/pry/commands/play.rb,
lib/pry/helpers/table.rb,
lib/pry/commands/hist.rb,
lib/pry/commands/help.rb,
lib/pry/commands/bang.rb,
lib/pry/commands/exit.rb,
lib/pry/method/patcher.rb,
lib/pry/wrapped_module.rb,
lib/pry/commands/reset.rb,
lib/pry/code/code_file.rb,
lib/pry/core_extensions.rb,
lib/pry/commands/gem_cd.rb,
lib/pry/method/disowned.rb,
lib/pry/input_completer.rb,
lib/pry/code/code_range.rb,
lib/pry/commands/jump_to.rb,
lib/pry/commands/nesting.rb,
lib/pry/module_candidate.rb,
lib/pry/repl_file_loader.rb,
lib/pry/commands/ls/grep.rb,
lib/pry/commands/raise_up.rb,
lib/pry/commands/gem_list.rb,
lib/pry/commands/whereami.rb,
lib/pry/commands/bang_pry.rb,
lib/pry/commands/show_doc.rb,
lib/pry/commands/exit_all.rb,
lib/pry/commands/gem_open.rb,
lib/pry/commands/show_info.rb,
lib/pry/commands/switch_to.rb,
lib/pry/commands/save_file.rb,
lib/pry/commands/amend_line.rb,
lib/pry/commands/show_input.rb,
lib/pry/commands/ls/methods.rb,
lib/pry/commands/shell_mode.rb,
lib/pry/commands/import_set.rb,
lib/pry/commands/ls/globals.rb,
lib/pry/commands/fix_indent.rb,
lib/pry/commands/reload_code.rb,
lib/pry/commands/show_source.rb,
lib/pry/commands/pry_version.rb,
lib/pry/commands/disable_pry.rb,
lib/pry/commands/find_method.rb,
lib/pry/helpers/base_helpers.rb,
lib/pry/commands/easter_eggs.rb,
lib/pry/commands/gem_install.rb,
lib/pry/commands/ls/constants.rb,
lib/pry/commands/ls/formatter.rb,
lib/pry/commands/ls/ls_entity.rb,
lib/pry/commands/exit_program.rb,
lib/pry/commands/toggle_color.rb,
lib/pry/commands/shell_command.rb,
lib/pry/commands/pry_backtrace.rb,
lib/pry/commands/ls/local_vars.rb,
lib/pry/commands/simple_prompt.rb,
lib/pry/helpers/command_helpers.rb,
lib/pry/commands/ls/local_names.rb,
lib/pry/commands/code_collector.rb,
lib/pry/helpers/options_helpers.rb,
lib/pry/commands/ls/self_methods.rb,
lib/pry/commands/install_command.rb,
lib/pry/commands/ls/instance_vars.rb,
lib/pry/commands/watch_expression.rb,
lib/pry/commands/cat/file_formatter.rb,
lib/pry/method/weird_method_locator.rb,
lib/pry/helpers/documentation_helpers.rb,
lib/pry/commands/edit/exception_patcher.rb,
lib/pry/commands/cat/abstract_formatter.rb,
lib/pry/commands/cat/exception_formatter.rb,
lib/pry/commands/edit/file_and_line_locator.rb,
lib/pry/commands/watch_expression/expression.rb,
lib/pry/commands/cat/input_expression_formatter.rb

Overview

PP subclass for streaming inspect output in color.

Defined Under Namespace

Modules: ExtendCommandBundle, FrozenObjectException, Helpers, InputCompleter, Pager, RbxPath, RescuableException, Rubygem, TooSafeException, UserError Classes: BlockCommand, CLI, ClassCommand, Code, CodeFile, CodeObject, ColorPrinter, Command, CommandError, CommandSet, Config, Editor, History, HistoryArray, Hooks, Indent, InputLock, Inspector, LastException, Method, MethodNotFound, NoCommandError, ObsoleteError, PluginManager, Prompt, REPL, REPLFileLoader, Result, Terminal, WrappedModule

Constant Summary

DEFAULT_HOOKS =

The default hooks - display messages when beginning and ending Pry sessions.

Pry::Hooks.new.add_hook(:before_session, :default) do |out, target, _pry_|
  next if _pry_.quiet?
  _pry_.run_command("whereami --quiet")
end
DEFAULT_PRINT =

The default print

proc do |output, value, _pry_|
  Pry::Pager.with_pager(output) do |pager|
    pager.print _pry_.config.output_prefix
    Pry::ColorPrinter.pp(value, pager, Pry::Terminal.width! - 1)
  end
end
SIMPLE_PRINT =

may be convenient when working with enormous objects and pretty_print is too slow

proc do |output, value|
  begin
    output.puts value.inspect
  rescue RescuableException
    output.puts "unknown"
  end
end
CLIPPED_PRINT =

useful when playing with truly enormous objects

proc do |output, value|
  output.puts Pry.view_clip(value, id: true)
end
DEFAULT_EXCEPTION_HANDLER =

Will only show the first line of the backtrace

proc do |output, exception, _|
  if UserError === exception && SyntaxError === exception
    output.puts "SyntaxError: #{exception.message.sub(/.*syntax error, */m, '')}"
  else
    output.puts "#{exception.class}: #{exception.message}"
    output.puts "from #{exception.backtrace.first}"
  end
end
DEFAULT_PROMPT_NAME =
'pry'
DEFAULT_PROMPT =

The default prompt; includes the target and nesting level

[
 proc { |target_self, nest_level, pry|
   "[#{pry.input_array.size}] #{Pry.config.prompt_name}(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}> "
 },

 proc { |target_self, nest_level, pry|
   "[#{pry.input_array.size}] #{Pry.config.prompt_name}(#{Pry.view_clip(target_self)})#{":#{nest_level}" unless nest_level.zero?}* "
 }
]
DEFAULT_PROMPT_SAFE_OBJECTS =
[String, Numeric, Symbol, nil, true, false]
SIMPLE_PROMPT =

A simple prompt - doesn't display target or nesting level

[proc { ">> " }, proc { " | " }]
NO_PROMPT =
[proc { '' }, proc { '' }]
SHELL_PROMPT =
[
 proc { |target_self, _, _| "#{Pry.config.prompt_name} #{Pry.view_clip(target_self)}:#{Dir.pwd} $ " },
 proc { |target_self, _, _| "#{Pry.config.prompt_name} #{Pry.view_clip(target_self)}:#{Dir.pwd} * " }
]
[
 proc do |conf|
   tree = conf.binding_stack.map { |b| Pry.view_clip(b.eval("self")) }.join " / "
   "[#{conf.expr_number}] (#{Pry.config.prompt_name}) #{tree}: #{conf.nesting_level}> "
 end,
 proc do |conf|
   tree = conf.binding_stack.map { |b| Pry.view_clip(b.eval("self")) }.join " / "
   "[#{conf.expr_number}] (#{ Pry.config.prompt_name}) #{tree}: #{conf.nesting_level}* "
 end,
]
DEFAULT_CONTROL_D_HANDLER =

Deal with the ^D key being pressed. Different behaviour in different cases: 1. In an expression behave like ! command. 2. At top-level session behave like exit command. 3. In a nested session behave like cd ...

proc do |eval_string, _pry_|
  if !eval_string.empty?
    eval_string.replace('') # Clear input buffer.
  elsif _pry_.binding_stack.one?
    _pry_.binding_stack.clear
    throw(:breakout)
  else
    # Otherwise, saves current binding stack as old stack and pops last
    # binding out of binding stack (the old stack still has that binding).
    _pry_.command_state["cd"] ||= Pry::Config.from_hash({}) # FIXME
    _pry_.command_state['cd'].old_stack = _pry_.binding_stack.dup
    _pry_.binding_stack.pop
  end
end
DEFAULT_SYSTEM =
proc do |output, cmd, _|
  if !system(cmd)
    output.puts "Error: there was a problem executing system command: #{cmd}"
  end
end
INITIAL_PWD =

Store the current working directory. This allows show-source etc. to work if your process has changed directory since boot. [Issue #675]

Dir.pwd
VERSION =
"0.10.0.pre"
HOME_RC_FILE =
ENV["PRYRC"] || "~/.pryrc"
LOCAL_RC_FILE =
"./.pryrc"
DEFAULT_EXCEPTION_WHITELIST =

Don't catch these exceptions

[SystemExit,
SignalException,
Pry::TooSafeException]
EMPTY_COMPLETIONS =
[].freeze
BINDING_METHOD_IMPL =

Returns Code of the method used when implementing Pry's binding, along with line indication to be used with instance_eval (and friends).

See Also:

[<<-METHOD, __FILE__, __LINE__ + 1]
  # Get a binding with 'self' set to self, and no locals.
  #
  # The default definee is determined by the context in which the
  # definition is eval'd.
  #
  # Please don't call this method directly, see {__binding__}.
  #
  # @return [Binding]
  def __pry__
    binding
  end
METHOD

Constants included from Config::Convenience

Config::Convenience::SHORTCUTS

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Config::Convenience

config_shortcut

Constructor Details

#initialize(options = {}) ⇒ Pry

Create a new Pry instance.

Options Hash (options):

  • :input (#readline)

    The object to use for input.

  • :output (#puts)

    The object to use for output.

  • :commands (Pry::CommandBase)

    The object to use for commands.

  • :hooks (Hash)

    The defined hook Procs.

  • :prompt (Array<Proc>)

    The array of Procs to use for prompts.

  • :print (Proc)

    The Proc to use for printing return values.

  • :quiet (Boolean)

    Omit the whereami banner when starting.

  • :backtrace (Array<String>)

    The backtrace of the session's binding.pry line, if applicable.

  • :target (Object)

    The initial context for this session.



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
# File 'lib/pry/pry_instance.rb', line 65

def initialize(options={})
  @binding_stack = []
  @indent        = Pry::Indent.new
  @command_state = {}
  @eval_string   = ""
  @backtrace     = options.delete(:backtrace) || caller
  @config = Pry::Config.new
  config.merge!(options)
  push_prompt(config.prompt)
  @input_array  = Pry::HistoryArray.new config.memory_size
  @output_array = Pry::HistoryArray.new config.memory_size
  @custom_completions = config.command_completions.call
  push_initial_binding(options[:target])
  set_last_result nil
  @input_array << nil
  exec_hook(:when_started, options[:target], options, self)
end

Class Attribute Details

.cliObject

Returns the value of attribute cli



13
14
15
# File 'lib/pry/pry_class.rb', line 13

def cli
  @cli
end

.configObject

Returns the value of attribute config



16
17
18
# File 'lib/pry/pry_class.rb', line 16

def config
  @config
end

.current_lineObject

Returns the value of attribute current_line



10
11
12
# File 'lib/pry/pry_class.rb', line 10

def current_line
  @current_line
end

.custom_completionsObject

Returns the value of attribute custom_completions



9
10
11
# File 'lib/pry/pry_class.rb', line 9

def custom_completions
  @custom_completions
end

.eval_pathObject

Returns the value of attribute eval_path



12
13
14
# File 'lib/pry/pry_class.rb', line 12

def eval_path
  @eval_path
end

.historyObject



32
33
34
# File 'lib/pry/pry_class.rb', line 32

def history
  @history ||= History.new
end

.last_internal_errorObject

Returns the value of attribute last_internal_error



15
16
17
# File 'lib/pry/pry_class.rb', line 15

def last_internal_error
  @last_internal_error
end

.line_bufferObject

Returns the value of attribute line_buffer



11
12
13
# File 'lib/pry/pry_class.rb', line 11

def line_buffer
  @line_buffer
end

.quietObject

Returns the value of attribute quiet



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

def quiet
  @quiet
end

Instance Attribute Details

#backtraceObject

Returns the value of attribute backtrace



28
29
30
# File 'lib/pry/pry_instance.rb', line 28

def backtrace
  @backtrace
end

#binding_stackObject

Returns the value of attribute binding_stack



25
26
27
# File 'lib/pry/pry_instance.rb', line 25

def binding_stack
  @binding_stack
end

#command_stateObject (readonly)

Returns the value of attribute command_state



35
36
37
# File 'lib/pry/pry_instance.rb', line 35

def command_state
  @command_state
end

#configObject (readonly)

Returns the value of attribute config



39
40
41
# File 'lib/pry/pry_instance.rb', line 39

def config
  @config
end

#custom_completionsObject

Returns the value of attribute custom_completions



26
27
28
# File 'lib/pry/pry_instance.rb', line 26

def custom_completions
  @custom_completions
end

#eval_stringObject

Returns the value of attribute eval_string



27
28
29
# File 'lib/pry/pry_instance.rb', line 27

def eval_string
  @eval_string
end

#exit_valueObject (readonly)

Returns the value of attribute exit_value



36
37
38
# File 'lib/pry/pry_instance.rb', line 36

def exit_value
  @exit_value
end

#input_arrayObject (readonly)

Returns the value of attribute input_array



37
38
39
# File 'lib/pry/pry_instance.rb', line 37

def input_array
  @input_array
end

#last_dirObject

Returns the value of attribute last_dir



32
33
34
# File 'lib/pry/pry_instance.rb', line 32

def last_dir
  @last_dir
end

#last_exceptionObject

Returns the value of attribute last_exception



34
35
36
# File 'lib/pry/pry_instance.rb', line 34

def last_exception
  @last_exception
end

#last_fileObject

Returns the value of attribute last_file



31
32
33
# File 'lib/pry/pry_instance.rb', line 31

def last_file
  @last_file
end

#last_resultObject

Returns the value of attribute last_result



30
31
32
# File 'lib/pry/pry_instance.rb', line 30

def last_result
  @last_result
end

#output_arrayObject (readonly)

Returns the value of attribute output_array



38
39
40
# File 'lib/pry/pry_instance.rb', line 38

def output_array
  @output_array
end

#suppress_outputObject

Returns the value of attribute suppress_output



29
30
31
# File 'lib/pry/pry_instance.rb', line 29

def suppress_output
  @suppress_output
end

Class Method Details

.auto_resize!Object



258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
# File 'lib/pry/pry_class.rb', line 258

def self.auto_resize!
  Pry.config.input # by default, load Readline

  if !defined?(Readline) || Pry.config.input != Readline
    warn "Sorry, you must be using Readline for Pry.auto_resize! to work."
    return
  end

  if Readline::VERSION =~ /edit/i
    warn <<-EOT
Readline version #{Readline::VERSION} detected - will not auto_resize! correctly.
For the fix, use GNU Readline instead:
https://github.com/guard/guard/wiki/Add-proper-Readline-support-to-Ruby-on-Mac-OS-X
    EOT
    return
  end

  trap :WINCH do
    begin
      Readline.set_screen_size(*Terminal.size!)
    rescue => e
      warn "\nPry.auto_resize!'s Readline.set_screen_size failed: #{e}"
    end
    begin
      Readline.refresh_line
    rescue => e
      warn "\nPry.auto_resize!'s Readline.refresh_line failed: #{e}"
    end
  end
end

.binding_for(target) ⇒ Binding

Return a Binding object for target or return target if it is already a Binding. In the case where target is top-level then return TOPLEVEL_BINDING



311
312
313
314
315
316
317
318
319
320
321
# File 'lib/pry/pry_class.rb', line 311

def self.binding_for(target)
  if Binding === target
    target
  else
    if Pry.main == target
      TOPLEVEL_BINDING
    else
      target.__binding__
    end
  end
end

.Code(obj) ⇒ Object

Convert the given object into an instance of Pry::Code, if it isn't already one.



12
13
14
15
16
17
18
19
20
21
# File 'lib/pry/code.rb', line 12

def Code(obj)
  case obj
  when Code
    obj
  when ::Method, UnboundMethod, Proc, Pry::Method
    Code.from_method(obj)
  else
    Code.new(obj)
  end
end

.critical_section(&block) ⇒ Object



349
350
351
352
353
354
355
# File 'lib/pry/pry_class.rb', line 349

def self.critical_section(&block)
  Thread.current[:pry_critical_section] ||= 0
  Thread.current[:pry_critical_section] += 1
  yield
ensure
  Thread.current[:pry_critical_section] -= 1
end

.currentPry::Config



49
50
51
# File 'lib/pry/pry_class.rb', line 49

def self.current
  Thread.current[:__pry__] ||= Pry::Config.from_hash({}, nil)
end

.default_editor_for_platformObject



246
247
248
249
250
251
252
253
254
255
256
# File 'lib/pry/pry_class.rb', line 246

def self.default_editor_for_platform
  return ENV['VISUAL'] if ENV['VISUAL'] and not ENV['VISUAL'].empty?
  return ENV['EDITOR'] if ENV['EDITOR'] and not ENV['EDITOR'].empty?
  if Helpers::BaseHelpers.windows?
    'notepad'
  else
    %w(editor nano vi).detect do |editor|
      system("which #{editor} > /dev/null 2>&1")
    end
  end
end

.in_critical_section?Boolean



344
345
346
347
# File 'lib/pry/pry_class.rb', line 344

def self.in_critical_section?
  Thread.current[:pry_critical_section] ||= 0
  Thread.current[:pry_critical_section] > 0
end

.initObject

Basic initialization.



300
301
302
303
304
# File 'lib/pry/pry_class.rb', line 300

def self.init
  @plugin_manager ||= PluginManager.new
  reset_defaults
  locate_plugins
end

.initial_session?Boolean



210
211
212
# File 'lib/pry/pry_class.rb', line 210

def self.initial_session?
  @initial_session
end

.initial_session_setupObject

Do basic setup for initial session. Including: loading .pryrc, loading plugins, loading requires, and loading history.



104
105
106
107
108
109
110
111
112
113
114
115
# File 'lib/pry/pry_class.rb', line 104

def self.initial_session_setup
  return unless initial_session?
  @initial_session = false

  # note these have to be loaded here rather than in pry_instance as
  # we only want them loaded once per entire Pry lifetime.
  load_rc_files
  load_plugins if Pry.config.should_load_plugins
  load_requires if Pry.config.should_load_requires
  load_history if Pry.config.history.should_load
  load_traps if Pry.config.should_trap_interrupts
end

.load_file_at_toplevel(file) ⇒ Object

Load the given file in the context of Pry.toplevel_binding



55
56
57
58
59
# File 'lib/pry/pry_class.rb', line 55

def self.load_file_at_toplevel(file)
  toplevel_binding.eval(File.read(file), file)
rescue RescuableException => e
  puts "Error loading #{file}: #{e}\n#{e.backtrace.first}"
end

.load_file_through_repl(file_name) ⇒ Object

Execute the file through the REPL loop, non-interactively.



160
161
162
163
# File 'lib/pry/pry_class.rb', line 160

def self.load_file_through_repl(file_name)
  require "pry/repl_file_loader"
  REPLFileLoader.new(file_name).load
end

.load_historyObject

Load Readline history if required.



204
205
206
# File 'lib/pry/pry_class.rb', line 204

def self.load_history
  Pry.history.load
end

.load_rc_filesObject

Load HOME_RC_FILE and LOCAL_RC_FILE if appropriate This method can also be used to reload the files if they have changed.



63
64
65
66
67
68
69
# File 'lib/pry/pry_class.rb', line 63

def self.load_rc_files
  rc_files_to_load.each do |file|
    critical_section do
      load_file_at_toplevel(file)
    end
  end
end

.load_requiresObject

Load any Ruby files specified with the -r flag on the command line.



89
90
91
92
93
# File 'lib/pry/pry_class.rb', line 89

def self.load_requires
  Pry.config.requires.each do |file|
    require file
  end
end

.load_trapsObject

Trap interrupts on jruby, and make them behave like MRI so we can catch them.



97
98
99
# File 'lib/pry/pry_class.rb', line 97

def self.load_traps
  trap('INT'){ raise Interrupt }
end

.mainmain



41
42
43
# File 'lib/pry/pry_class.rb', line 41

def self.main
  @main ||= TOPLEVEL_BINDING.eval "self"
end

.Method(obj) ⇒ Object

If the given object is a Pry::Method, return it unaltered. If it's anything else, return it wrapped in a Pry::Method instance.



8
9
10
11
12
13
14
# File 'lib/pry/method.rb', line 8

def Method(obj)
  if obj.is_a? Pry::Method
    obj
  else
    Pry::Method.new(obj)
  end
end

.orig_reset_defaultsObject

Set all the configurable options back to their default values



6
7
8
9
10
11
12
13
# File 'lib/pry/test/helper.rb', line 6

def self.reset_defaults
  @initial_session = true
  self.config = Pry::Config.new Pry::Config::Default.new
  self.cli = false
  self.current_line = 1
  self.line_buffer = [""]
  self.eval_path = "(pry)"
end

.promptObject



28
29
30
# File 'lib/pry/pry_class.rb', line 28

def prompt
  config.prompt
end

.prompt=(value) ⇒ Object



24
25
26
# File 'lib/pry/pry_class.rb', line 24

def prompt=(value)
  config.prompt = value
end

.rc_files_to_loadObject

Load the local RC file (./.pryrc)



72
73
74
75
76
77
# File 'lib/pry/pry_class.rb', line 72

def self.rc_files_to_load
  files = []
  files << HOME_RC_FILE if Pry.config.should_load_rc
  files << LOCAL_RC_FILE if Pry.config.should_load_local_rc
  files.map { |file| real_path_to(file) }.compact.uniq
end

.real_path_to(file) ⇒ Object

Expand a file to its canonical name (following symlinks as appropriate)



80
81
82
83
84
85
86
# File 'lib/pry/pry_class.rb', line 80

def self.real_path_to(file)
  expanded = Pathname.new(File.expand_path(file)).realpath.to_s
  # For rbx 1.9 mode [see rubinius issue #2165]
  File.exist?(expanded) ? expanded : nil
rescue Errno::ENOENT
  nil
end

.reset_defaultsObject

Set all the configurable options back to their default values



290
291
292
293
294
295
296
297
# File 'lib/pry/pry_class.rb', line 290

def self.reset_defaults
  @initial_session = true
  self.config = Pry::Config.new Pry::Config::Default.new
  self.cli = false
  self.current_line = 1
  self.line_buffer = [""]
  self.eval_path = "(pry)"
end

.run_command(command_string, options = {}) ⇒ Object

Run a Pry command from outside a session. The commands available are those referenced by Pry.commands (the default command set).

Examples:

Run at top-level with no output.

Pry.run_command "ls"

Run under Pry class, returning only public methods.

Pry.run_command "ls -m", :target => Pry

Display command output.

Pry.run_command "ls -av", :show_output => true

Options Hash (options):

  • :target (Object, Binding)

    The object to run the command under. Defaults to TOPLEVEL_BINDING (main).

  • :show_output (Boolean)

    Whether to show command output. Defaults to true.



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
# File 'lib/pry/pry_class.rb', line 230

def self.run_command(command_string, options={})
  options = {
    :target => TOPLEVEL_BINDING,
    :show_output => true,
    :output => Pry.output,
    :commands => Pry.commands
  }.merge!(options)

  # :context for compatibility with <= 0.9.11.4
  target = options[:context] || options[:target]
  output = options[:show_output] ? options[:output] : StringIO.new

  pry = Pry.new(:output   => output, :target   => target, :commands => options[:commands])
  pry.eval command_string
end

.start(target = nil, options = {}) ⇒ Object

Start a Pry REPL. This method also loads ~/.pryrc and ./.pryrc as necessary the first time it is invoked.

Examples:

Pry.start(Object.new, :input => MyInput.new)

Options Hash (options):

  • :input (#readline)

    The object to use for input.

  • :output (#puts)

    The object to use for output.

  • :commands (Pry::CommandBase)

    The object to use for commands.

  • :hooks (Hash)

    The defined hook Procs.

  • :prompt (Array<Proc>)

    The array of Procs to use for prompts.

  • :print (Proc)

    The Proc to use for printing return values.

  • :quiet (Boolean)

    Omit the whereami banner when starting.

  • :backtrace (Array<String>)

    The backtrace of the session's binding.pry line, if applicable.

  • :target (Object)

    The initial context for this session.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
# File 'lib/pry/pry_class.rb', line 125

def self.start(target=nil, options={})
  return if ENV['DISABLE_PRY']
  options = options.to_hash

  if in_critical_section?
    output.puts "ERROR: Pry started inside Pry."
    output.puts "This can happen if you have a binding.pry inside a #to_s or #inspect function."
    return
  end

  options[:target] = Pry.binding_for(target || toplevel_binding)
  options[:hooks] = Pry::Hooks.from_hash options.delete(:hooks) if options.key?(:hooks)
  initial_session_setup

  # Unless we were given a backtrace, save the current one
  if options[:backtrace].nil?
    options[:backtrace] = caller

    # If Pry was started via `binding.pry`, elide that from the backtrace
    if options[:backtrace].first =~ /pry.*core_extensions.*pry/
      options[:backtrace].shift
    end
  end

  driver = options[:driver] || Pry::REPL

  # Enter the matrix
  driver.start(options)
rescue Pry::TooSafeException
  puts "ERROR: Pry cannot work with $SAFE > 0"
  raise
end

.toplevel_bindingObject



323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
# File 'lib/pry/pry_class.rb', line 323

def self.toplevel_binding
  unless defined?(@toplevel_binding) && @toplevel_binding
    # Grab a copy of the TOPLEVEL_BINDING without any local variables.
    # This binding has a default definee of Object, and new methods are
    # private (just as in TOPLEVEL_BINDING).
    TOPLEVEL_BINDING.eval <<-RUBY
      def self.__pry__
        binding
      end
      Pry.toplevel_binding = __pry__
      class << self; undef __pry__; end
    RUBY
  end
  @toplevel_binding.eval('private')
  @toplevel_binding
end

.toplevel_binding=(binding) ⇒ Object



340
341
342
# File 'lib/pry/pry_class.rb', line 340

def self.toplevel_binding=(binding)
  @toplevel_binding = binding
end

.view_clip(obj, options = {}) ⇒ String

An inspector that clips the output to max_length chars. In case of > max_length chars the `# notation is used.

Options Hash (options):

  • :max_length (Integer) — default: 60

    The maximum number of chars before clipping occurs.

  • :id (Boolean) — default: false

    Boolean to indicate whether or not a hex reprsentation of the object ID is attached to the return value when the length of inspect is greater than value of :max_length.



184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# File 'lib/pry/pry_class.rb', line 184

def self.view_clip(obj, options = {})
  max = options.fetch :max_length, 60
  id = options.fetch :id, false
  if obj.kind_of?(Module) && obj.name.to_s != "" && obj.name.to_s.length <= max
    obj.name.to_s
  elsif Pry.main == obj
    # special-case to support jruby.
    # fixed as of https://github.com/jruby/jruby/commit/d365ebd309cf9df3dde28f5eb36ea97056e0c039
    # we can drop in the future.
    obj.to_s
  elsif Pry.config.prompt_safe_objects.any? { |v| v === obj } && obj.inspect.length <= max
    obj.inspect
  else
    id == true ? "#<#{obj.class}:0x%x>" % (obj.object_id << 1) : "#<#{obj.class}>"
  end
rescue RescuableException
  "unknown"
end

.WrappedModule(obj) ⇒ Object

If the given object is a Pry::WrappedModule, return it unaltered. If it's anything else, return it wrapped in a Pry::WrappedModule instance.



7
8
9
10
11
12
13
# File 'lib/pry/wrapped_module.rb', line 7

def WrappedModule(obj)
  if obj.is_a? Pry::WrappedModule
    obj
  else
    Pry::WrappedModule.new(obj)
  end
end

Instance Method Details

#add_sticky_local(name) { ... } ⇒ Object

Add a sticky local to this Pry instance. A sticky local is a local that persists between all bindings in a session.

Yields:

  • The block that defines the content of the local. The local will be refreshed at each tick of the repl loop.



170
171
172
# File 'lib/pry/pry_instance.rb', line 170

def add_sticky_local(name, &block)
  config.extra_sticky_locals[name] = block
end

#complete(input) ⇒ Array<String>

Generate completions.



126
127
128
129
130
131
132
133
# File 'lib/pry/pry_instance.rb', line 126

def complete(input)
  return EMPTY_COMPLETIONS unless config.completer
  Pry.critical_section do
    config.completer.call input, :target => current_binding,
      :pry => self,
      :custom_completions => custom_completions
  end
end

#current_bindingBinding Also known as: current_context

The currently active Binding.



111
112
113
# File 'lib/pry/pry_instance.rb', line 111

def current_binding
  binding_stack.last
end

#ensure_correct_encoding!(val) ⇒ Object (private)

Force eval_string into the encoding of val. [Issue #284]



364
365
366
367
368
369
370
# File 'lib/pry/pry_instance.rb', line 364

def ensure_correct_encoding!(val)
  if @eval_string.empty? &&
      val.respond_to?(:encoding) &&
      val.encoding != @eval_string.encoding
    @eval_string.force_encoding(val.encoding)
  end
end

#eval(line, options = {}) ⇒ Boolean

Pass a line of input to Pry.

This is the equivalent of Binding#eval but with extra Pry!

In particular: 1. Pry commands will be executed immediately if the line matches. 2. Partial lines of input will be queued up until a complete expression has been accepted. 3. Output is written to #output in pretty colours, not returned.

Once this method has raised an exception or returned false, this instance is no longer usable. #exit_value will return the session's breakout value if applicable.

Options Hash (options):

  • :generated (Boolean)

    Whether this line was generated automatically. Generated lines are not stored in history.

Raises:

  • (Exception)

    If the user uses the raise-up command, this method will raise that exception.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
# File 'lib/pry/pry_instance.rb', line 212

def eval(line, options={})
  return false if @stopped

  exit_value = nil
  exception = catch(:raise_up) do
    exit_value = catch(:breakout) do
      handle_line(line, options)
      # We use 'return !@stopped' here instead of 'return true' so that if
      # handle_line has stopped this pry instance (e.g. by opening _pry_.repl and
      # then popping all the bindings) we still exit immediately.
      return !@stopped
    end
    exception = false
  end

  @stopped = true
  @exit_value = exit_value

  # TODO: make this configurable?
  raise exception if exception
  return false
end

#evaluate_ruby(code) ⇒ Object



326
327
328
329
330
331
332
333
334
335
# File 'lib/pry/pry_instance.rb', line 326

def evaluate_ruby(code)
  inject_sticky_locals!
  exec_hook :before_eval, code, self

  result = current_binding.eval(code, Pry.eval_path, Pry.current_line)
  set_last_result(result, code)
ensure
  update_input_history(code)
  exec_hook :after_eval, result, self
end

#exec_hook(name, *args, &block) ⇒ Object, Exception

Execute the specified hook. If executing a hook raises an exception, we log that and then continue sucessfully. To debug such errors, use the global variable $pry_hook_error, which is set as a result.



440
441
442
443
444
445
446
447
448
449
# File 'lib/pry/pry_instance.rb', line 440

def exec_hook(name, *args, &block)
  e_before = hooks.errors.size
  hooks.exec_hook(name, *args, &block).tap do
    hooks.errors[e_before..-1].each do |e|
      output.puts "#{name} hook failed: #{e.class}: #{e.message}"
      output.puts "#{e.backtrace.first}"
      output.puts "(see _pry_.hooks.errors to debug)"
    end
  end
end

#generate_prompt(prompt_proc, conf) ⇒ Object (private)



534
535
536
537
538
539
540
# File 'lib/pry/pry_instance.rb', line 534

def generate_prompt(prompt_proc, conf)
  if prompt_proc.arity == 1
    prompt_proc.call(conf)
  else
    prompt_proc.call(conf.object, conf.nesting_level, conf._pry_)
  end
end

#handle_line(line, options) ⇒ Object (private)



235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
# File 'lib/pry/pry_instance.rb', line 235

def handle_line(line, options)
  if line.nil?
    config.control_d_handler.call(@eval_string, self)
    return
  end

  ensure_correct_encoding!(line)
  Pry.history << line unless options[:generated]

  @suppress_output = false
  inject_sticky_locals!
  begin
    if !process_command_safely(line.lstrip)
      @eval_string << "#{line.chomp}\n" if !line.empty? || !@eval_string.empty?
    end
  rescue RescuableException => e
    self.last_exception = e
    result = e

    Pry.critical_section do
      show_result(result)
    end
    return
  end

  # This hook is supposed to be executed after each line of ruby code
  # has been read (regardless of whether eval_string is yet a complete expression)
  exec_hook :after_read, eval_string, self

  begin
    complete_expr = Pry::Code.complete_expression?(@eval_string)
  rescue SyntaxError => e
    output.puts "SyntaxError: #{e.message.sub(/.*syntax error, */m, '')}"
    reset_eval_string
  end

  if complete_expr
    if @eval_string =~ /;\Z/ || @eval_string.empty? || @eval_string =~ /\A *#.*\n\z/
      @suppress_output = true
    end

    # A bug in jruby makes java.lang.Exception not rescued by
    # `rescue Pry::RescuableException` clause.
    #
    # * https://github.com/pry/pry/issues/854
    # * https://jira.codehaus.org/browse/JRUBY-7100
    #
    # Until that gets fixed upstream, treat java.lang.Exception
    # as an additional exception to be rescued explicitly.
    #
    # This workaround has a side effect: java exceptions specified
    # in `Pry.config.exception_whitelist` are ignored.
    jruby_exceptions = []
    if Pry::Helpers::BaseHelpers.jruby?
      jruby_exceptions << Java::JavaLang::Exception
    end

    begin
      # Reset eval string, in case we're evaluating Ruby that does something
      # like open a nested REPL on this instance.
      eval_string = @eval_string
      reset_eval_string

      result = evaluate_ruby(eval_string)
    rescue RescuableException, *jruby_exceptions => e
      # Eliminate following warning:
      # warning: singleton on non-persistent Java type X
      # (http://wiki.jruby.org/Persistence)
      if Pry::Helpers::BaseHelpers.jruby? && e.class.respond_to?('__persistent__')
        e.class.__persistent__ = true
      end
      self.last_exception = e
      result = e
    end

    Pry.critical_section do
      show_result(result)
    end
  end

  throw(:breakout) if current_binding.nil?
end

#inject_local(name, value, b) ⇒ Object

Injects a local variable into the provided binding.



140
141
142
143
144
145
# File 'lib/pry/pry_instance.rb', line 140

def inject_local(name, value, b)
  Pry.current[:pry_local] = value.is_a?(Proc) ? value.call : value
  b.eval("#{name} = ::Pry.current[:pry_local]")
ensure
  Pry.current[:pry_local] = nil
end

#inject_sticky_locals!Object

Inject all the sticky locals into the current binding.



159
160
161
162
163
# File 'lib/pry/pry_instance.rb', line 159

def inject_sticky_locals!
  sticky_locals.each_pair do |name, value|
    inject_local(name, value, current_binding)
  end
end

#last_result_is_exception?Boolean



490
491
492
# File 'lib/pry/pry_instance.rb', line 490

def last_result_is_exception?
  @last_result_is_exception
end

#memory_sizeInteger



149
150
151
# File 'lib/pry/pry_instance.rb', line 149

def memory_size
  @output_array.max_size
end

#memory_size=(size) ⇒ Object



153
154
155
156
# File 'lib/pry/pry_instance.rb', line 153

def memory_size=(size)
  @input_array  = Pry::HistoryArray.new(size)
  @output_array = Pry::HistoryArray.new(size)
end

#pop_promptArray<Proc>

Pops the current prompt off of the prompt stack. If the prompt you are popping is the last prompt, it will not be popped. Use this to restore the previous prompt.

Examples:

prompt1 = [ proc { '>' }, proc { '>>' } ]
prompt2 = [ proc { '$' }, proc { '>' } ]
pry = Pry.new :prompt => prompt1
pry.push_prompt(prompt2)
pry.pop_prompt # => prompt2
pry.pop_prompt # => prompt1
pry.pop_prompt # => prompt1


572
573
574
# File 'lib/pry/pry_instance.rb', line 572

def pop_prompt
  prompt_stack.size > 1 ? prompt_stack.pop : prompt
end

#process_command(val) ⇒ Boolean

If the given line is a valid command, process it in the context of the current eval_string and binding.



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
# File 'lib/pry/pry_instance.rb', line 377

def process_command(val)
  val = val.chomp
  result = commands.process_line(val,
    :target => current_binding,
    :output => output,
    :eval_string => @eval_string,
    :pry_instance => self
  )

  # set a temporary (just so we can inject the value we want into eval_string)
  Pry.current[:pry_cmd_result] = result

  # note that `result` wraps the result of command processing; if a
  # command was matched and invoked then `result.command?` returns true,
  # otherwise it returns false.
  if result.command?
    if !result.void_command?
      # the command that was invoked was non-void (had a return value) and so we make
      # the value of the current expression equal to the return value
      # of the command.
      @eval_string.replace "::Pry.current[:pry_cmd_result].retval\n"
    end
    true
  else
    false
  end
end

#process_command_safely(val) ⇒ Boolean

Same as process_command, but outputs exceptions to #output instead of raising.



409
410
411
412
413
414
415
# File 'lib/pry/pry_instance.rb', line 409

def process_command_safely(val)
  process_command(val)
rescue CommandError, Slop::InvalidOptionError, MethodSource::SourceNotFoundError => e
  Pry.last_internal_error = e
  output.puts "Error: #{e.message}"
  true
end

#promptArray<Proc>

The current prompt. This is the prompt at the top of the prompt stack.

Examples:

self.prompt = Pry::SIMPLE_PROMPT
self.prompt # => Pry::SIMPLE_PROMPT


91
92
93
# File 'lib/pry/pry_instance.rb', line 91

def prompt
  prompt_stack.last
end

#prompt=(new_prompt) ⇒ Object



95
96
97
98
99
100
101
# File 'lib/pry/pry_instance.rb', line 95

def prompt=(new_prompt)
  if prompt_stack.empty?
    push_prompt new_prompt
  else
    prompt_stack[-1] = new_prompt
  end
end

#prompt_stackObject (private)

the array that the prompt stack is stored in



544
545
546
# File 'lib/pry/pry_instance.rb', line 544

def prompt_stack
  @prompt_stack ||= Array.new
end

#push_binding(object) ⇒ Object

Push a binding for the given object onto the stack. If this instance is currently stopped, mark it as usable again.



118
119
120
121
# File 'lib/pry/pry_instance.rb', line 118

def push_binding(object)
  @stopped = false
  binding_stack << Pry.binding_for(object)
end

#push_initial_binding(target = nil) ⇒ Object

Initialize this instance by pushing its initial context into the binding stack. If no target is given, start at the top level.



105
106
107
# File 'lib/pry/pry_instance.rb', line 105

def push_initial_binding(target=nil)
  push_binding(target || Pry.toplevel_binding)
end

#push_prompt(new_prompt) ⇒ Array<Proc>

Pushes the current prompt onto a stack that it can be restored from later. Use this if you wish to temporarily change the prompt.

Examples:

new_prompt = [ proc { '>' }, proc { '>>' } ]
push_prompt(new_prompt) # => new_prompt


556
557
558
# File 'lib/pry/pry_instance.rb', line 556

def push_prompt(new_prompt)
  prompt_stack.push new_prompt
end

#raise_up(*args) ⇒ Object



615
# File 'lib/pry/pry_instance.rb', line 615

def raise_up(*args); raise_up_common(false, *args); end

#raise_up!(*args) ⇒ Object



616
# File 'lib/pry/pry_instance.rb', line 616

def raise_up!(*args); raise_up_common(true, *args); end

#raise_up_common(force, *args) ⇒ Object

Raise an exception out of Pry.

See Kernel#raise for documentation of parameters. See rb_make_exception for the inbuilt implementation.

This is necessary so that the raise-up command can tell the difference between an exception the user has decided to raise, and a mistake in specifying that exception.

(i.e. raise-up RunThymeError.new should not be the same as raise-up NameError, "unititialized constant RunThymeError")

Raises:

  • (TypeError)


588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
# File 'lib/pry/pry_instance.rb', line 588

def raise_up_common(force, *args)
  exception = if args == []
                last_exception || RuntimeError.new
              elsif args.length == 1 && args.first.is_a?(String)
                RuntimeError.new(args.first)
              elsif args.length > 3
                raise ArgumentError, "wrong number of arguments"
              elsif !args.first.respond_to?(:exception)
                raise TypeError, "exception class/object expected"
              elsif args.length === 1
                args.first.exception
              else
                args.first.exception(args[1])
              end

  raise TypeError, "exception object expected" unless exception.is_a? Exception

  exception.set_backtrace(args.length === 3 ? args[2] : caller(1))

  if force || binding_stack.one?
    binding_stack.clear
    throw :raise_up, exception
  else
    binding_stack.pop
    raise exception
  end
end

#repl(target = nil) ⇒ Object

Potentially deprecated — Use Pry::REPL.new(pry, :target => target).start (If nested sessions are going to exist, this method is fine, but a goal is to come up with an alternative to nested sessions altogether.)



322
323
324
# File 'lib/pry/pry_instance.rb', line 322

def repl(target = nil)
  Pry::REPL.new(self, :target => target).start
end

#reset_eval_stringObject

Reset the current eval string. If the user has entered part of a multiline expression, this discards that input.



188
189
190
# File 'lib/pry/pry_instance.rb', line 188

def reset_eval_string
  @eval_string = ""
end

#run_command(val) ⇒ Pry::Command::VOID_VALUE

Run the specified command.

Examples:

pry_instance.run_command("ls -m")


422
423
424
425
426
427
428
429
430
# File 'lib/pry/pry_instance.rb', line 422

def run_command(val)
  commands.process_line(val,
    :eval_string => @eval_string,
    :target => current_binding,
    :pry_instance => self,
    :output => output
  )
  Pry::Command::VOID_VALUE
end

#select_promptString

Returns the appropriate prompt to use.



503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
# File 'lib/pry/pry_instance.rb', line 503

def select_prompt
  object = current_binding.eval('self')

  open_token = @indent.open_delimiters.any? ? @indent.open_delimiters.last :
    @indent.stack.last

  c = Pry::Config.from_hash({
                     :object         => object,
                     :nesting_level  => binding_stack.size - 1,
                     :open_token     => open_token,
                     :session_line   => Pry.history.session_line_count + 1,
                     :history_line   => Pry.history.history_line_count + 1,
                     :expr_number    => input_array.count,
                     :_pry_          => self,
                     :binding_stack  => binding_stack,
                     :input_array    => input_array,
                     :eval_string    => @eval_string,
                     :cont           => !@eval_string.empty?})

  Pry.critical_section do
    # If input buffer is empty then use normal prompt
    if eval_string.empty?
      generate_prompt(Array(prompt).first, c)

    # Otherwise use the wait prompt (indicating multi-line expression)
    else
      generate_prompt(Array(prompt).last, c)
    end
  end
end

#set_last_result(result, code = "") ⇒ Object

Set the last result of an eval. This method should not need to be invoked directly.



455
456
457
458
459
460
# File 'lib/pry/pry_instance.rb', line 455

def set_last_result(result, code="")
  @last_result_is_exception = false
  @output_array << result

  self.last_result = result unless code =~ /\A\s*\z/
end

#should_print?Boolean

Whether the print proc should be invoked. Currently only invoked if the output is not suppressed.



497
498
499
# File 'lib/pry/pry_instance.rb', line 497

def should_print?
  !@suppress_output
end

#show_result(result) ⇒ Object

Output the result or pass to an exception handler (if result is an exception).



338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
# File 'lib/pry/pry_instance.rb', line 338

def show_result(result)
  if last_result_is_exception?
    exception_handler.call(output, result, self)
  elsif should_print?
    print.call(output, result, self)
  else
    # nothin'
  end
rescue RescuableException => e
  # Being uber-paranoid here, given that this exception arose because we couldn't
  # serialize something in the user's program, let's not assume we can serialize
  # the exception either.
  begin
    output.puts "(pry) output error: #{e.inspect}"
  rescue RescuableException => e
    if last_result_is_exception?
      output.puts "(pry) output error: failed to show exception"
    else
      output.puts "(pry) output error: failed to show result"
    end
  end
ensure
  output.flush if output.respond_to?(:flush)
end

#sticky_localsObject



174
175
176
177
178
179
180
181
182
183
184
# File 'lib/pry/pry_instance.rb', line 174

def sticky_locals
  { _in_: input_array,
    _out_: output_array,
    _pry_: self,
    _ex_: last_exception && last_exception.wrapped_exception,
    _file_: last_file,
    _dir_: last_dir,
    _: proc { last_result },
    __: proc { output_array[-2] }
  }.merge(config.extra_sticky_locals)
end

#update_input_history(code) ⇒ Object

Update Pry's internal state after evalling code. This method should not need to be invoked directly.



478
479
480
481
482
483
484
485
# File 'lib/pry/pry_instance.rb', line 478

def update_input_history(code)
  # Always push to the @input_array as the @output_array is always pushed to.
  @input_array << code
  if code
    Pry.line_buffer.push(*code.each_line)
    Pry.current_line += code.each_line.count
  end
end