Skip to content
This repository

Shell Integration

Quick Menu:

Overview

It can be convenient sometimes to access a system shell from within a REPL session. Pry allows arbitrary shell commands to be executed inside the REPL as well as providing a few custom shell commands of its own.

Execute arbitrary shell commands

In Pry 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.

Example:

pry(main)> .ls -l
total 104
-rw-r--r--   1 john  staff   5109 21 Jun 03:16 CHANGELOG
-rw-r--r--   1 john  staff   1106 21 Apr 19:52 LICENSE
-rw-r--r--   1 john  staff  20538 18 Jun 06:13 README.markdown
-rw-r--r--   1 john  staff   2248 18 Jun 06:13 Rakefile
drwxr-xr-x   4 john  staff    136 21 Jun 03:18 lib
pry(main)> .git log -1 --stat
commit 5c4feac5005b7f74451fd860fa4002f7a2d316e1
Author: John Mair <jrmair@gmail.com>
Date:   Tue Jun 21 03:17:04 2011 +1200

    version 0.9.2 release, updated CHANGELOG and version

 CHANGELOG          |    5 +++++
 lib/pry/version.rb |    2 +-
 2 files changed, 6 insertions(+), 1 deletions(-)
pry(main)> 

Ruby code can also be interpolated into shell commands using the normal #{} string interpolation syntax.

Example:

pry(main)> x = "[mM]"
=> "[mM]"
pry(main)> .ls | grep #{x}
Documents
Movies
Music
VirtualBox VMs
pry(main)> 

Back to the top

Shell mode

As a further convenience Pry features a shell-mode command to incorporate the present working directory into the Pry prompt and bring in (limited at this stage, sorry) file name completion. shell-mode makes it easier to make effective use of shell commands. Entering shell-mode a second time returns you to the ordinary Pry prompt.

Example:

pry(main)> shell-mode
pry main:/Users/john/ruby/projects/pry $ .cd ..
pry main:/Users/john/ruby/projects $ .cd ~
pry main:/Users/john $ .pwd
/Users/john
pry main:/Users/john $ shell-mode
pry(main)>

Back to the top

The cat command**

The standard system cat command is accessible via .cat (note the preceding '.' indicating a shell command) however Pry also features its own cat command invoked simply by cat (no . prefix).

Pry's built-in cat command features automatic syntax highlighting for a number of file types, including: .rb, .py, .cpp, .java, .json, .php, .xml and more. Further, a pager is automatically used when the output spans more than one page.

Pry's cat command supports a number of options:

  • The -l option causes line numbers to be displayed along side each line.
  • The -t [FILE_TYPE] forces the file to be syntax highlighted as the specified file type. Accepted types include: ruby, cpp, python, c, html, javascript, diff, among others.
  • The -s [START_LINE] specifies the line of the file with which to begin the cat. Likewise the -e [END_LINE] specifies the line of the file to end the cat. Note that negative numbers are accepted (as in most Pry commands); and follow the typical Ruby Array approach where -1 indicates the last line, and -2 indicates the second-to-last.

Some use cases for cat are for code browsing (facilitated by syntax highlighting, the pager, and line numbers), cat is also very useful when combined with the play command where lines are extracted from files to replay inside the REPL.

Example: cat + play

pry(main)> cat pry_instance.rb -l -s 470 
470:     #   valid_expression?("class Hello") #=> false
471:     #   valid_expression?("class Hello; end") #=> true
472:     def valid_expression?(code)
473:       RubyParser.new.parse(code)
474:       true
475:     rescue Racc::ParseError, SyntaxError
476:       false
477:     end
478:   end
479: end
pry(main)> play -f pry_instance.rb --lines 472..477
=> nil
pry(main)> show-method valid_expression?

From: (pry) @ line 72:
Number of lines: 6

def valid_expression?(code)
  RubyParser.new.parse(code)
  true
rescue Racc::ParseError, SyntaxError
  false
end

Back to the top

The _file_ and _dir_ locals**

Some commands such as show-method, show-doc, show-command, stat and cat update the _file_ and _dir_ local variables after they run. These locals contain the full path to the file involved in the last command as well as the directory containing that file.

You can then use these special locals in conjunction with Pry commands to do such things as change directory into the directory containing the file, open the file in an editor, display the file using cat, and so on.

Example:

pry(main)> show-method pry

From: /Users/john/ruby/projects/pry/lib/pry/core_extensions.rb @ line 19:
Number of lines: 3

def pry(target=self)
  Pry.start(target)
end
pry(main)> _file_
=> "/Users/john/ruby/projects/pry/lib/pry/core_extensions.rb"
pry(main)> cat #{_file_} -e 2
class Object
  # Start a Pry REPL.
pry(main)> shell-mode
pry main:/ $ .cd #{_dir_}
pry main:/Users/john/ruby/projects/pry/lib/pry $ 

Back to the top

Something went wrong with that request. Please try again.