Pry – Part 5 – Pry at runtime

Assuming you’ve halted the runtime at the point where you invoked the Pry REPL (see Pry – Part 4), you should have the Pry REPL.

A. The main ways of navigating the stack are the ls and cd commands.

ls shows you methods, constants and variables.

cd moves you into the new context (object or scope).

1. ls

 ls -h
Usage: ls [-m|-M|-p|-pM] [-q|-v] [-c|-i] [Object]
       ls [-g] [-l]

ls shows you which methods, constants and variables are accessible to Pry. By
default it shows you the local variables defined in the current shell, and any
public methods or instance variables defined on the current object.

The colours used are configurable using Pry.config.ls.*_color, and the separator
is Pry.config.ls.separator.

Pry.config.ls.ceiling is used to hide methods defined higher up in the
inheritance chain, this is by default set to [Object, Module, Class] so that
methods defined on all Objects are omitted. The -v flag can be used to ignore
this setting and show all methods, while the -q can be used to set the ceiling
much lower and show only methods defined on the object or its direct class.

    -m, --methods               Show public methods defined on the Object (default)
    -M, --instance-methods      Show methods defined in a Module or Class
    -p, --ppp                   Show public, protected (in yellow) and private (in green) methods
    -q, --quiet                 Show only methods defined on object.singleton_class and object.class
    -v, --verbose               Show methods and constants on all super-classes (ignores Pry.config.ls.ceiling)
    -g, --globals               Show global variables, including those builtin to Ruby (in cyan)
    -l, --locals                Show hash of local vars, sorted by descending size
    -c, --constants             Show constants, highlighting classes (in blue), and exceptions (in purple).
                                Constants that are pending autoload? are also shown (in yellow)
    -i, --ivars                 Show instance variables (in blue) and class variables (in bright blue)
    -G, --grep                  Filter output by regular expression
    -h, --help                  Show this message.

2. cd

> cd -h
Usage: cd [OPTIONS] [--help]

Move into new context (object or scope). As in UNIX shells use `cd ..` to go
back, `cd /` to return to Pry top-level and `cd -` to toggle between last two
scopes. Complex syntax (e.g `cd ../@x/y`) also supported.

cd @x
cd ..
cd /
cd -

https://github.com/pry/pry/wiki/State-navigation#wiki-Changing_scope

    -h, --help      Show this message.

B. Apart from navigating state, there are two other commands that are very useful, show-method and show-doc.

1. show-method
This shows the source for a method or class.

> show-method -h
Usage:   show-source [OPTIONS] [METH|CLASS]
Aliases: $, show-method

Show the source for a method or class. Tries instance methods first and then
methods by default.

show-source hi_method
show-source hi_method
show-source Pry#rep     # source for Pry#rep method
show-source Pry         # for Pry class
show-source Pry -a      # for all Pry class definitions (all monkey patches)
show-source Pry --super # for superclass of Pry (Object class)

https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method

    -s, --super             Select the 'super' method. Can be repeated to traverse the ancestors
    -l, --line-numbers      Show line numbers
    -b, --base-one          Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)
    -a, --all               Show all definitions and monkeypatches of the module/class
    -h, --help              Show this message.

2. show-doc shows the documentation by running the method comments through rdoc or yard

> show-method -h
Usage:   show-source [OPTIONS] [METH|CLASS]
Aliases: $, show-method

Show the source for a method or class. Tries instance methods first and then
methods by default.

show-source hi_method
show-source hi_method
show-source Pry#rep     # source for Pry#rep method
show-source Pry         # for Pry class
show-source Pry -a      # for all Pry class definitions (all monkey patches)
show-source Pry --super # for superclass of Pry (Object class)

https://github.com/pry/pry/wiki/Source-browsing#wiki-Show_method

    -s, --super             Select the 'super' method. Can be repeated to traverse the ancestors
    -l, --line-numbers      Show line numbers
    -b, --base-one          Show line numbers but start numbering at 1 (useful for `amend-line` and `play` commands)
    -a, --all               Show all definitions and monkeypatches of the module/class
    -h, --help              Show this message.

how do you change the syntax highlighting in Pry? Use Pry theme

Colours in Pry not quite how you want them?

Here’s how to change them:

[~]$ gem install pry-theme
[~]$ pry
Can't find `Pry.config.theme` definition in your `~/.pryrc`.
Using "pry-classic" theme now.
[1] pry(main)> pry-theme -l

[github]
Based on github theme
---
class Theme
  def method
    @ivar, @@cvar, lvar = 10_000, 400.00, "string"
  end
end

[monokai]
Based on Wimer Hazenberg's theme
---
class Theme
  def method
    @ivar, @@cvar, lvar = 10_000, 400.00, "string"
  end
end

* [pry-classic]
Default Pry theme
---
class Theme
  def method
    @ivar, @@cvar, lvar = 10_000, 400.00, "string"
  end
end

To get rid of the warning message create a pryrc file and add a theme, e.g.

Pry.config.theme="pry-modern"

https://github.com/kyrylo/pry-theme

On the Mac, another alternative is to just change your Terminal preferences.

Questions on pry?

Hang out at #pry on irc.freenode.net

Pry – Part 4 – Debugger

You can inject a Pry REPL directly into somewhere that you want to debug.

pry -r ./stack.rb

Here’s an example of runtime invocation:

test.rb

require 'pry'
# set x to 10
x = 10

# start a REPL session
binding.pry

# program resumes here (after pry session)
puts "program resumes here. Value of x is: #{x}."

when run using ruby test.rb:

$ ruby test.rb 

From: /Users/snowcrash/Developer/Ruby/Pry/test.rb @ line 6 :

    1: require 'pry'
    2: # set x to 10
    3: x = 10
    4: 
    5: # start a REPL session
 => 6: binding.pry
    7: 
    8: # program resumes here (after pry session)
    9: puts "program resumes here. Value of x is: #{x}."

[1] pry(main)> 

So, code is shown around the REPL invocation line with a cursor showing where the runtime has stopped.

http://pryrepl.org

For the best source of Pry documentation: https://github.com/pry/pry/wiki

For more on Pry at runtime, see Pry – Part 5 – Pry at runtime.

Pry – Part 3

So, assuming you’ve been through Part 1 and Part 2, you should have the Hello World gem installed.

We can cd directly into the gem’s source code and look at it directly:

gem-cd hello_world

We can run commands directly by prefixing them with a period.
E.g. look at the file structure layout using tree:

[32] pry(HelloWorld):1> .tree
.
├── Manifest
├── README.rdoc
├── Rakefile
├── hello_world.gemspec
└── lib
    └── hello_world.rb

1 directory, 5 files
[33] pry(HelloWorld):1> .cd lib/
[34] pry(HelloWorld):1> .cat hello_world.rb
module HelloWorld
  def self.say_hello
    puts 'hello world'
  end
end[35] pry(HelloWorld):1> 

Note that you may need to install tree on MacOSX. E.g.

brew install tree

You can cdd into other objects, e.g.

[35] pry(HelloWorld):1> cd 12 12
[36] pry(12):2> cd String
[37] pry(String):3> 

The prompt updates to show you what object you’re in.

And:

nesting

shows you the current nesting status, e.g.

[37] pry(String):3> nesting
Nesting status:
--
0. main (Pry top level)
1. HelloWorld
2. 12
3. String
[38] pry(String):3> 

Pop out using:

cd ..

or jump to an index:

[38] pry(String):3> jump-to 0
[39] pry(main)>

Input buffers:
Clear out:

[39] pry(main)> def helo(name)
[39] pry(main)*   show-input
1: def helo(name)
[39] pry(main)*   !
Input buffer cleared!
[40] pry(main)>

Amend:
Say you want to amend a line:

[40] pry(main)> def hello(name)
[40] pry(main)*   "Hello, #{name}
[40] pry(main)* show-input
1: def hello(name)
2:   "Hello, #{name}
[40] pry(main)* amend-line 2 "Hello, #{name}"
1: def hello(name)
2:   "Hello, #{name}"
[40] pry(main)* end  
=> nil
[41] pry(main)> hello "Me"
=> "Hello, Me"
[42] pry(main)> 

Pry – Part 2

More on using Pry.

Let’s play around with it a little using the Hello World gem (if you haven’t already installed it, use: gem install hello_world). Then, in pry:

require 'hello_world'

Some useful commands:

1. ls:
ls shows you which methods, constants and variables are accessible to Pry. By
default it shows you the local variables defined in the current shell, and any
public methods or instance variables defined on the current object.

So we can list, class methods:

ls HelloWorld -M
[]

i.e. nothing.

Instance methods:

ls HelloWorld -m
HelloWorld.methods: say_hello

i.e. this method is available.

And this is the default, i.e.

ls HelloWorld
HelloWorld.methods: say_hello

e.g.:

HelloWorld.say_hello
hello world
=> nil

2. cd
cd moves you into a new context (object or scope). As in UNIX shells use cd .. to go
back, cd / to return to Pry top-level and cd – to toggle between last two
scopes.

So,

cd HelloWorld

and now:

pry(HelloWorld):1> self
=> HelloWorld
pry(HelloWorld):1> ls -m
HelloWorld.methods: say_hello

So, we can invoke it like this:

pry(HelloWorld):1> say_hello
hello world
=> nil

However, if we’re only interested in the output value and not the return value then we can use a semi-colon:

pry(HelloWorld):1> say_hello;
hello world
pry(HelloWorld):1> 
[23] pry(HelloWorld):1> gem-cd hello_world
/Users/snowcrash/.rvm/gems/ruby-1.9.3-p327/gems/hello_world-0.0.2
[24] pry(HelloWorld):1> .pwd
/Users/snowcrash/.rvm/gems/ruby-1.9.3-p327/gems/hello_world-0.0.2

More in Pry – Part 3.

Pry – an IRB alternative and runtime developer console – Part 1

A brief guide to Pry:

1. Install
gem install pry pry-doc –no-ri –no-rdoc

pry-doc lets you browse core C source
Other flags: don’t bother installing the docs ‘cos it takes extra time

2. Features
Run pry

Useful commands:
a. help help

Note: pry offers command line completion.

b. show-doc
Show the documentation for a method or class. Tries instance methods first and
then methods by default.

e.g. if we create an object like this:
s = “pry”
then we can do:
show-doc s.each_line

From: string.c (C Method):
Owner: String
Visibility: public
Signature: each_line(*arg1)
Number of lines: 30

etc…

Note, show-doc is smart. Can even read ri syntax.
E.g.
show-doc String#each_line
which gives the same documentation.

c. show-method
e.g.
show-method s.each_line

shows each line of the implementation for String.

-l gives you line numbers.

d. Share your code
gist s.each_line
creates a gist and copies the URL to your clipboard.

More info here: http://pryrepl.org
The screencast there is great although it’s for a slightly older version of pry.
E.g. autocomplete on gist-method doesn’t work because this method doesn’t exist any more. It’s just called gist now.

See also: http://railscasts.com/episodes/280-pry-with-rails

This post is getting rather long so the rest will be in Part 2.