|
12 | 12 | require 'tracer' |
13 | 13 | require 'pp' |
14 | 14 |
|
15 | | -class Tracer |
| 15 | +class Tracer # :nodoc: |
16 | 16 | def Tracer.trace_func(*vars) |
17 | 17 | Single.trace_func(*vars) |
18 | 18 | end |
19 | 19 | end |
20 | 20 |
|
21 | | -SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__ |
| 21 | +SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__ # :nodoc: |
| 22 | + |
| 23 | +## |
| 24 | +# This library provides debugging functionality to Ruby. |
| 25 | +# |
| 26 | +# To add a debugger to your code, start by requiring +debug+ in your |
| 27 | +# program: |
| 28 | +# |
| 29 | +# def say(word) |
| 30 | +# require 'debug' |
| 31 | +# puts word |
| 32 | +# end |
| 33 | +# |
| 34 | +# This will cause Ruby to interrupt execution and show a prompt when the +say+ |
| 35 | +# method is run. |
| 36 | +# |
| 37 | +# Once you're inside the prompt, you can start debugging your program. |
| 38 | +# |
| 39 | +# (rdb:1) p word |
| 40 | +# "hello" |
| 41 | +# |
| 42 | +# == Getting help |
| 43 | +# |
| 44 | +# You can get help at any time by pressing +h+. |
| 45 | +# |
| 46 | +# (rdb:1) h |
| 47 | +# Debugger help v.-0.002b |
| 48 | +# Commands |
| 49 | +# b[reak] [file:|class:]<line|method> |
| 50 | +# b[reak] [class.]<line|method> |
| 51 | +# set breakpoint to some position |
| 52 | +# wat[ch] <expression> set watchpoint to some expression |
| 53 | +# cat[ch] (<exception>|off) set catchpoint to an exception |
| 54 | +# b[reak] list breakpoints |
| 55 | +# cat[ch] show catchpoint |
| 56 | +# del[ete][ nnn] delete some or all breakpoints |
| 57 | +# disp[lay] <expression> add expression into display expression list |
| 58 | +# undisp[lay][ nnn] delete one particular or all display expressions |
| 59 | +# c[ont] run until program ends or hit breakpoint |
| 60 | +# s[tep][ nnn] step (into methods) one line or till line nnn |
| 61 | +# n[ext][ nnn] go over one line or till line nnn |
| 62 | +# w[here] display frames |
| 63 | +# f[rame] alias for where |
| 64 | +# l[ist][ (-|nn-mm)] list program, - lists backwards |
| 65 | +# nn-mm lists given lines |
| 66 | +# up[ nn] move to higher frame |
| 67 | +# down[ nn] move to lower frame |
| 68 | +# fin[ish] return to outer frame |
| 69 | +# tr[ace] (on|off) set trace mode of current thread |
| 70 | +# tr[ace] (on|off) all set trace mode of all threads |
| 71 | +# q[uit] exit from debugger |
| 72 | +# v[ar] g[lobal] show global variables |
| 73 | +# v[ar] l[ocal] show local variables |
| 74 | +# v[ar] i[nstance] <object> show instance variables of object |
| 75 | +# v[ar] c[onst] <object> show constants of object |
| 76 | +# m[ethod] i[nstance] <obj> show methods of object |
| 77 | +# m[ethod] <class|module> show instance methods of class or module |
| 78 | +# th[read] l[ist] list all threads |
| 79 | +# th[read] c[ur[rent]] show current thread |
| 80 | +# th[read] [sw[itch]] <nnn> switch thread context to nnn |
| 81 | +# th[read] stop <nnn> stop thread nnn |
| 82 | +# th[read] resume <nnn> resume thread nnn |
| 83 | +# p expression evaluate expression and print its value |
| 84 | +# h[elp] print this help |
| 85 | +# <everything else> evaluate |
| 86 | +# |
| 87 | +# == Usage |
| 88 | +# |
| 89 | +# The following is a list of common functionalities that the debugger |
| 90 | +# provides. |
| 91 | +# |
| 92 | +# === Navigating through your code |
| 93 | +# |
| 94 | +# In general, a debugger is used to find bugs in your program, which |
| 95 | +# often means pausing execution and inspecting variables at some point |
| 96 | +# in time. |
| 97 | +# |
| 98 | +# Let's look at an example: |
| 99 | +# |
| 100 | +# def my_method(foo) |
| 101 | +# require 'debug' |
| 102 | +# foo = get_foo if foo.nil? |
| 103 | +# raise if foo.nil? |
| 104 | +# end |
| 105 | +# |
| 106 | +# When you run this program, the debugger will kick in just before the |
| 107 | +# +foo+ assignment. |
| 108 | +# |
| 109 | +# (rdb:1) p foo |
| 110 | +# nil |
| 111 | +# |
| 112 | +# In this example, it'd be interesting to move to the next line and |
| 113 | +# inspect the value of +foo+ again. You can do that by pressing +n+: |
| 114 | +# |
| 115 | +# (rdb:1) n # goes to next line |
| 116 | +# (rdb:1) p foo |
| 117 | +# nil |
| 118 | +# |
| 119 | +# You now know that the original value of +foo+ was nil, and that it |
| 120 | +# still was nil after calling +get_foo+. |
| 121 | +# |
| 122 | +# Other useful commands for navigating through your code are: |
| 123 | +# |
| 124 | +# +c+:: |
| 125 | +# Runs the program until it either exists or encounters another breakpoint. |
| 126 | +# You usually press +c+ when you are finished debugging your program and |
| 127 | +# want to resume its execution. |
| 128 | +# +s+:: |
| 129 | +# Steps into method definition. In the previous example, +s+ would take you |
| 130 | +# inside the method definition of +get_foo+. |
| 131 | +# +r+:: |
| 132 | +# Restart the program. |
| 133 | +# +q+:: |
| 134 | +# Quit the program. |
| 135 | +# |
| 136 | +# === Inspecting variables |
| 137 | +# |
| 138 | +# You can use the debugger to easily inspect both local and global variables. |
| 139 | +# We've seen how to inspect local variables before: |
| 140 | +# |
| 141 | +# (rdb:1) p my_arg |
| 142 | +# 42 |
| 143 | +# |
| 144 | +# You can also pretty print the result of variables or expressions: |
| 145 | +# |
| 146 | +# (rdb:1) pp %w{a very long long array containing many words} |
| 147 | +# ["a", |
| 148 | +# "very", |
| 149 | +# "long", |
| 150 | +# ... |
| 151 | +# ] |
| 152 | +# |
| 153 | +# You can list all local variables with +v l+: |
| 154 | +# |
| 155 | +# (rdb:1) v l |
| 156 | +# foo => "hello" |
| 157 | +# |
| 158 | +# Similarly, you can show all global variables with +v g+: |
| 159 | +# |
| 160 | +# (rdb:1) v g |
| 161 | +# all global variables |
| 162 | +# |
| 163 | +# Finally, you can omit +p+ if you simply want to evaluate a variable or |
| 164 | +# expression |
| 165 | +# |
| 166 | +# (rdb:1) 5**2 |
| 167 | +# 25 |
| 168 | +# |
| 169 | +# === Going beyond basics |
| 170 | +# |
| 171 | +# Ruby Debug provides more advanced functionalities like switching |
| 172 | +# between threads, setting breakpoints and watch expressions, and more. |
| 173 | +# The full list of commands is available at any time by pressing +h+. |
| 174 | +# |
| 175 | +# == Staying out of trouble |
| 176 | +# |
| 177 | +# Make sure you remove every instance of +require 'debug'+ before |
| 178 | +# shipping your code. Failing to do so may result in your program |
| 179 | +# hanging unpredictably. |
| 180 | +# |
| 181 | +# Debug is not available in safe mode. |
22 | 182 |
|
23 | 183 | class DEBUGGER__ |
24 | | - MUTEX = Mutex.new |
| 184 | + MUTEX = Mutex.new # :nodoc: |
25 | 185 |
|
26 | | - class Context |
| 186 | + class Context # :nodoc: |
27 | 187 | DEBUG_LAST_CMD = [] |
28 | 188 |
|
29 | 189 | begin |
|
0 commit comments