Skip to content
This repository

Customizing Pry

Quick Menu:

Back to Main Menu

Overview

Pry allows a fair degree of customization via an easy to use API. Such customizations may be inserted in a user's .pryrc file, or even distributed as a plugin. We list below a number of config options and demonstrate how they can be used to customize Pry.

Note that some config options only define a default value which specific Pry instances can override. See Per-instance customization for more information.

Per-instance customization

Pry.config settings apply to all Pry instances, but some can be overridden for a specific instance. The settings that can be overridden are:

  • Pry.config.input
  • Pry.config.output
  • Pry.config.print
  • Pry.config.exception_handler
  • Pry.config.prompt
  • Pry.config.prompt_name

To override a given value, pass a new value as an option to the Pry.start method.

Example: Overriding a default at instantiation

Pry.config.input = File.open("test.rb")

# Note that above `Pry.config.input` default is not used as we
# provide our own `input` default below:
Pry.start binding, :input => StringIO.new("ls\nexit")

Back to top

Color

Pry.config.color is a boolean option determining whether color will be used. Setting it to false disables color (i.e syntax highlighting and other color effects).

Note that the toggle-color command can also be used to toggle color on and off while in a session.

Default value: true

Example: Disabling color

Pry.config.color = false

Back to top

Pager

Pry.config.pager is a boolean option determining whether a pager will be used for long output. Setting it to false disables the pager.

Currently only the less pager is supported, though a very simple custom pager is used if less is not available.

It may be necessary to turn paging off if you are running Pry from within an emacs shell or similar.

Default value: true

Example: Disabling paging

Pry.config.pager = false

Back to top

Auto indent

Pry.config.auto_indent is a boolean option determining whether automatic indenting of input will occur. Setting it to false disables automatic indenting.

Default value: true

Example: Disabling auto indenting

Pry.config.auto_indent = false

Back to top

Correct indent

Pry.config.correct_indent is a boolean option determining whether correction of indenting will occur (requires auto_indent to be set to true). Setting it to false disables correction.

Correction of indenting typically happens when a final end is entered for a block of code. Pry will determine the proper indentation level for the end and will adjust its indentation accordingly.

Indentation correction makes use of ansi codes that most terminals should support, but some may not. If you find that indentation correction is causing strange behavior on your terminal, you should consider turning this option off.

Default value: true

Example: Disabling correcting of indentation

Pry.config.correct_indent = false

Back to top

The command prefix

Pry.config.command_prefix is an option determining which command prefix (if any) should be used.

More detailed information on the command prefix can be found in the Command system section

Default value: "" (no prefix)

Example: Change the command prefix to %

Pry.config.command_prefix = "%"

Back to top

History

Pry.config.history is an option determining various properties of Pry history. It has three sub-properties:

  • Pry.config.history.should_save is a boolean option, it defaults to true
  • Pry.config.history.should_load is a boolean option, it defaults to true
  • Pry.config.history.file is a string option, it defaults to ~/.pry_history

More detailed information on Pry history can be found in the history section

Example: Change the history file to ~/.irb_history

Pry.config.history.file = "~/.irb_history"

Back to top

Editor

Pry.config.editor is an option determining which editor will be used by default by Pry commands.

It accepts either a string or a callable (i.e a proc). More detailed information on this config option can be found in the Editor Integration section.

Default value: $EDITOR (or nano if $EDITOR not defined)

Example: Setting a String

Pry.config.editor = "emacsclient"

Example: Setting a proc

Pry.config.editor = proc { |file, line| "emacsclient #{file} +#{line}" }

Back to top

Plugin loading

Pry.config.should_load_plugins is a boolean option determining whether plugins should be loaded. Setting it to false disables plugin loading.

It may be useful to set this option in your .pryrc file or in your program when invoking Pry at runtime

Default value: true

Example: Disabling plugin loading

Pry.config.should_load_plugins = false

Back to top

RC-file loading

Pry.config.should_load_rc is a boolean option determining whether the rc file (.pryrc) should be loaded. Setting it to false disables RC file loading.

It only makes sense to set this option when invoking Pry at runtime, however RC file loading can be disabled at the command line by running the Pry executable with the -f option.

Default value: true

Example: Disabling RC-file loading

Pry.config.should_load_rc = false

Back to top

The _in_ and _out_ cache size

Pry.config.memory_size is an option determining the size of the _in_ and _out_ cache. More detailed information on this option is found in the Entering Input section.

Default value: 100

Example: Increasing the size of the cache

Pry.config.memory_size = 300

Back to top

The prompt

Pry.config.prompt is an option determining the prompt displayed to the user when awaiting input.

Pry can accept two prompt-types for every prompt; the 'main prompt' and the 'wait prompt'. The main prompt is always used for the first line of input; the wait prompt is used in multi-line input to indicate that the current expression is incomplete and more lines of input are required.

A valid Pry prompt is either a single Proc object or a two element array of Proc objects. When an array is used the first element is the 'main prompt' and the last element is the 'wait prompt'. When a single Proc object is used it will be used for both the main prompt and the wait prompt.

Three parameters are passed into the prompt procs, the object that is the target of the session, the current nesting level, and a reference to the associated Pry instance. These objects can be used in the prompt, if desired.

Default value: Pry::DEFAULT_PROMPT

Example: Using one proc for both main and wait prompts

Pry.config.prompt = proc { |obj, nest_level, _| "#{obj}:#{nest_level}> " }

Example: Alternatively, provide two procs; one for main and one for wait

Pry.config.prompt = [ proc { "ENTER INPUT> " }, proc { "MORE INPUT REQUIRED!*" }]

Example: Overriding the default at instantiation

Pry.start binding, :prompt => [proc { "ENTER INPUT> " }, proc { "MORE INPUT REQUIRED!*" }]

Back to top

The prompt name

Pry.config.prompt_name is an option determining the string that prefixes the pry prompt. It accepts any string value. You would typically customize this on a per project basis so that the pry prompt reflects the name of the project you are in.

Default value: pry

Example: Setting the prompt name to match the folder name of your current Rails project. Put this in #{ Rails.root }/.pryrc

Pry.config.prompt_name = File.basename(Dir.pwd)

Example: Setting the prompt name to whatever you want.

Pry.config.prompt_name = 'my_project_name'

The input object

Pry.config.input is an option determining the input object - the object from which Pry retrieves its lines of input. Pry accepts any object that implements the readline method. This includes IO objects, StringIO, Readline, File and custom objects.

Note it is important to ensure that the last line of input is exit if you are running non-interactively as the input object will be reset to Pry.config.input on EOF and potentially loop forever waiting for input.

Default value: Readline

Example: Setting the input object to a StringIO

Pry.config.input = StringIO.new("@x = 10\nexit")
5.pry

5.instance_variable_get(:@x) #=> 10

Example: Overriding the default at instantiation

Pry.start binding, :input => StringIO.new("ls\nexit")

Back to top

The output object

Pry.config.output is an option determining the output object - the object to which Pry writes its output. Pry accepts any object that implements the puts method. This includes IO objects, StringIO, File and custom objects.

Default value: $stdout

Example: Setting the output object to a StringIO

Pry.config.output = StringIO.new

Example: Overriding the default at instantiation

Pry.start binding, :output => StringIO.new

Back to top

The print object

Pry.config.print is an option determining the print object - the Proc responsible for displaying expression evaluation output.

Two parameters are passed to the print Proc: these are the output object for the current session and the expression value to print. It is important that you write to the output object instead of just stdout so that all Pry output can be redirected if necessary.

Default value: Pry::DEFAULT_PRINT

Example: IRB-style evaluation output

Pry.config.print = proc { |output, value| output.puts "=> #{value.inspect}" }

Example: Overriding the default at instantiation

Pry.start binding, :print => proc { |output, value| output.puts "=> #{value.inspect}" }

Back to top

The exception handler

Pry.config.exception_handler is an option determining the exception handler object - the Proc responsible for dealing with exceptions raised by user input to the REPL.

Three parameters are passed to the exception handler Proc: these are the output object for the current session, the exception object that was raised inside the Pry session, and a reference to the associated Pry instance. As mentioned in the print object section (above) it is important you write to the output object and not just stdout.

Default value: Pry::DEFAULT_EXCEPTION_HANDLER

  Pry.config.exception_handler = proc do |output, exception, _|
    output.puts "#{exception.class}: #{exception.message}"
    output.puts "from #{exception.backtrace.first}"
  end

Documentation: Customising the exception handler

Back to top

The exception whitelist

Pry.config.exception_whitelist is an option determining which exceptions Pry should not catch.

Default value: [SystemExit, SignalException]

Documentation: Configuring which exceptions are caught

Back to top

The exception window size

Pry.config.default_window_size tells Pry how many lines cat --ex should show before and after the line that raised an Exception.

Default value: 5

Documentation: Configuring cat --ex

Back to top

The command set object

Pry.config.commands is an option determining the commands object - the command set (Pry::CommandSet) responsible for providing the commands for the session.

Default value: Pry::Commands

More detailed information on Pry commands can be found in the commands section

Example:

Pry.config.commands = Pry::CommandSet.new do
    import_from Pry::Commands, "ls"
    command "greet" do |name|
        output.puts "hello #{name}"
    end
end

Example: Overriding the default at instantiation

Pry.start binding, :commands => Pry::ExtendedCommands::Experimental

Back to top

Runtime customization

As discussed in Per-instance customization some config options can be customized for a specific Pry instance. However, Pry also allows these config options to be changed at runtime.

Inside a Pry session there is a special _pry_ local variable which represents the Pry instance managing the current session. We can simply assign to the relevant accessor on the _pry_ object to change the option we want.

Note that for every config option that can be configured on instantiation there is a corresponding accessor:

Example: Change the prompt at runtime

_pry_.prompt = proc { "> " }

Example: Change the input object at runtime

_pry_.input = StringIO.new("ls")

Back to top

Something went wrong with that request. Please try again.