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 Breakpoint::CommandBundle 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.</person:0x292fbe8></person:0x292fbe8></person:0x292fbe8></person:0x292fbe8></person:0x292fbe8></person:0x292fbe8></person:0x292fbe8>

Source Code

# File breakpoint.rb, line 109
def breakpoint(id = nil, context = nil, &block)
  callstack = caller
  callstack.slice!(0, 3) if callstack.first["breakpoint"]
  file, line, method = *callstack.first.match(/^(.+?):(\d+)(?::in `(.*?)')?/).captures

  message = "Executing break point " + (id ? "#{id.inspect} " : "") +
            "at #{file}:#{line}" + (method ? " in `#{method}'" : "")

  if context then
    return handle_breakpoint(context, message, file, line, &block)
  end

  Binding.of_caller do |binding_context|
    handle_breakpoint(binding_context, message, file, line, &block)
  end
end