Pry

Pry logo

Alumni:

Conrad Irwin
Ryan Fitzgerald
Robert Gleeson

Links:

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

Introduction
Key features
Installation
Overview
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

Pry

Install / Use

README

Pry

Table of Contents