Pry

© John Mair (banisterfiend) 2018
(Creator)

© Kyrylo Silin (kyrylosilin) 2018
(Maintainer)

Alumni:

• Conrad Irwin
• Ryan Fitzgerald
• Robert Gleeson

Links:

• https://pry.github.io/
• YARD API documentation
• Wiki

Table of Contents

• Introduction
• Key features
• Installation
• Overview
  • Commands
  • Navigating around state
  • Runtime invocation
  • Command Shell Integration
  • Code Browsing
  • Documentation Browsing
  • Edit methods
  • Live Help System
  • Use Pry as your Rails Console
  • Syntax Highlighting
• Supported Rubies
• Contact
• License
• Contributors

Introduction

Pry is a runtime developer console and IRB alternative with powerful
introspection capabilities. Pry aims to be more than an IRB replacement. It is
an attempt to bring REPL driven programming to the Ruby language.

Key features

• Source code browsing (including core C source with the pry-doc gem)
• Documentation browsing
• Live help system
• Open methods in editors (edit Class#method)
• Syntax highlighting
• Command shell integration (start editors, run git, and rake from within Pry)
• Gist integration
• Navigation around state (cd, ls and friends)
• Runtime invocation (use Pry as a developer console or debugger)
• Exotic object support (BasicObject instances, IClasses, …)
• A powerful and flexible command system
• Ability to view and replay history
• Many convenience commands inspired by IPython, Smalltalk and other advanced
  REPLs
• A wide-range number of
  plugins that provide
  remote sessions, full debugging functionality, and more.

Installation

Bundler

gem 'pry', '~> 0.15.0'

Manual

gem install pry

Overview

Pry is fairly flexible and allows significant user
customization.
It is trivial to read from any object that has a readline method and
write to any object that has a puts method. Many other aspects of Pry are
also configurable, making it a good choice for implementing custom shells.

Pry comes with an executable so it can be invoked at the command line. Just
enter pry to start. A pryrc file in $XDG_CONFIG_HOME/pry/ or the user’s
home directory will be loaded if it exists. Type pry --help at the command
line for more information.

Commands

Nearly every piece of functionality in a Pry session is implemented as a
command. Commands are not methods and must start at the beginning of a line,
with no whitespace in between. Commands support a flexible syntax and allow
‘options’ in the same way as shell commands, for example the following Pry
command will show a list of all private instance methods (in scope) that begin
with ‘pa’

pry(YARD::Parser::SourceParser):5> ls -Mp --grep ^pa
YARD::Parser::SourceParser#methods: parse  parser_class  parser_type  parser_type=  parser_type_for_filename

Navigating around state

Pry allows us to pop in and out of different scopes (objects) using the cd
command. This enables us to explore the run-time view of a program or
library. To view which variables and methods are available within a particular
scope we use the versatile ls
command.

Here we will begin Pry at top-level, then Pry on a class and then on an instance
variable inside that class:

pry(main)> class Hello
pry(main)*   @x = 20
pry(main)* end
=> 20
pry(main)> cd Hello
pry(Hello):1> ls -i
instance variables: @x
pry(Hello):1> cd @x
pry(20):2> self + 10
=> 30
pry(20):2> cd ..
pry(Hello):1> cd ..
pry(main)> cd ..

The number after the : in the pry prompt indicates the nesting level. To
display more information about nesting, use the nesting command. E.g

pry("friend"):3> nesting
Nesting status:
0. main (Pry top level)
1. Hello
2. 100
3. "friend"
=> nil

We can then jump back to any of the previous nesting levels by using the
jump-to command:

pry("friend"):3> jump-to 1
=> 100
pry(Hello):1>

Runtime invocation

Pry can be invoked in the middle of a running program. It opens a Pry session at
the point it’s called and makes all program state at that point available. It
can be invoked on any object using the my_object.pry syntax or on the current
binding (or any binding) using binding.pry. The Pry session will then begin
within the scope of the object (or binding). When the session ends the program
continues with any modifications you made to it.

This functionality can be used for such things as: debugging, implementing
developer consoles and applying hot patches.

code:

# test.rb
require 'pry'

class A
  def hello() puts "hello world!" end
end

a = A.new

# start a REPL session
binding.pry

# program resumes here (after pry session)
puts "program resumes here."

Pry session:

pry(main)> a.hello
hello world!
=> nil
pry(main)> def a.goodbye
pry(main)*   puts "goodbye cruel world!"
pry(main)* end
=> :goodbye
pry(main)> a.goodbye
goodbye cruel world!
=> nil
pry(main)> exit

program resumes here.

Command Shell Integration

A line of input that begins with a ‘.’ will be forwarded to the command
shell. This enables us to navigate the file system, spawn editors, and run git
and rake directly from within Pry.

Further, we can use the shell-mode command to incorporate the present working
directory into the Pry prompt and bring in (limited at this stage, sorry) file
name completion. We can also interpolate Ruby code directly into the shell by
using the normal #{} string interpolation syntax.

In the code below we’re going to switch to shell-mode and edit the pryrc
file. We’ll then cat its contents and reload the file.

pry(main)> shell-mode
pry main:/home/john/ruby/projects/pry $ .cd ~
pry main:/home/john $ .emacsclient .pryrc
pry main:/home/john $ .cat .pryrc
def hello_world
  puts "hello world!"
end
pry main:/home/john $ load ".pryrc"
=> true
pry main:/home/john $ hello_world
hello world!

We can also interpolate Ruby code into the shell. In the example below we use
the shell command cat on a random file from the current directory and count
the number of lines in that file with wc:

pry main:/home/john $ .cat #{Dir['*.*'].sample} | wc -l
44

Code Browsing

You can browse method source code with the show-source command. Nearly all
Ruby methods (and some C methods, with the pry-doc gem) can have their source
viewed. Code that is longer than a page is sent through a pager (such as less),
and all code is properly syntax highlighted (even C code).

The show-source command accepts two syntaxes, the typical ri Class#method
syntax and also simply the name of a method that’s in scope. You can optionally
pass the -l option to show-source to include line numbers in the output.

In the following example we will enter the Pry class, list the instance
methods beginning with ‘se’ and display the source code for the set_last_result method:

pry(main)> cd Pry
pry(Pry):1> ls -M --grep se
Pry#methods: raise_up  raise_up!  raise_up_common  reset_eval_string  select_prompt  set_last_result
pry(Pry):1> show-source set_last_result -l

From: /home/john/ruby/projects/pry/lib/pry/pry_instance.rb:405:
Owner: Pry
Visibility: public
Signature: set_last_result(result, code=?)
Number of lines: 6

405: def set_last_result(result, code = "")
406:   @last_result_is_exception = false
407:   @output_ring << result
408:
409:   self.last_result = result unless code =~ /\A\s*\z/
410: end

Note that we can also view C methods (from Ruby Core) using the
pry-doc plugin; we also show off the alternate syntax for
show-source:

pry(main)> show-source Array#select

From: array.c in Ruby Core (C Method):
Number of lines: 15

static VALUE
rb_ary_select(VALUE ary)
{
    VALUE result;
    long i;

    RETURN_ENUMERATOR(ary, 0, 0);
    result = rb_ary_new2(RARRAY_LEN(ary));
    for (i = 0; i < RARRAY_LEN(ary); i++) {
        if (RTEST(rb_yield(RARRAY_PTR(ary)[i]))) {
            rb_ary_push(result, rb_ary_elt(ary, i));
        }
    }
    return result;
}

Documentation Browsing

One use-case for Pry is to explore a program at run-time by cd-ing in and out
of objects and viewing and invoking methods. In the course of exploring it may
be useful to read the documentation for a specific method that you come
across. show-source command supports two syntaxes - the
normal ri syntax as well as accepting the name of any method that is currently
in scope.

The Pry documentation system does not rely on pre-generated rdoc or ri,
instead it grabs the comments directly above the method on demand. This results
in speedier documentation retrieval and allows the Pry system to retrieve
documentation for methods that would not be picked up by rdoc. Pry also has a
basic understanding of both the rdoc and yard formats and will attempt to syntax
highlight the documentation appropriately.

Nonetheless, the ri functionality is very good and has an advantage over Pry’s
system in that it allows documentation lookup for classes as well as
methods. Pry therefore has good integration with ri through the ri
command. The syntax for the command is exactly as it would be in command-line -
so it is not necessary to quote strings.

In our example we will enter the Gem class and view the documentation for the
try_activate method:

pry(main)> cd Gem
pry(Gem):1> show-source try_activate -d

From: /Users/john/rbenv/versions/2.7.1/lib/ruby/2.7.0/rubygems.rb:194:
Owner: #<Class:Gem>
Visibility: public
Signature: try_activate(path)
Number of lines: 28

Try to activate a gem containing path. Returns true if
activation succeeded or wasn't needed because it was already
activated. Returns false if it can't find the path in a gem.

def self.try_activate(path)
  # finds the _latest_ version... regardless of loaded specs and their deps
  # if another gem had a requirement that would mean we shouldn't
  # activate the latest version, then either it would already be activated
  # or if it was ambiguous (and thus unresolved) the code in our custom
  # require will try to activate the more specific version.

  spec = Gem::Specification.find_by_path path
pry(Gem):1>

We can also use ri in the normal way:

pry(main) ri Array#each
----------------------------------------------------------- Array#each
     array.each {|item| block }   ->   array
------------------------------------------------------------------------
     Calls _block_ once for each element in _self_, passing that element
     as a parameter.

        a = [ "a", "b", "c" ]
        a.each {|x| print x, " -- " }

     produces:

        a -- b -- c --

Edit methods

You can use edit Class#method or edit my_method (if the method is in scope)
to open a method for editing directly in your favorite editor. Pry has knowledge
of a few different editors and will attempt to open the file at the line the
method is defined.

You can set the editor to use by assigning to the Pry.editor
accessor. Pry.editor will default to $EDITOR or failing that will use nano
as the backup default. The file that is edited will be automatically reloaded
after exiting the editor - reloading can be suppressed by passing the
--no-reload option to edit

In the example below we will set our default editor to “emacsclient” and open
the Pry#repl method for editing:

pry(main)> Pry.editor = "emacsclient"
pry(main)> edit Pry#repl

Live Help System

Many other commands are available in Pry; to see the full list type help at
the prompt. A short description of each command is provided with basic
instructions for use; some commands have a more extensive help that can be
accessed via typing command_name --help. A command will typically say in its
description if the --help option is available.

Use Pry as your Rails Console

You can run a Pry console in your app’s environment using Pry’s -r flag:

pry -r ./config/environment

Or start the rails console (bin/rails console) and then type pry.

It’s also possible to use Pry as your Rails console by adding the pry-rails
gem to your Gemfile. This replaces the
default console with Pry, in addition to loading the Rails console helpers and
adding some useful Rails-specific commands.

Note that pry-rails is not currently maintained.

Also check out the
wiki
for more information about integrating Pry with Rails.

Syntax Highlighting

Syntax highlighting is on by default in Pry. If you want to change the colors,
check out the pry-theme gem.

You can toggle the syntax highlighting on and off in a session by using the
toggle-color command. Alternatively, you can turn it off permanently by
putting the line Pry.color = false in your pryrc file.

Supported Rubies

• CRuby >= 2.0.0
• JRuby >= 9.0

Contact

In case you have a problem, question or a bug report, feel free to:

• ask a question on IRC (#pry on Freenode)
• file an issue
• tweet at us

License

The project uses the MIT License. See LICENSE.md for details.

Contributors

Pry is primarily the work of John Mair (banisterfiend), for full list
of contributors see the
contributors graph.