ruby-debug 0.11 Command Documatation

ruby-debug-man.md

ruby-debug 0.11 Command Documentation

break

b[reak] file:line [if expr]
b[reak] class(.|#)method [if expr]
	set breakpoint to some position, (optionally) if expr == true

catch

cat[ch]		same as "info catch"
cat[ch] <exception-name> [on|off]
	Intercept <exception-name> when there would otherwise be no handler.
	With an "on" or "off", turn handling the exception on or off.
cat[ch] off	delete all catchpoints

condition

Condition breakpoint-number expression
Specify breakpoint number N to break only if COND is true.
N is an integer and COND is an expression to be evaluated whenever 
breakpoint N is reached. If the empty string is used, the condition is removed.

continue

c[ont[inue]][ nnn]	run until program ends, hits a breakpoint or reaches line nnn 

delete

del[ete][ nnn...]	delete some or all breakpoints

disable

Disable some things.

A disabled item is not forgotten, but has no effect until reenabled.
Use the "enable" command to have it take effect again.
-- 
List of disable subcommands:
--  
disable breakpoints -- Disable some breakpoints
disable display -- Disable some display expressions when program stops

disable breakpoints

Disable some breakpoints.
Arguments are breakpoint numbers with spaces in between.
A disabled breakpoint is not forgotten, but has no effect until reenabled.

disable display

Disable some display expressions when program stops.
Arguments are the code numbers of the expressions to stop displaying.
Do "info display" to see current list of code numbers.

display

disp[lay] <expression>	add expression into display expression list

display

disp[lay]		display expression list

down

down[count]	move to lower frame

edit

Edit specified file.

With no argument, edits file containing most recent line listed.
Editing targets can also be specified in this:
FILE:LINENUM, to edit at that line in that file,

enable

Enable some things.
This is used to cancel the effect of the "disable" command.
-- 
List of enable subcommands:
--  
enable breakpoints -- Enable specified breakpoints
enable display -- Enable some expressions to be displayed when program stops

enable breakpoints

Enable specified breakpoints.
Give breakpoint numbers (separated by spaces) as arguments.
This is used to cancel the effect of the "disable" command.

enable display

Enable some expressions to be displayed when program stops.
Arguments are the code numbers of the expressions to resume displaying.
Do "info display" to see current list of code numbers.

finish

fin[ish] [frame-number]	Execute until selected stack frame returns.

If no frame number is given, we run until the currently selected frame
returns.  The currently selected frame starts out the most-recent
frame or 0 if no frame positioning (e.g "up", "down" or "frame") has
been performed. If a frame number is given we run until that frame
returns.

frame

f[rame] [frame-number [thread thread-number]]
Move the current frame to the specified frame number, or the
0 if no frame-number has been given.

A negative number indicates position from the other end.  So
'frame -1' moves to the oldest frame, and 'frame 0' moves to
the newest frame.

Without an argument, the command prints the current stack
frame. Since the current position is redisplayed, it may trigger a
resyncronization if there is a front end also watching over
things. 

If a thread number is given then we set the context for evaluating
expressions to that frame of that thread. 

help

h[elp]		print this help
h[elp] command	print help on command

info

Generic command for showing things about the program being debugged.
-- 
List of info subcommands:
--  
info args -- Argument variables of current stack frame
info breakpoints -- Status of user-settable breakpoints
info catch -- Exceptions that can be caught in the current stack frame
info display -- Expressions to display when program stops
info file -- Info about a particular file read in
info files -- File names and timestamps of files read in
info global_variables -- Global variables
info instance_variables -- Instance variables of the current stack frame
info line -- Line number and file name of current position in source file
info locals -- Local variables of the current stack frame
info program -- Execution status of the program
info stack -- Backtrace of the stack
info thread -- List info about thread NUM
info threads -- information of currently-known threads
info variables -- Local and instance variables of the current stack frame

info args

Argument variables of current stack frame.

info breakpoints

Status of user-settable breakpoints.
Without argument, list info about all breakpoints.  With an
integer argument, list info on that breakpoint.

info catch

Exceptions that can be caught in the current stack frame.

info display

Expressions to display when program stops.

info file

Info about a particular file read in.

After the file name is supplied, you can list file attributes that
you wish to see.

Attributes include: "all", "basic", "breakpoint", "lines", "mtime", "path" 
and "sha1".

info files

File names and timestamps of files read in.

info global_variables

Global variables.

info instance_variables

Instance variables of the current stack frame.

info line

Line number and file name of current position in source file.

info locals

Local variables of the current stack frame.

info program

Execution status of the program.

info stack

Backtrace of the stack.

info thread

List info about thread NUM.

If no thread number is given, we list info for all threads. 'terse' and 'verbose' 
options are possible. If terse, just give summary thread name information. See 
"help info threads" for more detail about this summary information.

If 'verbose' appended to the end of the command, then the entire
stack trace is given for each thread.

info threads

information of currently-known threads.

This information includes whether the thread is current (+), if it is
suspended ($), or ignored (!).  The thread number and the top stack
item. If 'verbose' is given then the entire stack frame is shown.

info variables

Local and instance variables of the current stack frame.

interrupt

i[nterrupt]	interrupt the program

irb

irb [-d]	starts an Interactive Ruby (IRB) session.

If -d is added you can get access to debugger state via the global variable
$RDEBUG_state. 

irb is extended with methods "cont", "n" and "step" which 
run the corresponding debugger commands. In contrast to the real debugger
commands these commands don't allow command arguments.

jump

j[ump] line	jump to line number (absolute)
j[ump] -line	jump back to line (relative)
j[ump] +line	jump ahead to line (relative)

Change the next line of code to be executed.

kill

kill [SIGNAL]

Send [signal] to Process.pid
Equivalent of Process.kill(Process.pid)

list

l[ist]		list forward
l[ist] -	list backward
l[ist] =	list current line
l[ist] nn-mm	list given lines
* NOTE - to turn on autolist, use 'set autolist'

method

m[ethod] i[nstance] <obj>	show methods of object
m[ethod] iv <obj>		show instance variables of object
m[ethod] <class|module>		show instance methods of class or module

next

n[ext][+-]?[ nnn]	step over once or nnn times, 
		'+' forces to move to another line.
		'-' is the opposite of '+' and disables the force_stepping setting.

pp

pp expression	evaluate expression and pretty-print its value

ps

ps expression	evaluate expression, an array, sort, and columnize its value

putl

putl expression		evaluate expression, an array, and columnize its value

p|eval

e[val] expression	evaluate expression and print its value,
			alias for p.
* NOTE - to turn on autoeval, use 'set autoeval'

quit|exit

q[uit] [!|unconditionally]	exit from debugger. 
exit[!]	alias to quit

Normally we prompt before exiting. However if the parameter
"unconditionally" or is given or suffixed with !, we stop
without asking further questions.  

reload

r[eload]	forces source code reloading

restart

restart|R [args] 
Restart the program. This is is a re-exec - all debugger state
is lost. If command arguments are passed those are used.

save

save [FILE]
Saves current debugger state to FILE as a script file.
This includes breakpoints, catchpoints, display expressions and some settings.
If no filename is given, we will fabricate one.

Use the 'source' command in another debug session to restore them.

set

Modifies parts of the ruby-debug environment. Boolean values take
on, off, 1 or 0.
You can see these environment settings with the "show" command.

-- 
List of set subcommands:
--  
set annotate -- Set annotation level
set args -- Set argument list to give program being debugged when it is started
set autoeval -- Evaluate every unrecognized command
set autolist -- Execute 'list' command on every breakpoint
set autoirb -- Invoke IRB on every stop
set autoreload -- Reload source code when changed
set basename -- Report file basename only showing file names
set callstyle -- Set how you want call parameters displayed
set debuggertesting -- Used when testing the debugger
set forcestep -- Make sure 'next/step' commands always move to a new line
set fullpath -- Display full file names in frames
set history -- Generic command for setting command history parameters
set keep-frame-bindings -- Save frame binding on each call
set linetrace+ -- Set line execution tracing to show different lines
set linetrace -- Set line execution tracing
set listsize -- Set number of source lines to list by default
set trace -- Display stack trace when 'eval' raises exception
set width -- Number of characters the debugger thinks are in a line

set annotate

Set annotation level.
0 == normal;
2 == output annotated suitably for use by programs that control 
ruby-debug.

set args

Set argument list to give program being debugged when it is started.
Follow this command with any number of args, to be passed to the program.

set autoeval

Evaluate every unrecognized command.

set autoirb

Invoke IRB on every stop.

set autolist

Execute 'list' command on every breakpoint.

set autoreload

Reload source code when changed.

set basename

Report file basename only showing file names.

set callstyle

Set how you want call parameters displayed.

set debuggertesting

Used when testing the debugger.

set forcestep

Make sure 'next/step' commands always move to a new line.

set fullpath

Display full file names in frames.

set history

Generic command for setting command history parameters.
set history filename -- Set the filename in which to record the command history
set history save -- Set saving of the history record on exit
set history size -- Set the size of the command history

set keep-frame-bindings

Save frame binding on each call.

set linetrace

Set line execution tracing.

set linetrace+

Set line execution tracing to show different lines.

set listsize

Set number of source lines to list by default.

set trace

Display stack trace when 'eval' raises exception.

set width

Number of characters the debugger thinks are in a line.

show

Generic command for showing things about the debugger.

-- 
List of show subcommands:
--  
show annotate -- Show annotation level
show args -- Show argument list to give program being debugged when it is started
show autoeval -- Show if unrecognized command are evaluated
show autolist -- Show if 'list' commands is run on breakpoints
show autoirb -- Show if IRB is invoked on debugger stops
show autoreload -- Show if source code is reloaded when changed
show basename -- Show if basename used in reporting files
show callstyle -- Show paramater style used showing call frames
show commands -- Show the history of commands you typed
show forcestep -- Show if sure 'next/step' forces move to a new line
show fullpath -- Show if full file names are displayed in frames
show history -- Generic command for showing command history parameters
show keep-frame-bindings -- Save frame binding on each call
show linetrace -- Show line execution tracing
show linetrace+ -- Show if consecutive lines should be different are shown in tracing
show listsize -- Show number of source lines to list by default
show port -- Show server port
show post-mortem -- Show whether we go into post-mortem debugging on an uncaught exception
show trace -- Show if a stack trace is displayed when 'eval' raises exception
show version -- Show what version of the debugger this is
show width -- Show the number of characters the debugger thinks are in a line

show annotate

Show annotation level.
0 == normal; 2 == output annotated suitably for use by programs that control 
ruby-debug.

show args

Show argument list to give program being debugged when it is started.
Follow this command with any number of args, to be passed to the program.

show autoeval

Show if unrecognized command are evaluated.

show autoirb

Show if IRB is invoked on debugger stops.

show autolist

Show if 'list' commands is run on breakpoints.

show autoreload

Show if source code is reloaded when changed.

show basename

Show if basename used in reporting files.

show callstyle

Show paramater style used showing call frames.

show commands

Show the history of commands you typed.
You can supply a command number to start with.

show forcestep

Show if sure 'next/step' forces move to a new line.

show fullpath

Show if full file names are displayed in frames.

show history

Generic command for showing command history parameters.
show history filename -- Show the filename in which to record the command history
show history save -- Show saving of the history record on exit
show history size -- Show the size of the command history

show keep-frame-bindings

Save frame binding on each call.

show linetrace

Show line execution tracing.

show linetrace+

Show if consecutive lines should be different are shown in tracing.

show listsize

Show number of source lines to list by default.

show port

Show server port.

show post-mortem

Show whether we go into post-mortem debugging on an uncaught exception.

show trace

Show if a stack trace is displayed when 'eval' raises exception.

show version

Show what version of the debugger this is.

show width

Show the number of characters the debugger thinks are in a line.

source

source FILE	executes a file containing debugger commands

step

s[tep][+-]?[ nnn]	step (into methods) once or nnn times
		'+' forces to move to another line.
		'-' is the opposite of '+' and disables the force_stepping setting.

thread

th[read] resume <nnn>		resume thread nnn

thread

th[read] stop <nnn>		stop thread nnn

thread

th[read] [sw[itch]] <nnn>	switch thread context to nnn

thread

th[read] l[ist]			list all threads

thread

th[read] [cur[rent]]		show current thread

tmate

tm[ate] n	opens a current file in TextMate. 
		It uses n-th frame if arg (n) is specifed.

trace

tr[ace] (on|off)	set trace mode of current thread
tr[ace] (on|off) all	set trace mode of all threads
tr[ace] var(iable) VARNAME [stop|nostop]	set trace variable on VARNAME

undisplay

undisp[lay][ nnn]
Cancel some expressions to be displayed when program stops.
Arguments are the code numbers of the expressions to stop displaying.
No argument means cancel all automatic-display expressions.
"delete display" has the same effect as this command.
Do "info display" to see current list of code numbers.

up

up[count]	move to higher frame

var

v[ar] l[ocal]			show local variables

var

v[ar] cl[ass] 			show class variables of self

var

v[ar] c[onst] <object>		show constants of object

var

v[ar] i[nstance] <object>	show instance variables of object

var

v[ar] g[lobal]			show global variables

where|backtrace

bt|backtrace		alias for where - display stack frames

Print the entire stack frame. Each frame is numbered, the most recent
frame is 0. frame number can be referred to in the "frame" command;
"up" and "down" add or subtract respectively to frame numbers shown.
The position of the current frame is marked with -->.  

Appendix: Debugger.settings

Use Debugger.settings[] and Debugger.settings[]= methods to query and set
debugger settings. These settings are available:

- :autolist - automatically calls 'list' command on breakpoint
- :autoeval - evaluates input in the current binding if it's not recognized as a debugger command
- :autoirb - automatically calls 'irb' command on breakpoint
- :stack_trace_on_error - shows full stack trace if eval command results with an exception
- :frame_full_path - displays full paths when showing frame stack
- :frame_class_names - displays method's class name when showing frame stack
- :reload_source_on_change - makes 'list' command to always display up-to-date source code
- :force_stepping - stepping command asways move to the new line

ruby-debug-man.rb

#!/usr/bin/env ruby
# Print Markdown formatted ruby-debug command documentation to STDOUT
require "ruby-debug"

def stringify(arg)
  case arg
  when Array
    arg.join "|"
  else
    arg.to_s
  end
end

def strip_lines(str)
  str.lines.map{|str| str.gsub(/^ +/, "")}.join.gsub(/\A\n+/, "").gsub(/\n+\z/, "")
end

def tab(str)
  str.lines.map{|str| "    #{str}"}.join
end

helps = Debugger.constants.
  map{|name| Debugger.const_get(name) }.
  select{|const| const.is_a?(Class) && const < Debugger::Command }.
  inject([]){|result, klass|
    if klass.constants.include?(:Subcommands)
      klass.const_get(:Subcommands).map do |subcommand|
        result << {
          help_command: "#{stringify klass.help_command} #{subcommand.name}",
          help: strip_lines(klass.help([nil, subcommand.name]))
        }
      end
    end
    
    result << {
      help_command: "#{stringify klass.help_command}",
      help: strip_lines(klass.help([nil]))
    }
    
    result
  }.sort_by{|h| h[:help_command]}

LINE_WIDTH = 85

puts
puts "ruby-debug #{Debugger::VERSION} Command Documentation"
puts "=" * LINE_WIDTH
puts

helps.each do |h|
  command = h[:help_command]
  help = h[:help]
  
  puts
  puts command
  puts "-" * LINE_WIDTH
  puts
  puts tab help
  puts
end

document_for_settings = <<EOS
Use Debugger.settings[] and Debugger.settings[]= methods to query and set
debugger settings. These settings are available:

- :autolist - automatically calls 'list' command on breakpoint
- :autoeval - evaluates input in the current binding if it's not recognized as a debugger command
- :autoirb - automatically calls 'irb' command on breakpoint
- :stack_trace_on_error - shows full stack trace if eval command results with an exception
- :frame_full_path - displays full paths when showing frame stack
- :frame_class_names - displays method's class name when showing frame stack
- :reload_source_on_change - makes 'list' command to always display up-to-date source code
- :force_stepping - stepping command asways move to the new line
EOS

puts
puts "Appendix: Debugger.settings"
puts "-" * LINE_WIDTH
puts
puts tab document_for_settings
puts