breakpoint

This will pop up an interactive ruby session at a pre-defined break point in a Ruby application. In this session you can examine the environment of the break point.

You can get a list of variables in the context using local_variables via local_variables. You can then examine their values by typing their names.

You can have a look at the call stack via caller.

The source code around the location where the breakpoint was executed can be examined via source_lines. Its argument specifies how much lines of context to display. The default amount of context is 5 lines. Note that the call to source_lines can raise an exception when it isn’t able to read in the source code.

breakpoints can also return a value. They will execute a supplied block for getting a default return value. A custom value can be returned from the session by doing +throw(:debug_return, value)+.

You can also give names to break points which will be used in the message that is displayed upon execution of them.

Here’s a sample of how breakpoints should be placed:

  class Person
    def initialize(name, age)
      @name, @age = name, age
      breakpoint("Person#initialize")
    end

    attr_reader :age
    def name
      breakpoint("Person#name") { @name }
    end
  end

  person = Person.new("Random Person", 23)
  puts "Name: #{person.name}"

And here is a sample debug session:

  Executing break point "Person#initialize" at file.rb:4 in `initialize'
  irb(#<Person:0x292fbe8>):001:0> local_variables
  => ["name", "age", "_", "__"]
  irb(#<Person:0x292fbe8>):002:0> [name, age]
  => ["Random Person", 23]
  irb(#<Person:0x292fbe8>):003:0> [@name, @age]
  => ["Random Person", 23]
  irb(#<Person:0x292fbe8>):004:0> self
  => #<Person:0x292fbe8 @age=23, @name="Random Person">
  irb(#<Person:0x292fbe8>):005:0> @age += 1; self
  => #<Person:0x292fbe8 @age=24, @name="Random Person">
  irb(#<Person:0x292fbe8>):006:0> exit
  Executing break point "Person#name" at file.rb:9 in `name'
  irb(#<Person:0x292fbe8>):001:0> throw(:debug_return, "Overriden name")
  Name: Overriden name

Breakpoint sessions will automatically have a few convenience methods available. See <a href="/rails/Breakpoint/CommandBundle">Breakpoint::CommandBundle</a> for a list of them.

Breakpoints can also be used remotely over sockets. This is implemented by running part of the IRB session in the application and part of it in a special client. You have to call Breakpoint.activate_drb to enable support for remote breakpoints and then run breakpoint_client.rb which is distributed with this library. See the documentation of Breakpoint.activate_drb for details.