Module: Debugger

Module | Debugger
In: | lib/ruby-debug-base.rb ext/ruby_debug.c

## Summary

This is a singleton class allows controlling the debugger. Use it to start/stop debugger, set/remove breakpoints, etc.

### Methods

add_breakpoint add_catchpoint breakpoints catchpoints contexts current_context debug_at_exit debug_load handle_post_mortem interrupt interrupt_last keep_frame_binding= keep_frame_binding? last_context post_mortem post_mortem= post_mortem? remove_breakpoint resume skip source_reload start start_ started? stop suspend thread_context tracing tracing= track_frame_args= track_frame_args?

### Classes and Modules

Class Debugger::Context

### Constants

DEFAULT_START_SETTINGS | = | { :init => true, # Set $0 and save ARGV? :post_mortem => false, # post-mortem debugging on uncaught exception? :tracing => nil |  | Default options to Debugger.start
VERSION | = | rb_str_new2(DEBUG_VERSION)

### Attributes

handler | [RW] | interface modules provide `handler` object
last_exception | [RW] |
reload_source_on_change | [RW] | if `true`, checks the modification time of source files and reloads if it was modified

### Public Class methods

Debugger.add_breakpoint(source, pos, condition = nil) → breakpoint

Adds a new breakpoint. source is a name of a file or a class. pos is a line number or a method name if source is a class name. condition is a string which is evaluated to `true` when this breakpoint is activated.

Debugger.catchpoint(string) → string

Sets catchpoint. Returns the string passed.

Debugger.breakpoints → array

Returns an array of breakpoints.

Debugger.catchpoints → hash

Returns a current catchpoints, which is a hash exception names that will trigger a debugger when raised. The values are the number of times taht catchpoint was hit, initially 0.

Debugger.contexts → array

Returns an array of all contexts.

Debugger.current_context → context

Returns current context. Note: Debugger.current_context.thread == Thread.current

Debugger.debug_at_exit { block } → proc

Register `at_exit` hook which is escaped from the debugger. FOR INTERNAL USE ONLY.

Debugger.debug_load(file, stop = false, increment_start = false) → nil

Same as Kernel#load but resets current context‘s frames. `stop` parameter forces the debugger to stop at the first line of code in the `file` `increment_start` determines if start_count should be incremented. When

     control threads are used, they have to be set up before loading the
     debugger; so here +increment_start+ will be false.

FOR INTERNAL USE ONLY.

handle_post_mortem(exp)
interrupt()

Interrupts the current thread

interrupt_last()

Interrupts the last debugged thread

Debugger.keep_frame_binding = bool

Setting to `true` will make the debugger create frame bindings.

Debugger.keep_frame_binding? → bool

Returns `true` if the debugger will collect frame bindings.

Debugger.last_interrupted → context

Returns last debugged context.

post_mortem() {|| ...}

Activates the post-mortem mode. There are two ways of using it:

## Global post-mortem mode

By calling Debugger.post_mortem method without a block, you install at_exit hook that intercepts any unhandled by your script exceptions and enables post-mortem mode.

## Local post-mortem mode

If you know that a particular block of code raises an exception you can enable post-mortem mode by wrapping this block with Debugger.post_mortem, e.g.

      def offender
         raise 'error'
      end
      Debugger.post_mortem do
         ...
         offender
         ...
      end

Debugger.post_mortem = bool

Sets post-moterm flag. FOR INTERNAL USE ONLY.

Debugger.post_mortem? → bool

Returns `true` if post-moterm debugging is enabled.

Debugger.remove_breakpoint(id) → breakpoint

Removes breakpoint by its id. id is an identificator of a breakpoint.

Debugger.resume → Debugger

Resumes all contexts.

Debugger.skip { block } → obj or nil

The code inside of the block is escaped from the debugger.

source_reload()
Debugger.start_ → bool
Debugger.start_ { ... } → bool

This method is internal and activates the debugger. Use Debugger.start (from `lib/ruby-debug-base.rb`) instead.

The return value is the value of !Debugger.started? before issuing the `start`; That is, `true` is returned, unless debugger was previously started.

If a block is given, it starts debugger and yields to block. When the block is finished executing it stops the debugger with Debugger.stop method. Inside the block you will probably want to have a call to Debugger.debugger. For example:

      Debugger.start{debugger; foo}  # Stop inside of foo

Also, ruby-debug only allows one invocation of debugger at a time; nested Debugger.start‘s have no effect and you can‘t use this inside the debugger itself.

Note that if you want to completely remove the debugger hook, you must call Debugger.stop as many times as you called Debugger.start method.

Debugger.started? → bool

Returns `true` the debugger is started.

Debugger.stop → bool

This method disables the debugger. It returns `true` if the debugger is disabled, otherwise it returns `false`.

Note that if you want to complete remove the debugger hook, you must call Debugger.stop as many times as you called Debugger.start method.

Debugger.suspend → Debugger

Suspends all contexts.

Debugger.thread_context(thread) → context

Returns context of the thread passed as an argument.

Debugger.tracing → bool

Returns `true` if the global tracing is activated.

Debugger.tracing = bool

Sets the global tracing flag.

Debugger.track_frame_args = bool

Setting to `true` will make the debugger save argument info on calls.

Debugger.track_fame_args? → bool

Returns `true` if the debugger track frame argument values on calls.

### Public Instance methods

start(options={}, &block)

Debugger.start(options) -> bool Debugger.start(options) { … } -> obj

If it‘s called without a block it returns `true`, unless debugger was already started. If a block is given, it starts debugger and yields to block. When the block is finished executing it stops the debugger with Debugger.stop method.

If a block is given, it starts debugger and yields to block. When the block is finished executing it stops the debugger with Debugger.stop method. Inside the block you will probably want to have a call to Debugger.debugger. For example:

        Debugger.start{debugger; foo}  # Stop inside of foo

Also, ruby-debug only allows one invocation of debugger at a time; nested Debugger.start‘s have no effect and you can‘t use this inside the debugger itself.

Note that if you want to stop debugger, you must call Debugger.stop as many time as you called Debugger.start method.

`options` is a hash used to set various debugging options. Set :init true if you want to save ARGV and some variables which make a debugger restart possible. Only the first time :init is set true will values get set. Since ARGV is saved, you should make sure it hasn‘t been changed before the (first) call. Set :post_mortem true if you want to enter post-mortem debugging on an uncaught exception. Once post-mortem debugging is set, it can‘t be unset.

[Validate]