Permalink
Browse files

* lib/debug.rb: Added toplevel documentation. Based on patch by Oscar

  Del Ben.  [Bug #6743], fixes #146 on github.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36426 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent 7a514fc commit 9844bc02a0004d6700b9daf88d089e0d9891fed6 @drbrain drbrain committed Jul 18, 2012
Showing with 169 additions and 4 deletions.
  1. +5 −0 ChangeLog
  2. +164 −4 lib/debug.rb
View
@@ -1,3 +1,8 @@
+Wed Jul 18 10:00:54 2012 Eric Hodel <drbrain@segment7.net>
+
+ * lib/debug.rb: Added toplevel documentation. Based on patch by Oscar
+ Del Ben. [Bug #6743], fixes #146 on github.
+
Wed Jul 18 09:33:59 2012 NAKAMURA Usaku <usa@ruby-lang.org>
* test/win32ole/test_win32ole_event.rb (TestWIN32OLE_EVENT): use
View
@@ -12,18 +12,178 @@
require 'tracer'
require 'pp'
-class Tracer
+class Tracer # :nodoc:
def Tracer.trace_func(*vars)
Single.trace_func(*vars)
end
end
-SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__
+SCRIPT_LINES__ = {} unless defined? SCRIPT_LINES__ # :nodoc:
+
+##
+# This library provides debugging functionality to Ruby.
+#
+# To add a debugger to your code, start by requiring +debug+ in your
+# program:
+#
+# def say(word)
+# require 'debug'
+# puts word
+# end
+#
+# This will cause Ruby to interrupt execution and show a prompt when the +say+
+# method is run.
+#
+# Once you're inside the prompt, you can start debugging your program.
+#
+# (rdb:1) p word
+# "hello"
+#
+# == Getting help
+#
+# You can get help at any time by pressing +h+.
+#
+# (rdb:1) h
+# Debugger help v.-0.002b
+# Commands
+# b[reak] [file:|class:]<line|method>
+# b[reak] [class.]<line|method>
+# set breakpoint to some position
+# wat[ch] <expression> set watchpoint to some expression
+# cat[ch] (<exception>|off) set catchpoint to an exception
+# b[reak] list breakpoints
+# cat[ch] show catchpoint
+# del[ete][ nnn] delete some or all breakpoints
+# disp[lay] <expression> add expression into display expression list
+# undisp[lay][ nnn] delete one particular or all display expressions
+# c[ont] run until program ends or hit breakpoint
+# s[tep][ nnn] step (into methods) one line or till line nnn
+# n[ext][ nnn] go over one line or till line nnn
+# w[here] display frames
+# f[rame] alias for where
+# l[ist][ (-|nn-mm)] list program, - lists backwards
+# nn-mm lists given lines
+# up[ nn] move to higher frame
+# down[ nn] move to lower frame
+# fin[ish] return to outer frame
+# tr[ace] (on|off) set trace mode of current thread
+# tr[ace] (on|off) all set trace mode of all threads
+# q[uit] exit from debugger
+# v[ar] g[lobal] show global variables
+# v[ar] l[ocal] show local variables
+# v[ar] i[nstance] <object> show instance variables of object
+# v[ar] c[onst] <object> show constants of object
+# m[ethod] i[nstance] <obj> show methods of object
+# m[ethod] <class|module> show instance methods of class or module
+# th[read] l[ist] list all threads
+# th[read] c[ur[rent]] show current thread
+# th[read] [sw[itch]] <nnn> switch thread context to nnn
+# th[read] stop <nnn> stop thread nnn
+# th[read] resume <nnn> resume thread nnn
+# p expression evaluate expression and print its value
+# h[elp] print this help
+# <everything else> evaluate
+#
+# == Usage
+#
+# The following is a list of common functionalities that the debugger
+# provides.
+#
+# === Navigating through your code
+#
+# In general, a debugger is used to find bugs in your program, which
+# often means pausing execution and inspecting variables at some point
+# in time.
+#
+# Let's look at an example:
+#
+# def my_method(foo)
+# require 'debug'
+# foo = get_foo if foo.nil?
+# raise if foo.nil?
+# end
+#
+# When you run this program, the debugger will kick in just before the
+# +foo+ assignment.
+#
+# (rdb:1) p foo
+# nil
+#
+# In this example, it'd be interesting to move to the next line and
+# inspect the value of +foo+ again. You can do that by pressing +n+:
+#
+# (rdb:1) n # goes to next line
+# (rdb:1) p foo
+# nil
+#
+# You now know that the original value of +foo+ was nil, and that it
+# still was nil after calling +get_foo+.
+#
+# Other useful commands for navigating through your code are:
+#
+# +c+::
+# Runs the program until it either exists or encounters another breakpoint.
+# You usually press +c+ when you are finished debugging your program and
+# want to resume its execution.
+# +s+::
+# Steps into method definition. In the previous example, +s+ would take you
+# inside the method definition of +get_foo+.
+# +r+::
+# Restart the program.
+# +q+::
+# Quit the program.
+#
+# === Inspecting variables
+#
+# You can use the debugger to easily inspect both local and global variables.
+# We've seen how to inspect local variables before:
+#
+# (rdb:1) p my_arg
+# 42
+#
+# You can also pretty print the result of variables or expressions:
+#
+# (rdb:1) pp %w{a very long long array containing many words}
+# ["a",
+# "very",
+# "long",
+# ...
+# ]
+#
+# You can list all local variables with +v l+:
+#
+# (rdb:1) v l
+# foo => "hello"
+#
+# Similarly, you can show all global variables with +v g+:
+#
+# (rdb:1) v g
+# all global variables
+#
+# Finally, you can omit +p+ if you simply want to evaluate a variable or
+# expression
+#
+# (rdb:1) 5**2
+# 25
+#
+# === Going beyond basics
+#
+# Ruby Debug provides more advanced functionalities like switching
+# between threads, setting breakpoints and watch expressions, and more.
+# The full list of commands is available at any time by pressing +h+.
+#
+# == Staying out of trouble
+#
+# Make sure you remove every instance of +require 'debug'+ before
+# shipping your code. Failing to do so may result in your program
+# hanging unpredictably.
+#
+# Debug is not available in safe mode.
class DEBUGGER__
- MUTEX = Mutex.new
+ MUTEX = Mutex.new # :nodoc:
- class Context
+ class Context # :nodoc:
DEBUG_LAST_CMD = []
begin

0 comments on commit 9844bc0

Please sign in to comment.