byebug 2.2.2 → 2.3.0

data/old_doc/byebug.texi

@@ -1,3259 +0,0 @@
-\input texinfo
-@setfilename byebug.info
-
-@set BYEBUG_VERSION 1.8.2
-@set UPDATED Aug-2013
-
-@macro Example {}
-@iftex
-@cartouche
-@end iftex
-@smallexample
-@end macro
-
-@macro EndExample {}
-@iftex
-@end cartouche
-@end iftex
-@end smallexample
-@end macro
-
-@c How to show optional variables.
-@macro ovar{varname}
-@r{[}@var{\varname\}@r{]}
-@end macro
-
-@settitle Byebug
-@setchapternewpage odd
-@c %**end of header
-
-@finalout
-
-@c This is a dir.info fragment to support semi-automated addition of
-@c manuals to an info tree.
-@dircategory Programming & development tools.
-@direntry
-* byebug: (byebug).    Ruby Byebug
-@end direntry
-
-@titlepage
-@title Debugging with @code{byebug}
-@sp 1
-@subtitle @value{BYEBUG_VERSION} Edition
-@subtitle @value{UPDATED-MONTH}
-@author David Rodríguez, Rocky Bernstein, Kent Sibilev, and Mark Moseley
-@page
-@end titlepage
-@page
-
-@ifnottex
-@node Top, Summary, (dir), (dir)
-@top Debugging with byebug
-
-This file describes Byebug, a Ruby 2.0 debugger, version @value{BYEBUG_VERSION}
-
-Last updated: @value{UPDATED}
-@c Copyleft (U+0254) 2013
-
-@menu
-* Summary::                   Overview of Byebug with sample sessions
-* Invocation::                Getting in and out
-* Byebug Command Reference::  Byebug's commands
-* Post-Mortem Debugging::     Debugging on an uncaught exception
-* Byebug Module and Class::   Byebug's module and class
-
-Appendix
-* Contributing::
-
-Indexes
-* Class Module Method Index:: An item for each Class, Module and Method.
-* Command Index::             An item for each command name.
-* General Index::             An item for each concept.
-@end menu
-
-@end ifnottex
-
-@contents
-
-@node Summary
-@chapter Summary of @code{byebug}
-
-The purpose of a debugger such as @code{byebug} is to allow you to see what is
-going on ``inside'' a Ruby program while it executes. @code{byebug} can do four
-main kinds of things (plus other things in support of these) to help you catch
- bugs in the act:
-
-@itemize @bullet
-@item
-Start your script, specifying anything that might affect its behavior.
-
-@item
-Make your script stop on specified conditions.
-
-@item
-Examine what has happened, when your script has stopped.
-
-@item
-Change things in your script, so you can experiment with correcting the effects
-of one bug and go on to learn about another.
-@end itemize
-
-Although you can use @code{byebug} to invoke your Ruby programs via a debugger
-at the outset, there are other ways to use and enter the debugger.
-
-@menu
-* First Sample Session::      @code{display}, @code{print}, @code{quit}
-* Second Sample Session::     @code{where}, @code{frame}, @code{restart}, @code{autoeval}, @code{break}, @code{ps}
-* Unit Testing Session::      Using byebug in unit testing
-* Byebug.start with a block:: Using the Byebug.start with a block
-* Debugging Oddities::        How debugging Ruby may be different...
-@end menu
-
-@node First Sample Session
-@section First Sample Session
-
-You can use this manual at your leisure to read all about @code{byebug}.
-However, a handful of commands are enough to get started using byebug. The
-following sections illustrates these commands.
-
-@iftex
-In this sample session, we emphasize user input like this: @b{input}, to make it
-easier to pick out from the surrounding output.
-@end iftex
-
-Below is Ruby code to compute a triangle number of a given length.
-@footnote{There are of course shorter ways to define @code{triangle} such as:
-@smallexample
-  def triangle(n) (n * (n+1)) / 2 end
-@end smallexample
-The code we use in this example and the next is more for pedagogical purposes
-than how to write short Ruby code.}
-
-@smallexample
-$ @b{byebug triangle.rb}
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-   1   #!/usr/bin/env ruby
-   2   # Compute the n'th triangle number - the hard way
-   3   # triangle(n) == (n * (n+1)) / 2
-=> 4   def triangle(n)
-   5     tri = 0
-   6     0.upto(n) do |i|
-   7       tri += i
-   8     end
-   9     tri
-   10  end
-(byebug)
-@end smallexample
-
-@noindent
-
-There are lots of command options, but we don't need them for now. See
-@ref{byebug command-line options} for a full list of command options.
-
-We are currently stopped before the first executable line of the program; this
-is line 4 of @code{triangle.rb}. If you are used to less dynamic languages and
-have used debuggers for more statically compiled languages like C, C++, or Java,
-it may seem odd to be stopped before a function definition but in Ruby line 4 is
-executed, the name @code{triangle} (probably) does not exist so issuing a method
-call of @code{triangle} will raise a ``method not found'' error.
-
-@code{byebug}'s prompt is @code{(byebug)}. If the program has died and you are
-in post-mortem debugging @code{(byebug:post-mortem)} is used instead. If the
-program has terminated normally, the string this position will be
-@code{(byebug:ctrl)}. The commands which are available change depending on the
-program's state.
-
-Byebug automatically lists 10 lines of code centered around the current line
-everytime it is stopped. The current line here is line 4 and is marked with
-@code{=>}, so the range byebug would like to show is [-1..8]. However since
-there aren't 5 lines before the current line, the range is moved ``up'' so we
-can actually display 10 lines of code.
-
-Now let us step through the program.
-
-@smallexample
-(byebug) @b{step}
-[4, 13] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-   4   def triangle(n)
-   5     tri = 0
-   6     0.upto(n) do |i|
-   7       tri += i
-   8     end
-   9     tri
-   10  end
-   11
-=> 12  t = triangle(3)
-   13  puts t
-(byebug) @b{@key{<RET>}}
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-   1  #!/usr/bin/env ruby
-   2  # Compute the n'th triangle number - the hard way
-   3  # triangle(n) == (n * (n+1)) / 2
-   4  def triangle(n)
-=> 5    tri = 0
-   6    0.upto(n) do |i|
-   7      tri += i
-   8    end
-   9    tri
-   10  end
-(byebug) @b{p tri}
-nil
-(byebug) @b{step}
-[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-   1   #!/usr/bin/env ruby
-   2   # Compute the n'th triangle number - the hard way
-   3   # triangle(n) == (n * (n+1)) / 2
-   4   def triangle(n)
-   5     tri = 0
-=> 6     0.upto(n) do |i|
-   7       tri += i
-   8     end
-   9     tri
-   10  end
-(byebug) @b{p tri}
-0
-@end smallexample
-
-The first @kbd{step} command (@pxref{Step}) runs the script one executable unit.
-The second command we entered was just hitting the return key; @code{byebug}
-remembers the last command you entered was @code{step}, so it runs that last
-command again.
-
-One way to print the values of variables uses @code{p} (of course, there are
-lots of other ways). When we look at the value of @code{tri} the first time, we
-see it is @code{nil}. Again we are stopped @emph{before} the assignment on line
-5, and this variable hasn't been set previously. However after issuing another
-@code{step} command we see that the value is 0 as expected. If every time we
-stop we want to see the value of @code{tri} to see how things are going, there
-is a better way by setting a display expression (@pxref{DisplayCommands}).
-
-@smallexample
-(byebug:1) @b{display tri}
-1: tri = 0
-@end smallexample
-
-Now let us run the program until we return from the function. We'll want to see
-which lines get run.
-
-@smallexample
-(byebug) @b{display i}
-2: i =
-(byebug) @b{set linetrace on}
-line tracing is on.
-(byebug) @b{finish}
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:7 tri += i
-1: tri = 0
-2: i = 0
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:7 tri += i
-1: tri = 0
-2: i = 1
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:7 tri += i
-1: tri = 1
-2: i = 2
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:7 tri += i
-1: tri = 3
-2: i = 3
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:9 tri
-1: tri = 6
-2: i =
-Tracing: /home/davidr/Proyectos/byebug/old_doc/triangle.rb:13 puts t
-1: tri =
-2: i =
-[4, 13] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
-   4  def triangle(n)
-   5    tri = 0
-   6    0.upto(n) do |i|
-   7      tri += i
-   8    end
-   9    tri
-   10  end
-   11  
-   12  t = triangle(3)
-=> 13  puts t
-1: tri =
-2: i =
-(byebug) @b{quit}
-Really quit? (y/n) @b{y}
-@end smallexample
-
-So far, so good. As you can see from the above to get out of @code{byebug}, one
-can issue a @code{quit} command (@code{q} and @code{exit} are just as good). If
-you want to quit without being prompted, suffix the command with an exclamation
-mark, e.g. @code{q!}.
-
-@node Second Sample Session
-@section Second Sample Session 2: Delving Deeper
-
-In this section we'll introduce breakpoints, the call stack and restarting. So
-far we've been doing pretty good in that we've not encountered a bug to fix.
-Let's try another simple example. Okay here's the program.
-
-Below we will debug a simple Ruby program to solve the classic Towers of Hanoi
-puzzle. It is augmented by the bane of programming: some command-parameter
-processing with error checking.
-
-@smallexample
-$ @b{byebug hanoi.rb}
-hanoi.rb:3 def hanoi(n,a,b,c)
-(byebug:1) @b{list 1,100}
-[1, 100] in ./hanoi.rb
-   1  #!/usr/bin/ruby
-   2
-=> 3  def hanoi(n,a,b,c)
-   4    if n-1 > 0
-   5      hanoi(n-1, a, c, b)
-   6    end
-   7    puts "Move disk %s to %s" % [a, b]
-   8    if n-1 > 0
-   9      hanoi(n-1, c, b, a)
-   10   end
-   11 end
-   12
-   13 i_args=ARGV.length
-   14 if i_args > 1
-   15   puts "*** Need number of disks or no parameter"
-   16   exit 1
-   17 end
-   18
-   19 n=3
-   20
-   21 if i_args > 0
-   22   begin
-   23     n = ARGV[0].to_i
-   24   rescue ValueError, msg
-   25     print "** Expecting an integer, got: %s" % ARGV[0].to_s
-   26     exit 2
-   27   end
-   28 end
-   29
-   30 if n < 1 or n > 100
-   31   puts "*** number of disks should be between 1 and 100"
-   32   exit 2
-   33 end
-   34
-   35 hanoi(n, :a, :b, :c)
-(byebug:1)
-@end smallexample
-
-Recall in the first section I said that before the @code{def} is run
-the method it names is undefined. Let's check that out. First let's
-see what private methods we can call before running @code{def hanoi}
-
-@smallexample
-(byebug:1) @b{set autoeval on}
-autoeval is on.
-(byebug:1) @b{private_methods}
-[:require_relative, :Digest, :default_src_encoding, :debug_program, ...
-@end smallexample
-
-The @code{set autoeval} (@pxref{Autoeval}) command causes any commands
-that are not normally understood to be byebug commands to get
-evaluated as though they were Ruby commands. I use this a lot, so I
-set this by putting it the command file @code{.byebugrc},
-@pxref{Command Files}, that gets read when @code{byebug} starts.
-
-As showing the list output of @code{private_methods}, I find this kind
-of list unwieldy. What you are supposed to notice here is that
-method @code{hanoi} is not in this list. When you ask
-@code{byebug} for a list of method names via @code{method
-instance}, it doesn't show output in this way; @code{byebug} can
-sort and put into columns lists like this using the print command, @code{ps}.
-
-
-@smallexample
-(byebug:1) @b{ps private_methods}
-Array         debug_program         p                           spawn
-Complex       default_src_encoding  pp                          sprintf
-Digest        eval                  print                       srand
-Float         exec                  printf                      syscall
-Integer       exit                  proc                        system
-Pathname      exit!                 process_options             test
-Rational      fail                  putc                        throw
-String        fork                  puts                        trace_var
-__callee__    format                raise                       trap
-__method__    gem                   rand                        untrace_var
-`             gets                  readline                    warn
-abort         global_variables      readlines                   whence_file
-at_exit       initialize            remove_instance_variable    y
-autoload      initialize_copy       require
-autoload?     iterator?             require_relative
-binding       lambda                select
-block_given?  load                  set_trace_func
-caller        local_variables       singleton_method_added
-catch         loop                  singleton_method_removed
-dbg_print     method_missing        singleton_method_undefined
-dbg_puts      open                  sleep
-@end smallexample
-
-Now let's see what happens after stepping:
-
-@smallexample
-(byebug:1) @b{private_methods.member?(:hanoi)}
-false
-(byebug:1) @b{step}
-hanoi.rb:13
-i_args=ARGV.length
-(byebug:1) @b{private_methods.member?(:hanoi)}
-true
-(byebug:1)
-@end smallexample
-
-Okay, now where were we?
-
-@smallexample
-(byebug:1) @b{list}
-[8, 17] in ./hanoi.rb
-   8      if n-1 > 0
-   9         hanoi(n-1, c, b, a)
-   10      end
-   11  end
-   12
-=> 13  i_args=ARGV.length
-   14  if i_args > 1
-   15      puts "*** Need number of disks or no parameter"
-   16      exit 1
-   17  end
-(byebug:1) @b{ARGV}
-[]
-@end smallexample
-
-Ooops. We forgot to specify any parameters to this program. Let's try
-again. We can use the @code{restart} command here.
-
-@smallexample
-(byebug:1) @b{restart 3}
-Re exec'ing:
-        /usr/bin/byebug hanoi.rb 3
-hanoi.rb:3
-def hanoi(n,a,b,c)
-(byebug:1) @b{break 4}
-Breakpoint 1 file hanoi.rb, line 4
-(byebug:1) @b{continue}
-Breakpoint 1 at hanoi.rb:4
-./hanoi.rb:4 if n-1 > 0
-(byebug:1) @b{display n}
-1: n = 3
-(byebug:1) @b{display a}
-2: a = a
-(byebug:1) @b{undisplay 2}
-(byebug:1) @b{display a.inspect}
-3: a.inspect = :a
-(byebug:1) @b{display b.inspect}
-4: b.inspect = :b
-(byebug:1) @b{continue}
-Breakpoint 1 at hanoi.rb:4
-1: n = 2
-3: a.inspect = :a
-4: b.inspect = :c
-./hanoi.rb:4
-if n-1 > 0
-(byebug:1) @b{c}
-Breakpoint 1 at hanoi.rb:4
-1: n = 1
-3: a.inspect = :a
-4: b.inspect = :b
-./hanoi.rb:4
-if n-1 > 0
-(byebug:1) @b{where}
---> #0 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at hanoi.rb:4
-    #1 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at hanoi.rb:5
-    #2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at hanoi.rb:5
-    #3 at hanoi.rb:35
-(byebug:1)
-@end smallexample
-
-In the above we added a new command, @code{break} (@pxref{Breakpoints}) which
-indicates to go into byebug just before that line of code is run. And
-@code{continue} resumes execution.  Notice the difference between 
-@code{display a} and @code{display a.inspect}. An implied string conversion is
-performed on the expression after it is evaluated. To remove a display
-expression @code{undisplay} is used. If we give a display number, just that
-display expression is removed.
-
-Above we also used a new command @code{where} (@pxref{Backtrace} to show the
-call stack. In the above situation, starting from the bottom line we see we
-called the hanoi from line 35 of the file @code{hanoi.rb} and the hanoi method
-called itself two more times at line 5.
-
-In the call stack we show the file line position in the same format we use when
-we stop at a line. Also we see the names of the parameters and the types that
-those parameters @emph{currently} have. It's possible that when the program was
-called the parameter had a different type, since the types of variables can
-change dynamically. You can alter the style of what to show in the trace
-(@pxref{Callstyle}).
-
-Let's explore a little more. Now where were we?
-@smallexample
-(byebug:1) @b{list}
-   1  #!/usr/bin/ruby
-   2
-   3  def hanoi(n,a,b,c)
-=> 4      if n-1 > 0
-   5         hanoi(n-1, a, c, b)
-   6      end
-   7      puts "Move disk %s to %s" % [a, b]
-   8      if n-1 > 0
-(byebug:1) @b{undisplay}
-Clear all expressions? (y/n) @b{y}
-(byebug:1) @b{i_args}
-NameError Exception: undefined local variable or method `i_args' for main:Object
-(byebug:1) @b{frame -1}
-#3 at hanoi.rb:35
-(byebug:1) @b{i_args}
-1
-(byebug:1) @b{p n}
-3
-(byebug:1) @b{down 2}
-#2 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at hanoi.rb:5
-(byebug:1) @b{p n}
-2
-@end smallexample
-
-Notice in the above to get the value of variable @code{n} I had to use a print
-command like @code{p n}; If I entered just @code{n}, that would be taken to mean
-byebug command ``next''. In the current scope, variable @code{i_args} is not
-defined. However I can change to the top-most frame by using the @code{frame}
-command. Just as with arrays, -1 means the last one. Alternatively using frame
-number 3 would have been the same thing; so would issuing @code{up 3}.
-
-Note that in the outside frame 3, the value of @code{i_args} can be shown. Also
-note that the value of variable @code{n} is different.
-
-@node Unit Testing Session
-@section Using byebug in unit testing (@code{byebug}, @code{Byebug.start})
-
-In the previous sessions we've been calling byebug right at the outset. I
-confess that this mode of operation is usually not how I use byebug.
-
-There are a number of situations where calling byebug at the outset is
-impractical for a couple of reasons.
-
-@enumerate
-@item
-byebug just doesn't work when run at the outset.  By necessity any debugging
-changes the behavior or the program in slight and subtle ways, and sometimes
-this can hinder finding bugs.
-@item
-There's a lot of code that needs to be run before the part you want to inspect.
-Running this code takes time and you don't want the overhead of byebug.
-@end enumerate
-
-In this section we'll show how to enter the code in the middle of your program,
-while delving more into byebug's operation.
-
-In this section we will also use unit testing. Using unit tests will greatly
-reduce the amount of debugging needed, while at the same time, will increase the
-quality of your program.
-
-What we'll do is take the @code{triangle} code from the first session and write
-a unit test for that. In a sense we did write a minitest for the program which
-was basically the last line where we printed the value of triangle(3). This test
-however wasn't automated: the implication is that someone would look at the
-output and verify that what was printed is what was expected.
-
-Before we can turn that into something that can be @code{required}, we probably
-want to remove that output. However I like to keep in that line so that when I
-look at the file, I have an example of how to run it.  Therefore we will
-conditionally run this line if that file is invoked directly, but skip it if it
-is not@footnote{@code{byebug} resets @code{$0} to try to make things like this
-work.}.
-@smallexample
-  if __FILE__ == $0
-    t = triangle(3)
-    puts t
-  end
-@end smallexample
-
-Let's call this file @code{tri2.rb}.
-
-Okay, we're now ready to write our unit test. We'll use @code{"test/unit"} which
-comes with the standard Ruby distribution.  Here's the test code; it should be
-in the same directory as tri2.rb.
-@smallexample
-  #!/usr/bin/env ruby
-  require 'test/unit'
-  require_relative './tri2.rb'
-
-  class TestTri < Test::Unit::TestCase
-    def test_basic
-      solutions = []
-      0.upto(5) do |i|
-        solutions << triangle(i)
-      end
-      assert_equal([0, 1, 3, 6, 10, 15], solutions,
-                   'Testing the first 5 triangle numbers')
-    end
-  end
-@end smallexample
-
-If you run it, it will work. However if you run @code{byebug} initially, you
-will not get into the test, because @code{test/unit} wants to be the main
-program. So here is a situation where one may need to modify the program to add
-an explicit @emph{entry} into byebug. @footnote{For some versions of rake and
-@code{byebug} you can in fact set a breakpoint after running @code{byebug}
-initially. Personally though I find it much simpler and more reliable to modify
-the code as shown here.}
-
-One way to do this is to add the following before the place you want to stop:
-@smallexample
-  require 'byebug'
-  byebug
-@end smallexample
-
-Let's add this code just after entering @code{test_basic}:
-@smallexample
-  ...
-  def test_basic
-    @b{require "byebug"}
-    @b{byebug}
-    solutions = []
-   ...
-@end smallexample
-
-Now we run the program..
-@smallexample
-  $ @b{ruby test-tri.rb}
-  Loaded suite test-tri
-  Started
-  test-tri.rb:9
-  solutions = []
-  (byebug:1)
-@end smallexample
-and we see that we are stopped at line 9 just before the initialization of the
-list @code{solutions}.
-
-Now let's see where we are...
-@smallexample
-(byebug:1) @b{where}
---> #0 TestTri.test_basic at /home/rocky/ruby/test-tri.rb:9
-(byebug:1)
-@end smallexample
-
-Something seems wrong here; @code{TestTri.test_basic} indicates that we are in
-class @code{TestTri} in method @code{test_basic}. However we don't see the call
-to this like we did in the last example when we used the @code{where} command.
-This is because byebug really didn't spring into existence until after we
-already had entered that method, and Ruby doesn't keep call stack information
-around in a way that would give the information we show when running
-@code{where}.
-
-If we want call stack information, we have to turn call-stack tracking on
-@emph{beforehand}. This is done by adding @code{Byebug.start}.
-
-Here's what our test program looks like so after we modify it to start tracking
-calls from the outset
-@smallexample
-#!/usr/bin/env ruby
-require 'test/unit'
-require 'tri2.rb'
-require 'byebug'
-@b{Byebug.start}
-
-class TestTri < Test::Unit::TestCase
-  def test_basic
-    @b{byebug}
-    solutions = []
-    0.upto(5) do |i|
-      solutions << triangle(i)
-    end
-    assert_equal([0, 1, 3, 6, 10, 15], solutions,
-                 "Testing the first 5 triangle numbers")
-  end
-end
-@end smallexample
-
-Now when we run this:
-@smallexample
-$ @b{ruby test-tri2.rb}
-Loaded suite test-tri2
-Started
-test-tri2.rb:11
-solutions = []
-(byebug:1) @b{where}
---> #0 TestTri.test_basic at test-tri2.rb:11
-    #1 MiniTest::Unit::TestCase.run(runner#MiniTest::Unit)
-       at /usr/local/lib/ruby/1.9.1/minitest/unit.rb:458
-    #2 MiniTest::Unit.run_test_suites
-       at /usr/local/lib/ruby/1.9.1/minitest/unit.rb:426
-    #3 MiniTest::Unit.run
-       at /usr/local/lib/ruby/1.9.1/minitest/unit.rb:393
-    #4 at /usr/local/lib/ruby/1.9.1/minitest/unit.rb:334
-(byebug:1)
-@end smallexample
-
-Much better. But again let me emphasize that the parameter types are those of
-the corresponding variables that @emph{currently} exist, and this might have
-changed since the time when the call was made.
-
-@node Byebug.start with a block
-@section Using the @code{Byebug.start} with a block
-
-We saw that @code{Byebug.start()} and @code{Byebug.stop()} allow fine-grain
-control over where byebug tracking should occur.
-
-Rather than use an explicit @code{stop()}, you can also pass a block to the
-@code{start()} method. This causes @code{start()} to run and then @code{yield}
-to that block. When the block is finished, @code{stop()} is run. In other words,
-this wraps a @code{Byebug.start()} and @code{Byebug.stop()} around the block of
-code. But it also has a side benefit of ensuring that in the presence of an
-uncaught exception @code{stop} is run, without having to explicitly use
-@code{begin} ... @code{ensure Byebug.stop() end}.
-
-For example, in Ruby on Rails you might want to debug code in one of the
-controllers without causing any slowdown to any other code. And this can be done
-by wrapping the controller in a @code{start()} with a block; when the method
-wrapped this way finishes, byebug is turned off and the application proceeds at
-regular speed.
-
-Of course, inside the block you will probably want to enter the byebug using
-@code{Byebug.byebug()}, otherwise there would be little point in using the
-@code{start}. For example, you can do this in @code{irb}:
-@smallexample
-$ @b{irb}
-irb(main):001:0> @b{require 'byebug'}
-=> true
-irb(main):002:0> @b{def foo}
-irb(main):003:1> @b{x=1}
-irb(main):004:1> @b{puts 'foo'}
-irb(main):005:1> @b{end}
-=> nil
-irb(main):006:0> @b{Byebug.start@{byebug; foo@}}
-(irb):3
-
-(byebug:1) @b{s}
-(irb):4
-
-(byebug:1) @b{p x}
-1
-(byebug:1) @b{s}
-foo
-=> true
-irb(main):007:0>
-@end smallexample
-
-There is a counter inside of @code{Byebug.start} method to make sure that this
-works when another @code{Byebug.start} method is called inside of the outer one.
-However if you are stopped inside byebug, issuing another @code{byebug} call
-will not have any effect even if it is nested inside another
-@code{Byebug.start}.
-
-@node Debugging Oddities
-@section How debugging Ruby may be different from debugging other languages
-
-If you are used to debugging in other languages like C, C++, Perl, Java or even
-Bash@footnote{this is just an excuse to put in a shameless plug for this bash
-debugger @url{http://bashdb.sf.net}}, there may be a number of things that seem
-or feel a little bit different and may confuse you. A number of these things
-aren't oddities of the debugger per se, so much as a difference in how Ruby
-works compared to those other languages. Because Ruby works a little differently
-from those other languages, writing a debugger has to also be a little
-different as well if it is to be useful.
-
-In this respect, using byebug may help you understand Ruby better.
-
-We've already seen two examples of such differences. One difference is the fact
-that we stop on method definitions or @code{def}'s and that is because these are
-in fact executable statements. In other compiled languages this would not happen
-because that's already been done when you compile the program (or in Perl when
-it scans in the program). The other difference we saw was our inability to show
-call stack parameter types without having made arrangements for byebug to track
-this. In other languages call stack information is usually available without
-asking assistance of the debugger@footnote{However in C and C++ you generally
-have to ask the compiler to add such information.}.
-
-In this section we'll consider some other things that might throw off new users
-to Ruby who are familiar with other languages and debugging in them.
-
-@menu
-* Bouncing Around in Blocks (e.g. Iterators)::
-* No Parameter Values in a Call Stack::
-* Lines You Can Stop At::
-@end menu
-
-@node Bouncing Around in Blocks (e.g. Iterators)
-@subsection Bouncing Around in Blocks (e.g.@: Iterators)
-When debugging languages with coroutines like Python and Ruby, a method call may
-not necessarily go to the first statement after the method header. It's possible
-that the call will continue after a @code{yield} statement from a prior call.
-
-@smallexample
- 1 #!/usr/bin/env ruby
- 2 # Enumerator for primes
- 3 class SievePrime
- 4   @@@@odd_primes = []
- 5   def self.next_prime(&block)
- 6     candidate = 2
- 7     yield candidate
- 8     not_prime = false
- 9     candidate += 1
-10     while true do
-11       @@@@odd_primes.each do |p|
-12         not_prime = (0 == (candidate % p))
-13         break if not_prime
-14       end
-15       unless not_prime
-16         @@@@odd_primes << candidate
-17         yield candidate
-18       end
-19       candidate += 2
-20     end
-21   end
-22 end
-23 SievePrime.next_prime do |prime|
-24   puts prime
-25   break if prime > 10
-26 end
-@end smallexample
-
-@smallexample
-$ @b{byebug primes.rb}
-primes.rb:3
-class SievePrime
-(byebug:1) @b{set linetrace on}
-line tracing is on.
-(byebug:1) @b{step 9}
-Tracing(1):primes.rb:4 @@odd_primes = []
-Tracing(1):primes.rb:5 def self.next_prime(&block)
-Tracing(1):primes.rb:23 SievePrime.next_prime do |prime|
-Tracing(1):primes.rb:6 candidate = 2
-Tracing(1):primes.rb:7 yield candidate
-Tracing(1):primes.rb:24 puts prime
-2
-Tracing(1):primes.rb:25 break if prime > 10
-Tracing(1):primes.rb:8 not_prime = false
-Tracing(1):primes.rb:9 candidate += 1
-primes.rb:9
-candidate += 1
-(byebug:1)
-@end smallexample
-
-The loop between lines 23--26 gets interleaved between those of
-@code{Sieve::next_prime}, lines 6--19 above.
-
-@node No Parameter Values in a Call Stack
-@subsection No Parameter Values in a Call Stack
-In traditional debuggers, in a call stack you can generally see the names of the
-parameters and the values that were passed in.
-
-Ruby is a very dynamic language and it tries to be efficient within the confines
-of the language definition. Values generally aren't taken out of a variable or
-expression and pushed onto a stack. Instead a new scope created and the
-parameters are given initial values. Parameter passing is by @emph{reference},
-not by value as it is say Algol, C, or Perl. During the execution of a method,
-parameter values can change---and often do. In fact even the @emph{class} of the
-object can change.
-
-So at present, the name of the parameter shown. The call-style setting
-@pxref{Callstyle} can be used to set whether the name is shown or the name and
-the @emph{current} class of the object.
-
-It has been contemplated that a style might be added which saves on call shorter
-``scalar'' types of values and the class name.
-
-@node Lines You Can Stop At
-@subsection Lines You Can Stop At
-As with the duplicate stops per control (e.g.@: @code{if} statement), until
-tools like byebugs get more traction among core ruby developers there are going
-to be weirdness. Here we describe the stopping locations which effects the
-breakpoint line numbers you can stop at.
-
-Consider the following little Ruby program.
-@smallexample
-'Yes it does' =~ /
-(Yes) \s+
-it  \s+
-does
-/ix
-puts $1
-@end smallexample
-
-The stopping points that Ruby records are the last two lines, lines 5 and 6.
-
-Inside @code{byebug} you can get a list of stoppable lines for a file using the
-@code{info file} command with the attribute @code{breakpoints}.
-
-@ifset FINISHED
-To be continued...
-
-@itemize @bullet
-@item more complex example with objects, pretty printing and irb.
-@item line tracing and non-interactive tracing.
-@item mixing in Byebug.debug with byebug
-@item post-mortem debugging and setting up for that
-@item references to videos
-@end itemize
-@end ifset
-
-@node Invocation
-@chapter Getting in & out
-
-@menu
-* Starting byebug::      How to enter byebug
-* Command Files::        Command files
-* Quitting byebug::      How to leave byebug (quit, kill)
-* Calling from Program:: Calling byebug from inside your program
-* Post-Mortem Debugging:: Enter byebug after an uncaught exception
-@end menu
-
-@node Starting byebug
-@section Starting byebug
-
-Probably the most familiar thing to do is invoke byebug from a command line. A
-wrapper shell script called @code{byebug} basically @code{require}'s the gem
-package @code{byebug} and then loads @code{byebug}.
-
-@smallexample
-byebug [byebug-options] [--] @var{ruby-script} @var{ruby-script-arguments...}
-@end smallexample
-
-If you don't need to pass dash options to your program which might get confused
-with byebug options, then you don't need to add the @option{--}.
-
-To get a brief list of options and descriptions, use the @code{--help} option.
-
-@smallexample
-$ @b{byebug --help}
-byebug @value{BYEBUG_VERSION}
-Usage: byebug [options] <script.rb> -- <script.rb parameters>
-
-Options:
-    -d, --debug                Set $DEBUG=true
-    -I, --include PATH         Add PATH to $LOAD_PATH
-    -m, --post-mortem          Activate post-mortem mode
-        --no-quit              Do not quit when script finishes
-        --no-stop              Do not stop when script is loaded
-    -nx                        Don't run any initialization files like .byebugrc
-    -r, --require SCRIPT       Require the library, before executing your script
-        --restart-script FILE  Name of the script file to run. Erased after read
-        --script FILE          Name of the script file to run
-    -x, --trace                Turn on line tracing
-
-Common options:
-        --help                 Show this message
-        --version              Print the version
-    -v                         Print version number, then turn on verbose mode
-@end smallexample
-
-Options for the @code{byebug} are shown in the following list.
-
-@menu
-* byebug command-line options::   Options you can pass to byebug
-* byebug default options::        How to Set Default Command-Line Options
-@end menu
-
-@node byebug command-line options
-@subsection Options you can pass to byebug
-
-You can run @code{byebug} in various alternative modes, for example, as a
-program that interacts directly with the program in the same process on the same
-computer or via a socket to another process possibly on a different computer.
-
-Many options appear as a long option name, such as @option{--help}, and a short
-one letter option name, such as @option{-h}. A double dash (@option{--} is used
-to separate options which go to @code{byebug} from options that are intended to
-go to your Ruby script. Options (if any) to @code{byebug} should come first. If
-there is no possibility of the Ruby script to be debugged getting confused with
-@code{byebug}'s option, the double dash can be omitted.
-
-@table @code
-@item --help
-@cindex @option{-h}
-@cindex @option{--help}
-This option causes @code{byebug} to print some basic help and exit.
-
-@item -v | --version
-@cindex @option{-v}
-This option causes @code{byebug} to print its version number and exit.
-
-@item --debug
-@cindex @option{--debug}
-Set @code{$DEBUG} to @code{true}. This option is compatible with Ruby's.
-
-@item -I --include @var{PATH}
-@cindex @option{-I} @var{PATH}
-@cindex @option{--include} @var{PATH}
-Add @var{PATH} to @code{$LOAD_PATH}
-
-@item -m | --post-mortem
-@cindex @option{-m}
-@cindex @option{--post-mortem}
-If your program raises an exception that isn't caught you can enter byebug for
-inspection of what went wrong. You may also want to use this option in
-conjunction with @option{--no-stop}. See also @ref{Post-Mortem Debugging}.
-
-@item --no-quit
-@cindex @option{--no-quit}
-Restart byebug when your program terminates normally.
-
-@item --no-stop
-@cindex @option{--no-stop}
-Normally the @code{byebug} stops before executing the first statement. If
-instead you want it to start running initially and will perhaps break it later
-in the running, use this options.
-
-@item -r | --require @var{library}
-@cindex @option{-r}
-@cindex @option{--require}
-Require the library, before executing your script. However if the library
-happened to be @code{debug}, we'll just ignore the require (since we're already
-a debugger). This option is compatible with Ruby's.
-
-@item --script @var{file}
-@cindex @option{--script}
-Require the library, before executing your script. However if the library
-happend to be @code{debug}, we'll just ignore the require (since we're already a
-debugger). This option is compatible with Ruby's.
-
-@item -x | --trace
-@cindex @option{-x}
-@cindex @option{--trace}
-Turn on line tracing. Running @command{byebug --trace @emph{rubyscript.rb}}
-is much like running: @command{ruby -rtracer @emph{rubyscript.rb}}
-
-If all you want to do however is get a linetrace, @code{tracer} and not
-@code{byebug}, may be faster:
-
-@smallexample
-$ @b{time ruby -rtracer gcd.rb 34 21 > /dev/null}
-
-real  0m0.266s
-user  0m0.008s
-sys  0m0.000s
-$ @b{time byebug --trace gcd.rb 34 21 > /dev/null}
-
-real  0m0.875s
-user  0m0.448s
-sys  0m0.056s
-$
-@end smallexample
-@end table
-
-@node byebug default options
-@subsection How to Set Default Command-Line Options
-
-@code{byebug} has many command-line options; it seems that some people want to
-set them differently from the defaults. For example, some people may want
-@option{--no-quit --no-control} to be the default behavior. One could write a
-wrapper script or set a shell alias to handle this. But @code{byebug} has
-another way to do this. Before processing command options, if the file
-@code{$HOME/.rdboptrc} is found, it is loaded. If you want to set the defaults
-in some other way, you can put Ruby code here and set variable @code{options}
-which is an OpenStruct. For example here's how you'd set @option{-no-quit} and
-change the default control port to 5000.
-
-@smallexample
-# This file contains how you want the default options to byebug to be set. Any
-# Ruby code can be put here.
-#
-# byebug # Uncomment if you want to debug byebug!
-options.control = false
-options.port = 5000
-puts "rocky's rdboptrc run"
-@end smallexample
-
-Here are the default values in @code{options}
-@smallexample
-#<OpenStruct server=false, client=false, frame_bind=false, cport=8990,
-             tracing=false, nx=false, post_mortem=false, port=8989,
-             control=true, restart_script=nil, quit=true, stop=true, script=nil,
-             host=nil, wait=false>
-@end smallexample
-
-@node Command Files
-@section Command files
-
-@cindex command files
-A command file is a file of lines that are @code{byebug} commands. Comments
-(lines starting with @kbd{#}) may also be included. An empty line in a command
-file does nothing; it does not mean to repeat the last command, as it would from
-the terminal.
-
-@cindex init file
-@cindex @file{.byebugrc}
-When you start @code{byebug}, it automatically executes commands from its
-@dfn{init files}, normally called @file{.byebugrc}. On some configurations of
-@code{byebug}, the init file may be known by a different name.
-
-During startup, @code{byebug} does the following:
-
-@enumerate
-@item
-Processes command line options and operands.
-
-@item
-Reads the init file in your current directory, if any, and then checks your home
-directory. The home directory is the directory named in the @code{HOME} or
-@code{HOMEPATH} environment variable. Thus, you can have more than one init
-file, one generic in your home directory, and another, specific to the program
-you are debugging, in the directory where you invoke @code{byebug}.
-
-@item
-Reads command files specified by the @samp{--script} option.
-@end enumerate
-
-You can also request the execution of a command file with the @code{source}
-command, @pxref{Source}.
-
-@node Quitting byebug
-@section Quitting byebug
-
-Inside a byebug interpreter, use @code{quit} command (
-@pxref{Control, ,Quitting byebug}).
-
-Another way to terminate byebug is to use the @code{kill} command. This does the
-more forceful @code{kill -9}. It can be used in cases where @code{quit} doesn't
-work.
-
-@node Calling from Program
-@section Calling byebug from inside your Ruby program
-
-Running a program from byebug adds a bit of overhead and slows down your program
-a little. Furthermore, by necessity, debuggers change the operation of the
-program they are debugging. And this can lead to unexpected and unwanted
-differences. It has happened so often that the term ``Heisenbugs'' (see
-@url{http://en.wikipedia.org/wiki/Heisenbug}) was coined to describe the
-situation where using a debugger (among other possibilities) changes the
-behavior of the program so that the bug doesn't manifest itself anymore.
-
-There is another way to get into byebug which adds no overhead or slowdown until
-you reach the point at which you want to start debugging. However here you must
-change the script and make an explicit call to byebug. Because byebug isn't
-involved before the first call, there is no overhead and the script will run
-at the same speed as if there were no byebug.
-
-There are three parts to calling byebug from inside the script, ``requiring''
-the gem, telling byebug to start tracking things and then making an explicit
-breakpoints.
-
-To get byebug class accessible from your Ruby program:
-@smallexample
-require 'byebug'
-@end smallexample
-
-After @code{require 'byebug'}, it's possible to set some of the byebug variables
-influence preferences. For example if you want to have @code{byebug} run a
-@code{list} command every time it stops you set the variable
-@code{Byebug.settings[:autolist]}. @pxref{Byebug.settings} has a list of
-variable settings and the default values. Byebug settings can also be set in
-@code{.byebugrc} as byebug commands. @pxref{Command Files}
-
-To tell byebug to start tracking things:
-@smallexample
-Byebug.start
-@end smallexample
-
-There is also a @code{Byebug.stop} to turn off byebug tracking. If speed is
-crucial, you may want to start and stop this around certain sections of code.
-Alternatively, instead of issuing an explicit @code{Byebug.stop} you can add a
-block to the @code{Byebug.start} and debugging is turned on for that block. If
-the block of code raises an uncaught exception that would cause the block to
-terminate, the @code{stop} will occur.  See @ref{Byebug.start with a block}.
-
-And finally to enter byebug:
-@smallexample
-byebug
-@end smallexample
-
-As indicated above, when @code{byebug} is run a @code{.byebugrc} profile is read
-if that file exists.
-
-You may want to enter byebug at several points in the program where there is a
-problem you want to investigate. And since @code{byebug} is just a method call
-it's possible enclose it in a conditional expression, for example:
-@smallexample
-byebug if 'bar' == foo and 20 == iter_count
-@end smallexample
-
-Although each step does a very specific thing which offers great flexibility, in
-order to make getting into byebug easier the three steps have been rolled into
-one command:
-@smallexample
-require "byebug/byebug"
-@end smallexample
-
-@node Byebug Command Reference
-@chapter @code{byebug} Command Reference
-
-@menu
-* Command Interfaces::  The kinds of interface used to interact with byebug
-* Command Syntax::      How to give commands to byebug
-* Command Output::      How byebug presents its output
-* Help::                How to ask for help (help)
-* Control::             Controlling byebug (quit, restart)
-* DisplayCommands::     Executing expressions on stop (display, undisplay)
-* PrintCommands::       Evaluating and Printing Expressions (p, pp, ps, pp, irb)
-* PrintVars::           Printing Variables (var)
-* List::                Examining Program Source Files (list)
-* Edit::                Editing source files (edit)
-* FrameCommands::       Examining the stack frame (where, up, down, frame)
-* Stopping::            Stopping and continuing (break, watch, step, cont...)
-* byebug settings::     byebug-settings (set args, set autoeval, ...)
-* Program Information:: Program Status  (info)
-@end menu
-
-@node Command Interfaces
-@section Command Interfaces
-There are several ways one can talk to @code{byebug} and get results. The
-simplest way is via a command-line interface directly talking to byebug. This is
-referred to below as a ``Local Interface''. It's also possible to run byebug and
-set up a port by which some other process can connect and control the debug
-session. This is called a ``Remote Interface''. When you want to gain access to
-a remote interface you need to run @code{byebug} using a ``Control Interface''.
-This interface might not be the same process as the process running the debugged
-program and might not even be running on the same computer.
-
-Other front-ends may use one of these and build on top and provide other
-(richer) interfaces. Although many of the commands are available on all
-interfaces some are not. Most of the time in this manual when we talk about
-issuing commands describing the responses elicited, we'll assume we are working
-with the local interface.
-
-@node Command Syntax
-@section Command Syntax
-Usually a command is put on a single line. There is no limit on how long it can
-be. It starts with a command name, which is followed by arguments whose meaning
-depends on the command name. For example, the command @code{step} accepts an
-argument which is the number of times to step, as in @code{step 5}. You can also
-use the @code{step} command with no arguments. Some commands do not allow any
-arguments.
-
-Multiple commands can be put on a line by separating each with a semicolon
-(@code{;}). You can disable the meaning of a semicolon to separate commands by
-escaping it with a backslash.
-
-For example, if you have @code{autoeval} (@ref{Autoeval}) set, you might want to
-enter the following code to compute the 5th Fibonacci number:
-@smallexample
-# Compute the 5 Fibonaci number
-(byebug:1) set autoeval on
-(byebug:1) fib1=0; fib2=1; 5.times @{|temp| temp=fib1; fib1=fib2; fib2 += temp @}
-SyntaxError Exception: compile error
-/usr/bin/irb:10: syntax error, unexpected $end, expecting '@}'
- 5.times @{|temp| temp=fib1
-                          ^
-(byebug:1) fib1=0\; fib2=1\; 5.times @{|temp| temp=fib1\; fib1=fib2\; fib2 += temp @}
-5
-(byebug:1) fib2
-fib2
-8
-@end smallexample
-
-You might also consider using the @code{irb} command, @ref{irb}, and then you
-won't have to escape semicolons.
-
-A blank line as input (typing just @key{<RET>}) means to repeat the previous
-command.
-
-In the ``local'' interface, the Ruby Readline module is used. It handles line
-editing and retrieval of previous commands. Up arrow, for example moves to the
-previous byebug command; down arrow moves to the next more recent command
-(provided you are not already at the last command). Command history is saved in
-file @code{.byebug_hist}. A limit is put on the history size. You can see this
-with the @code{show history size} command. See @ref{History} for history
-parameters.
-
-@node Command Output
-@section Command Output
-In the command-line interface, when @code{byebug} is waiting for input it
-presents a prompt of the form @code{(byebug)}. If the program has terminated
-normally the prompt will be @code{(byebug:ctrl)} and in post-mortem debugging it
-will be @code{(byebug:post-mortem)}.
-
-In the local interface, whenever @code{byebug} gives an error message such as
-for an invalid command, or an invalid location position, it will generally
-preface the message with @code{***}.
-
-@node Help
-@section Getting help (@samp{help})
-@cindex on-line documentation
-@menu
-* Help for Subcommands::
-@end menu
-
-Once inside @code{byebug} you can always ask it for information on its commands
-using the @code{help} command.
-
-@table @code
-@kindex h @r{(@code{help})}
-@kindex help @ovar{command-name}
-@item help
-@itemx h
-You can use @code{help} (abbreviated @code{h}) with no arguments to display a
-short list of named classes of commands:
-
-@flushleft
-@smallexample
-(byebug:1) @b{help}
-byebug help v@value{BYEBUG_VERSION}
-Type 'help <command-name>' for help on a specific command
-
-Available commands:
-backtrace  delete   enable  help  method  ps       save    step       where
-break      disable  eval    info  next    putl     set     trace
-catch      display  exit    irb   p       quit     show    undisplay
-condition  down     finish  kill  pp      reload   skip    up
-continue   edit     frame   list  pry     restart  source  var
-@end smallexample
-@end flushleft
-@c the above line break eliminates huge line overfull...
-
-@end table
-
-@table @code
-@item help @var{command}
-With a command name as @code{help} argument, @code{byebug} displays short
-information on how to use that command.
-
-@smallexample
-(byebug:1) @b{help list}
-byebug help v@value{BYEBUG_VERSION}
-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'
-(byebug:1)
-@end smallexample
-@end table
-
-@node Help for Subcommands
-@subsection Help on Subcommands
-A number of commands have many sub-parameters or @emph{subcommands}. These
-include @code{info}, @code{set}, @code{show}, @code{enable} and @code{disable}.
-
-When you ask for help for one of these commands, you will get help for all of
-the subcommands that that command offers. Sometimes you may want help that
-subcommand and to do this just follow the command with its subcommand name. For
-example @code{help info breakpoints} will just give help about the
-@code{info breakpoints} command. Furthermore it will give longer help than the
-summary information that appears when you ask for help. You don't need to list
-the full subcommand name, but just enough of the letters to make that subcommand
-distinct from others will do. For example, @code{help info b} is the same as
-@code{help info breakpoints}.
-
-Some examples follow.
-@example
-(byebug:1) @b{help 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 variables -- Local and instance variables of the current stack frame
-@end example
-
-@example
-(byebug:1) @b{help info breakpoints}
-Status of user-settable breakpoints.
-Without argument, list info about all breakpoints.
-With an integer argument, list info on that breakpoint.
-@end example
-
-@example
-(byebug:1) @b{help info br}
-Status of user-settable breakpoints.
-Without argument, list info about all breakpoints.
-With an integer argument, list info on that breakpoint.
-@end example
-
-@node Control
-@section Controlling byebug (@samp{quit}, @samp{restart}, @samp{source})
-
-@menu
-* Quit::      Quitting byebug (quit)
-* Restart::   Restarting script execution (restart)
-* Source::    Running Byebug commands (source)
-@end menu
-
-@node Quit
-@subsection Quit (@samp{quit})
-
-@table @code
-@kindex quit @r{[}unconditionally@r{]}
-@kindex q @r{(@code{quit})}
-@item quit @r{[}unconditionally@r{]}
-@item exit
-@itemx q
-
-To exit @code{byebug}, use the @code{quit} command (abbreviated @code{q}), or
-alias @code{exit}.
-
-Normally if you are in an interactive session, this command will prompt to ask
-if you really want to quit. If you don't want any questions asked, enter
-``unconditionally''.
-@end table
-
-@node Restart
-@subsection Restarting script execution (@samp{restart})
-
-@table @code
-@kindex restart @r{[}@var{program args}@r{]}
-@kindex R @r{(@code{restart})}
-@item restart
-@itemx R
-Restart the program. This is a re-exec - all byebug state is lost. If command
-arguments are passed those are used. Otherwise program arguments from the last
-invocation are used.
-
-You won't be able to restart your program in all cases. First, the program
-should have been invoked at the outset rather than having been called from
-inside your program or invoked as a result of post-mortem handling.
-
-Also, since this relies on the the OS @code{exec} call, this command is
-available only if your OS supports @code{exec}; OSX for example does not (yet).
-@end table
-
-@node Source
-@subsection Running Byebug Commands (@samp{source})
-
-@table @code
-@kindex source @var{filename}
-@item source @var{filename}
-Execute the command file @var{filename}.
-
-The lines in a command file are executed sequentially.  They are not printed as
-they are executed.  If there is an error, execution proceeds to the next command
-in the file. For information about command files that get run automatically on
-startup, @pxref{Command Files}.
-@end table
-
-@node DisplayCommands
-@section Executing expressions on stop (@samp{display}, @samp{undisplay})
-@cindex automatic display
-@cindex display of expressions
-
-If you find that you want to print the value of an expression frequently (to see
-how it changes), you might want to add it to the @dfn{automatic display list} so
-that @code{byebug} evaluates a statement each time your program stops or the
-statement is shown in line tracing. Each expression added to the list is given a
-number to identify it; to remove an expression from the list, you specify that
-number. The automatic display looks like this:
-
-@smallexample
-(byebug:1) display n
-1: n = 3
-@end smallexample
-
-@noindent
-This display shows item numbers, expressions and their current values. If the
-expression is undefined or illegal the expression will be printed but no value
-will appear.
-
-@smallexample
-(byebug:1) display undefined_variable
-2: undefined_variable =
-(byebug:1) display 1/0
-3: 1/0 =
-@end smallexample
-
-Note: this command uses @code{to_s} in expressions; for example an array
-@code{[1, 2]} will appear as @code{12}. For some datatypes like an Array, you
-may want to call the @code{inspect} method, for example
-@code{display ARGV.inspect} rather than @code{display ARGV}.
-
-@table @code
-@kindex display @ovar{expr}
-@item display @var{expr}
-Add the expression @var{expr} to the list of expressions to display each time
-your program stops or a line is printed when linetracing is on
-(@pxref{DisplayCommands}).
-
-@item display
-Display the current values of the expressions on the list, just as is done when
-your program stops.
-
-@kindex undisplay @ovar{num}
-@item undisplay @ovar{num}
-@itemx delete display @var{num}
-Remove item number @var{num} from the list of expressions to display.
-
-@kindex info display
-@item info display
-Show all display expressions
-
-@ifset GDB_COMPLETED
-@code{undisplay} does not repeat if you press @key{RET} after using it.
-(Otherwise you would just get the error @samp{No display number @dots{}}.)
-@end ifset
-
-@kindex disable display
-@item disable display @var{dnums}@dots{}
-Disable the display of item numbers @var{dnums}. A disabled display item is not
-printed automatically, but is not forgotten. It may be enabled again later.
-
-@kindex enable display
-@item enable display @var{dnums}@dots{}
-Enable display of item numbers @var{dnums}. It becomes effective once again in
-auto display of its expression, until you specify otherwise.
-
-@end table
-
-@node PrintCommands
-@section Evaluating and Printing Expressions (@samp{p}, @samp{pp}, @samp{putl}, @samp{ps}, @samp{irb})
-
-One way to examine and change data in your script is with the @code{eval}
-command (abbreviated @code{p}). A similar command is @code{pp} which tries to
-pretty print the result. Finally @code{irb} is useful when you anticipate
-examining or changing a number of things and prefer not to have to preface each
-command, but rather work as one does in @code{irb}.
-
-@menu
-* eval:: eval or print an expression (eval, p)
-* pp::   pretty print an expression (pp, ps, putl)
-* irb::  running irb using the current context
-@end menu
-
-@node eval
-@subsection Printing an expression (@samp{eval}, @samp{p})
-@table @code
-@kindex eval @var{expr}
-@kindex p @r{(@code{eval})}
-@item eval @var{expr}
-@itemx p @var{expr}
-
-Use @code{eval} or @code{p} to evaluate a Ruby expression, @var{expr}, same as
-you would if you were in @code{irb}. If there are many expressions you want to
-look at, you may want to go into irb from byebug.
-
-@smallexample
-@group
-(byebug:p) p n
-3
-(byebug:1) p "the value of n is #@{n@}"
-"the value of n is 3"
-(byebug:1)
-@end group
-@end smallexample
-@end table
-
-@node pp
-@subsection Pretty-Printing an expression (@samp{pp}, @samp{putl}, @samp{ps}))
-@table @code
-@item pp
-@kindex pp @var{expr}
-Evaluates and pretty-prints @var{expr}
-@smallexample
-@group
-(byebug:1) @b{p $LOAD_PATH}
-["/home/rocky/lib/ruby", "/usr/lib/ruby/site_ruby/1.8", "/usr/lib/ruby/site_ruby/1.8/i586-linux", "/usr/lib/ruby/1.8"]
-(byebug:1) @b{pp $LOAD_PATH}
-["/home/rocky/lib/ruby",
- "/usr/lib/ruby/site_ruby/1.8",
- "/usr/lib/ruby/site_ruby/1.8/i586-linux",
- "/usr/lib/ruby/1.8"]
-@end group
-@end smallexample
-
-@kindex putl
-@item putl
-If the value you want to print is an array, sometimes a columnized list looks
-nicer:
-@smallexample
-@group
-(byebug:1) @b{putl $LOAD_PATH}
-/home/rocky/lib/ruby                    /usr/lib/ruby/site_ruby/1.8
-/usr/lib/ruby/site_ruby/1.8/i586-linux  /usr/lib/ruby/1.8
-@end group
-@end smallexample
-
-Note however that entries are sorted to run down first rather than across. So
-in the example above the second entry in the list is
-@code{/usr/lib/ruby/site_ruby/1.8/i586-linux} and the @emph{third} entry is
-@code{/usr/lib/ruby/site_ruby/1.8}.
-
-If the value is not an array @code{putl} will just call pretty-print.
-
-@kindex ps
-@item ps
-Sometimes you may want to print the array not only columnized, but sorted as
-well. The list of byebug help commands appears this way, and so does the output
-of the @code{method} commands.
-
-@smallexample
-@group
-(byebug:1) ps Kernel.private_methods
-Digest                   initialize                  y
-Pathname                 initialize_copy
-Rational                 location_of_caller
-active_gem_with_options  method_added
-alias_method             method_removed
-append_features          method_undefined
-attr                     module_function
-attr_accessor            private
-attr_reader              protected
-attr_writer              public
-class_variable_get       remove_class_variable
-class_variable_set       remove_const
-define_method            remove_instance_variable
-extend_object            remove_method
-extended                 singleton_method_added
-gcd                      singleton_method_removed
-gem_original_require     singleton_method_undefined
-include                  timeout
-included                 undef_method
-@end group
-@end smallexample
-
-If the value is not an array, @code{ps} will just call pretty-print. See also
-the @code{methods}.
-@end table
-
-@node irb
-@subsection Run irb (@samp{irb})
-@table @code
-@kindex irb
-@item irb
-Run an interactive ruby session (@code{irb}) with the bindings environment set
-to the state you are in the program.
-
-When you leave irb and go back to byebug command prompt we show again the file,
-line and text position of the program in the same way as when entered byebug. If
-you issue a @command{list} without location information, the default location
-used is the current line rather than the position may have gotten updated via a
-prior @command{list} command.
-
-@smallexample
-triangle.rb:4
-def triangle(n)
-(byebug:1) @b{list}
-[1, 8] in /home/rocky/ruby/triangle.rb
-   1  #!/usr/bin/env ruby
-   2  # Compute the n'th triangle number - the hard way
-   3  # triangle(n) == (n * (n+1)) / 2
-=> 4  def triangle(n)
-   5    tri = 0
-   6    0.upto(n) do |i|
-   7      tri += i
-   8    end
-@b{irb}
->> @b{(0..6).inject@{|sum, i| sum +=i@}}
-=> 21
->> @b{exit}
-triangle.rb:4
-def triangle(n)
-(byebug:1) @b{list # Note we get the same line range as before going into irb}
-[1, 8] in /home/rocky/ruby/triangle.rb
-   1  #!/usr/bin/env ruby
-   2  # Compute the n'th triangle number - the hard way
-   3  # triangle(n) == (n * (n+1)) / 2
-=> 4  def triangle(n)
-   5    tri = 0
-   6    0.upto(n) do |i|
-   7      tri += i
-   8    end
-@end smallexample
-
-@end table
-
-@node PrintVars
-@section Printing Variables (@samp{var}, @samp{method})
-
-@table @code
-@item var const @var{object}
-@kindex var const @var{expr}
-Show the constants of @var{object}. This is basically listing
-variables and their values in @var{object}@code{.constant}.
-@item var instance @var{object}
-@kindex var instance @var{expr}
-Show the instance variables of @var{object}. This is basically listing
-@var{object}@code{.instance_variables}.
-@item info instance_variables
-@kindex info instance_variables
-Show instance_variables of @code{@@self}
-@item info locals
-@kindex info locals
-Show local variables
-@item info globals
-@kindex info globals
-Show global variables
-@item info variables
-@kindex info variables
-Show local and instance variables of @code{@@self}
-@item method instance @var{object}
-@kindex method instance @var{object}
-Show methods of @var{object}. Basically this is the same as running
-@code{ps object.instance_methods(false)} on @var{object}.
-@item method iv @var{object}
-@kindex method iv @var{object}
-Show method instance variables of @var{object}. Basically this is the same as
-running
-@smallexample
-  obj.instance_variables.each do |v|
-     puts "%s = %s\n" % [v, obj.instance_variable_get(v)]
-  end
-@end smallexample
-on @var{object}.
-@item signature @var{object}
-@kindex method signature @var{object}
-Show procedure signature of method @var{object}.
-@emph{This command is available only if the nodewrap is installed.}
-@smallexample
-  def mymethod(a, b=5, &bock)
-  end
-  (byebug:1) @b{method sig mymethod}
-  Mine#mymethod(a, b=5, &bock)
-@end smallexample
-on @var{object}.
-@item method @var{class-or-module}
-@kindex method @var{class-or-module}
-Show methods of the class or module, @var{class-or-module}. Basically this is
-the same as running @code{ps object.methods} on @var{class-or-module}.
-@end table
-
-@node List
-@section Examining Program Source Files (@samp{list})
-
-@cindex current line
-@code{byebug} can print parts of your script's source.  When your script stops,
-@code{byebug} spontaneously prints the line where it stopped and the text of
-that line. Likewise, when you select a stack frame (@pxref{Selection})
-@code{byebug} prints the line where execution in that frame has stopped.
-Implicitly there is a default line location. Each time a list command is run
-that implicit location is updated, so that running several list commands in
-succession shows a contiguous block of program text.
-
-If you don't need code context displayed every time, you can issue the @code{set
-noautolist} command. Now whenever you want code listed, you can explicitly issue
-the @code{list} or it abbreviation @code{l}. Notice that a second listing is
-displayed, we continue listing from the place we last left off. The desired
-range of lines this time is lines 9 to 18; but since the program ends at line
-13, the range is moved down so 10 lines can be shown. You can set the
-@code{noautolist} option by default by dropping @code{set noautolist} in
-byebug's startup file @code{.byebugrc}.
-
-If you want to set how many lines to print by default rather than use the
-initial number of lines, 10, use the @code{set listsize} command
-(@pxref{Listsize}). To see the entire program in one shot, we gave an explicit
-starting and ending line number.
-
-You can print other portions of source files by giving an explicit position as a
-parameter to the list command.
-
-@kindex list @ovar{line-number}
-@kindex l @r{(@code{list})}
-To print lines from a source file, use the @code{list} command
-(abbreviated @code{l}).  By default, ten lines are printed. Fewer may
-appear if there fewer lines before or after the current line to center
-the listing around.
-
-There are several ways to specify what part of the file you want to print.
-Here are the forms of the @code{list} command.
-
-@table @code
-@item list @var{line-number}
-@itemx l @var{line-number}
-Print lines centered around line number @var{line-number} in the
-current source file.
-
-@item list
-@itemx l
-Print more lines.  If the last lines printed were printed with a
-@code{list} command, this prints lines following the last lines
-printed; however, if the last line printed was a solitary line printed
-as part of displaying a stack frame (@pxref{Frames}), this prints lines
-centered around that line.
-
-@item list -
-@itemx l -
-Print lines just before the lines last printed.
-@item list @var{first}-@var{last}
-Print lines between @var{first} and @var{last} inclusive.
-
-@item list =
-Print lines centered around where the script is stopped.
-@end table
-
-Repeating a @code{list} command with @key{RET} discards the argument, so it is
-equivalent to typing just @code{list}.  This is more useful than listing the
-same lines again.  An exception is made for an argument of @samp{-}; that
-argument is preserved in repetition so that each repetition moves up in the
-source file.
-
-@node Edit
-@section Editing Source files (@samp{edit})
-
-To edit the lines in a source file, use the @code{edit} command.  The editing
-program of your choice is invoked with the current line set to the active line
-in the program.  Alternatively, you can give a line specification to specify
-what part of the file you want to print if you want to see other parts of the
-program.
-
-You can customize to use any editor you want by using the @code{EDITOR}
-environment variable. The only restriction is that your editor (say @code{ex})
-recognizes the following command-line syntax:
-@smallexample
-ex +@var{number} file
-@end smallexample
-The optional numeric value +@var{number} specifies the number of the line in the
-file where to start editing. For example, to configure @code{byebug} to use the
-@code{vi} editor, you could use these commands with the @code{sh} shell:
-
-@smallexample
-EDITOR=/usr/bin/vi
-export EDITOR
-gdb @dots{}
-@end smallexample
-or in the @code{csh} shell,
-@smallexample
-setenv EDITOR /usr/bin/vi
-gdb @dots{}
-@end smallexample
-
-@table @code
-@kindex edit @ovar{line-specification}
-@item edit @ovar{line specification}
-Edit line specification using the editor specified by the @code{EDITOR}
-environment variable.
-@end table
-
-@node FrameCommands
-@section Examining the Stack Frame (@samp{where}, @samp{up}, @samp{down}, @samp{frame})
-
-When your script has stopped, one thing you'll probably want to know is where it
-stopped and some idea of how it got there.
-
-@cindex call stack
-Each time your script performs a function or sends a message to a method, or
-enters a block, information about this action is saved. The frame stack then is
-a history of the blocks that got you to the point that you are currently stopped
-at.@footnote{More accurately we should call this a ``block stack''; but we'll
-use the name that is more commonly used. And internally in Ruby, there is
-``FRAME'' structure which is yet slightly different.}
-
-@cindex selected block
-One entry in call stack is @dfn{selected} by @code{byebug} and many
-@code{byebug} commands refer implicitly to the selected block.  In particular,
-whenever you ask @code{byebug} to list lines without giving a line number or
-location the value is found in the selected frame. There are special
-@code{byebug} commands to select whichever frame you are interested in.
-@xref{Selection, ,Selecting a frame}.
-
-When your program stops, @code{byebug} automatically selects the currently
-executing frame and describes it briefly, similarly to the @code{frame} command.
-
-After switching frames, when you issue a @code{list} command without any
-position information, the position used is the location in the frame that you
-just switched to, rather than a location that got updated via a prior
-@code{list} command.
-
-@menu
-* Frames::    Stack frames
-* Backtrace:: Backtraces (where)
-* Selection:: Selecting a frame (up, down, frame)
-@end menu
-
-@node Frames
-@subsection Stack frames
-
-@cindex frame, definition
-@cindex stack frame
-The block stack is divided up into contiguous pieces called @dfn{stack frames},
-@dfn{frames}, or @dfn{blocks} for short; each frame/block has a scope associated
-with itr. It contains a line number and the source-file name that the line
-refers to. If the frame/block is the beginning of a method or function it also
-contains the function name.
-
-@cindex initial frame
-@cindex outermost frame
-@cindex innermost frame
-When your script is started, the stack has only one frame, that of the function
-@code{main}.  This is called the @dfn{initial} frame or the @dfn{outermost}
-frame. Each time a function is called, a new frame is made. Each time a function
-returns, the frame for that function invocation is eliminated. If a function is
-recursive, there can be many frames for the same function. The frame for the
-function in which execution is actually occurring is called the @dfn{innermost}
-frame. This is the most recently created of all the stack frames that still
-exist.
-
-@cindex frame number
-@code{byebug} assigns numbers to all existing stack frames, starting with zero
-for the innermost frame, one for the frame that called it, and so on upward.
-These numbers do not really exist in your script; they are assigned by
-@code{byebug} to give you a way of designating stack frames inside commands.
-
-@node Backtrace
-@subsection Backtraces (@samp{where})
-
-@cindex backtraces
-@cindex tracebacks
-@cindex stack traces
-A backtrace is essentially the same as the call stack: a summary of how your
-script got where it is.  It shows one line per frame, for many frames, starting
-with the place that you are stopped at (frame zero), followed by its caller
-(frame one), and on up the stack.
-
-@table @code
-@kindex where
-@kindex w @r{(@code{where})}
-@itemx where
-Print the entire stack frame; @code{info stack} is an alias for this command.
-Each frame is numbered and can be referred to in the @code{frame} command;
-@code{up} and @code{down} add or subtract respectively to frame numbers shown.  The position of the current frame is marked with
-@code{-->}.
-
-@smallexample
-(byebug:1) where
---> #0 Object.gcd(a#Fixnum, b#Fixnum) at /tmp/gcd.rb:6
-    #1 at /tmp/gcd.rb:19
-@end smallexample
-
-@ifset FINISHED
-@item backtrace @var{n}
-@itemx bt @var{n}
-@itemx where @var{n}
-@itemx T @var{n}
-Similar, but print only the innermost @var{n} frames.
-
-@item backtrace -@var{n}
-@itemx bt -@var{n}
-@itemx where -@var{n}
-@itemx T -@var{n}
-Similar, but print only the outermost @var{n} frames.
-@end ifset
-@end table
-
-@node Selection
-@subsection Selecting a frame (@samp{up}, @samp{down}, @samp{frame})
-Commands for listing source code in your script work on whichever stack frame is
-selected at the moment.  Here are the commands for selecting a stack frame; all
-of them finish by printing a brief description of the stack frame just selected.
-
-@table @code
-@kindex up @ovar{n}
-@item up @ovar{n}
-Move @var{n} frames up the stack.  For positive numbers @var{n}, this advances
-toward the outermost frame, to higher frame numbers, to frames that have existed
-longer.  Using a negative @var{n} is the same thing as issuing a @code{down}
-command of the absolute value of the @var{n}.  Using zero for @var{n} does no
-frame adjustment, but since the current position is redisplayed, it may trigger
-a resynchronization if there is a front end also watching over things.
-
-@var{n} defaults to one. You may abbreviate @code{up} as @code{u}.
-
-@kindex down @ovar{n}
-@item down @ovar{n}
-Move @var{n} frames down the stack.  For positive numbers @var{n}, this advances
-towards the innermost frame, to lower frame numbers, to frames that were created
-more recently.  Using a negative @var{n} is the same as issuing a @code{up}
-command of the absolute value of the @var{n}.  Using zero for @var{n} does no
-frame adjustment, but since the current position is redisplayed, it may trigger
-a resynchronization if there is a front end also watching over things.
-
-@var{n} defaults to one.
-@end table
-
-@table @code
-@kindex frame @r{[} @ovar{n}@r{]}
-@cindex current stack frame
-@item frame@r{[} @ovar{n}@r{]}
-The @code{frame} command allows you to move from one stack frame to another, and
-to print the stack frame you select.  @var{n} is the the stack frame number or 0
-if no frame number is given; @code{frame 0} then will always show the current
-and most recent stack frame.
-
-If a negative number is given, counting is from the other end of the stack
-frame, so @code{frame -1} shows the least-recent, outermost or most ``main''
-stack frame.
-
-Without an argument, @code{frame} prints the current stack frame. Since the
-current position is redisplayed, it may trigger a resynchronization if there is
-a front end also watching over things.
-@end table
-
-@node Stopping
-@section Stopping and Resuming Execution
-One important use of a debugger is to stop your program @emph{before} it
-terminates, so that if your script runs into trouble you can investigate and
-find out why. However should your script accidentally continue to termination,
-it can be arranged for @code{byebug} to not to leave byebug without your
-explicit instruction. That way, you can restart the program using the same
-command arguments.
-
-Inside @code{byebug}, your script may stop for any of several reasons, such as a
-signal, a breakpoint, or reaching a new line after a @code{byebug} command such
-as @code{step}.  You may then examine and change variables, set new breakpoints
-or remove old ones, and then continue execution.
-
-@menu
-* Breakpoints::        Breakpoints (break, catch, delete)
-* Disabling::          Disabling breakpoints (disable, enable)
-* Conditions::         Break conditions (condition)
-* Resuming Execution:: Resuming execution (continue, step, next, finish)
-@end menu
-
-@node Breakpoints
-@subsection Breakpoints (@samp{break}, @samp{catch}, @samp{delete})
-
-@cindex breakpoints
-A @dfn{breakpoint} makes your script stop whenever a certain point in the
-program is reached. For each breakpoint, you can add conditions to control in
-finer detail whether your script stops. You specify the place where your script
-should stop with the @code{break} command and its variants.
-
-@cindex breakpoint numbers
-@cindex numbers for breakpoints
-@code{byebug} assigns a number to each breakpoint when you create it; these
-numbers are successive integers starting with one. In many of the commands for
-controlling various features of breakpoints you use the breakpoint number to say
-which breakpoint you want to change. Each breakpoint may be @dfn{enabled} or
-@dfn{disabled}; if disabled, it has no effect on your script until you enable it
-again.
-
-
-@table @code
-@kindex break @ovar{location}
-@kindex b @r{(@code{break})}
-@item break
-Set a breakpoint at the current line.
-
-@item break @var{linenum}
-Set a breakpoint at line @var{linenum} in the current source file. The current
-source file is the last file whose source text was printed. The breakpoint will
-stop your script just before it executes any of the code on that line.
-
-@item break @var{filename}:@var{linenum}
-Set a breakpoint at line @var{linenum} in source file @var{filename}.
-
-What may be a little tricky when specifying the filename is getting the name
-recognized by @code{byebug}. If you get a message the message ``@code{No source
-file named ...}'', then you may need to qualify the name more fully. To see what
-files are loaded you can use the @code{info files} or @code{info file} commands.
-If you want the name @code{byebug} thinks of as the current file, use
-@code{info line}.
-
-Here's an example:
-@example
-$ @b{byebug ~/ruby/gcd.rb 3 5}
-/home/rocky/ruby/gcd.rb:4   # Note this is the file name
-def gcd(a, b)
-(byebug:1) @b{break gcd.rb:6}
-*** No source file named gcd.rb
-(byebug:1) @b{info line}
-Line 4 of "/home/rocky/ruby/gcd.rb"
-(byebug:1) @b{break /home/rocky/ruby/gcd.rb:6}
-Breakpoint 1 file /home/rocky/ruby/gcd.rb, line 6
-(byebug:1) @b{break ~/ruby/gcd.rb:10}  # tilde expansion also works
-Breakpoint 2 file /home/rocky/ruby/gcd.rb, line 10
-(byebug:1) @b{info file gcd.rb}
-File gcd.rb is not cached
-(byebug:1) @b{info file /home/rocky/ruby/gcd.rb}
-File /home/rocky/ruby/gcd.rb
-         19 lines
-@end example
-
-@item break @var{class}:@var{method}
-Set a breakpoint in class @var{class} method @var{method}. You can also use a
-period @code{.} instead of a colon @code{:}. Note that two colons @code{::} are
-not used. Also note a class @emph{must} be specified here. If the method you
-want to stop in is in the main class (i.e. the class that @code{self} belongs to
-at the start of the program), then use the name @code{Object}.
-
-@kindex catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
-@kindex cat @r{(@code{catch})}
-@item catch @ovar{exception} @r{[} on | 1 | off | 0 @r{]}
-Set catchpoint to an exception. Without an exception name show catchpoints.
-
-With an ``on'' or ``off'' parameter, turn handling the exception on or off. To
-delete all exceptions type ``catch off''.
-
-@cindex delete breakpoints
-@kindex delete @ovar{breakpoints}
-@kindex del @r{(@code{delete})}
-@item delete @ovar{breakpoints}
-Delete the breakpoints specified as arguments.
-
-If no argument is specified, delete all breakpoints (@code{byebug} asks for
-confirmation.  You can abbreviate this command as @code{del}).
-@kindex info breakpoints
-@cindex @code{$_} and @code{info breakpoints}
-@item info breakpoints @ovar{n}
-@itemx info break @ovar{n}
-Print a table of all breakpoints set and not deleted, with the following columns
-for each breakpoint:
-
-@table @emph
-@item Breakpoint Numbers (@samp{Num})
-@item Enabled or Disabled (@samp{Enb})
-Enabled breakpoints are marked with @samp{1}. @samp{0} marks breakpoints that
-are disabled (not enabled).
-@item File and Line (@samp{file:line})
-The filename and line number inside that file where of breakpoint in the script.
-The file and line are separated with a colon.
-@item Condition
-A condition (an arithmetic expression) which when true causes the breakpoint to
-take effect.
-@end table
-@noindent
-If a breakpoint is conditional, @code{info break} shows the condition on the
-line following the affected breakpoint; breakpoint commands, if any, are listed
-after that.
-
-@code{info break} with a breakpoint number @var{n} as argument lists only that
-breakpoint.
-
-Examples:
-@example
-(byebug:1) @b{info break}
-Breakpoints at following places:
-Num  Enb What
-1    y   gcd.rb:3
-2    y   gcb.rb:28 if n > 1
-(byebug:1) @b{info break 2}
-2    y   gcb.rb:28 if n > 1
-@end example
-@end table
-
-@node Disabling
-@subsection Disabling breakpoints (@samp{disable}, @samp{enable})
-
-Rather than deleting a breakpoint, you might prefer to @dfn{disable} it. This
-makes the breakpoint inoperative as if it had been deleted, but remembers the
-information on the breakpoint so that you can @dfn{enable} it again later.
-
-You disable and enable breakpoints and catchpoints with the @code{enable} and
-@code{disable} commands, optionally specifying one or more breakpoint numbers as
-arguments. Use @code{info break} to print a list of breakpoints and catchpoints
-if you do not know which numbers to use.
-
-A breakpoint or catchpoint can have any different states of enablement:
-
-@itemize @bullet
-@item
-Enabled.  The breakpoint stops your program.  A breakpoint set
-with the @code{break} command starts out in this state.
-@item
-Disabled.  The breakpoint has no effect on your program.
-@end itemize
-
-You can use the following commands to enable or disable breakpoints and
-catchpoints:
-
-@table @code
-@kindex disable breakpoints
-@item disable @var{breakpoints}
-Disable the specified breakpoints or all breakpoints, if none are listed. A
-disabled breakpoint has no effect but it is not forgotten. All options such as
-ignore-counts, conditions and commands are remembered in case the breakpoint is
-enabled again later. You may abbreviate @code{disable} as @code{dis}.
-
-@kindex enable breakpoints
-@item enable @var{breakpoints}
-Enable the specified breakpoints (or all defined breakpoints). They become
-effective once again in stopping your program.
-@end table
-
-Breakpoints that you set are initially enabled; subsequently, they become
-disabled or enabled only when you use one of the commands above. (The command
-@code{until} can set and delete a breakpoint of its own, but it does not change
-the state of your other breakpoints; see @ref{Resuming Execution}.)
-
-@node Conditions
-@subsection Break conditions (@samp{condition})
-@cindex conditional breakpoints
-@cindex breakpoint conditions
-
-The simplest sort of breakpoint breaks every time your script reaches a
-specified place. You can also specify a @dfn{condition} for a breakpoint. A
-condition is just a Ruby expression.
-
-Break conditions can be specified when a breakpoint is set, by using @samp{if}
-in the arguments to the @code{break} command. A breakpoint with a condition
-evaluates the expression each time your script reaches it, and your script stops
-only if the condition is @emph{true}. They can also be changed at any time with
-the @code{condition} command.
-
-@ifset FINISHED
-You can also use the @code{if} keyword with the @code{watch} command. The
-@code{catch} command does not recognize the @code{if} keyword; @code{condition}
-is the only way to impose a further condition on a catchpoint.
-@end ifset
-
-@table @code
-@kindex condition
-@item condition @var{bnum} @var{expression}
-Specify @var{expression} as the break condition for breakpoint @var{bnum}. After
-you set a condition, breakpoint @var{bnum} stops your program only if the value
-of @var{expression} is true (nonzero).
-
-@item condition @var{bnum}
-Remove the condition from breakpoint number @var{bnum}.  It becomes an ordinary
-unconditional breakpoint.
-@end table
-
-@ifset FINISHED
-When you use @code{condition}, @code{byebug} checks @var{expression} immediately
-for syntactic correctness, and to determine whether symbols in it have referents
-in the context of your breakpoint. If @var{expression} uses symbols not
-referenced in the context of the breakpoint, @code{byebug} prints an error
-message:
-
-@example
-No symbol "foo" in current context.
-@end example
-@end ifset
-
-@noindent
-The debugger does not actually evaluate @var{expression} at the time the
-@code{condition} command (or a command that sets a breakpoint with a condition,
-like @code{break if @dots{}}) is given, however.
-
-Examples;
-@example
-condition 1 x>5   # Stop on breakpoint 0 only if x>5 is true.
-condition 1       # Change that! Unconditionally stop on breakpoint 1.
-@end example
-
-@node Resuming Execution
-@subsection Resuming Execution (@samp{step}, @samp{next}, @samp{finish}, @samp{continue})
-
-A typical technique for using stepping is to set a breakpoint
-(@pxref{Breakpoints}) at the beginning of the function or the section of your
-script where a problem is believed to lie, run your script until it stops at
-that breakpoint, and then step through the suspect area, examining the variables
-that are interesting, until you see the problem happen.
-
-@cindex stepping
-@cindex continuing
-@cindex resuming execution
-@dfn{Continuing} means resuming program execution until your script completes
-normally. In contrast, @dfn{stepping} means executing just one more ``step'' of
-your script, where ``step'' may mean one line of source code.  Either when
-continuing or when stepping, your script may stop even sooner, due to a
-breakpoint or a signal.
-
-@menu
-* Step::     running the next statement (step)
-* Next::     running the next statement skipping over functions (next)
-* Finish::   running until the return of a function or ``source'' (finish)
-* Continue:: continuing execution (continue)
-@end menu
-
-@node Step
-@subsubsection Step (@samp{step})
-
-@table @code
-@kindex step @r{[}+@r{]} @ovar{count}
-@kindex s @r{(@code{step})}
-@item step @r{[}+-@r{]} @ovar{count}
-Continue running your program until the next logical stopping point and return
-control to @code{byebug}. This command is abbreviated @code{s}.
-
-Just like int the programming language Lisp, Ruby tends to be implemented in a
-highly expression-oriented manner. Therefore things that in other languages may
-appear to be a single statement are implemented in Ruby as several expressions.
-For example, in an ``if'' statement or loop statement a stop is made after the
-expression is evaluated but before the test on the expression is made.
-
-So it is common that some lines in the program will have several stopping points
-whereas in other debuggers of other languages there would be only one. Or you
-may have several statements listed on a single line.
-
-When stepping it is not uncommon to want to go to a different line on each step.
-If you want to make sure that on a step you go to a @emph{different} position,
-add a plus sign (@samp{+}).
-
-@emph{Note: step+ with a number count is not the same as issuing count step+
-commands. Instead it uses count-1 step commands followed by a step+ command. For
-example, @code{step+ 3} is the same as @code{step; step; step+}, not
-@code{step+; step+; step+}}
-
-If you find yourself generally wanting to use @code{step+} rather than
-@code{step}, you may want to consider using @code{set forcestep},
-(@pxref{Forcestep}).
-
-If you have @code{forcestep} set on but want to temporarily disable it for the
-next step command, append a minus, or @code{step-}.
-
-With a count, @code{step} will continue running as normal, but do so @var{count}
-times.  If a breakpoint is reached, or a signal not related to stepping occurs
-before @var{count} steps, stepping stops right away.
-@end table
-
-@node Next
-@subsubsection Next (@samp{next})
-@table @code
-@kindex next @r{[}+-@r{]} @ovar{count}
-@kindex n @r{(@code{next})}
-@item next @r{[}+@r{]} @ovar{count}
-This is similar to @code{step}, but function or method calls that appear within
-the line of code are executed without stopping. As with step, if you want to
-make sure that on a step you go to a @emph{different} position, add a plus sign
-(@samp{+}).  Similarly, appending a minus disables a @code{forcestep}
-temporarily, and an argument @var{count} is a repeat count, as for @code{step}.
-@end table
-
-@node Finish
-@subsubsection Finish (@samp{finish})
-@table @code
-@kindex finish @ovar{frame-number}
-@item finish @ovar{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@: @code{up},
-@code{down} or @code{frame}) has been performed. If a frame number is given we
-run until @var{frame} frames returns.
-
-If you want instead to terminate the program and byebug entirely, use
-@code{quit} (@pxref{Quitting byebug, ,Quitting byebug}).
-
-@end table
-
-@node Continue
-@subsubsection Continue (@samp{continue})
-@table @code
-@kindex continue @ovar{line-specification}
-@kindex c @r{(@code{continue})}
-@item continue @ovar{line-specification}
-@itemx c @ovar{line-specification}
-Resume program execution, at the address where your script last
-stopped; any breakpoints set at that address are bypassed.
-
-The optional argument @var{line-specification} allows you to specify a
-line number to set a one-time breakpoint which is deleted when that
-breakpoint is reached.
-
-Should the program stop before that breakpoint is reached, for
-example, perhaps another breakpoint is reached first, in
-a listing of the breakpoints you won't see this entry in the list of
-breakpoints.
-@end table
-
-@node byebug settings
-@section byebug settings (@samp{set args}, @samp{set autoeval}..)
-
-You can alter the way byebug interacts with you using @code{set}
-commands.
-
-The various parameters to @code{set} are given below. Each parameter
-name needs to to be only enough to make it unique. For example
-@code{set force} is a suitable abbreviation for @code{set forcestep}.
-The letter case is not important, so @code{set FORCE} or @code{set
-Force} are also suitable abbreviations.
-
-Many @code{set} commands are either ``on'' or ``off'', and you can
-indicate which way you want set by supplying the corresponding
-word. The number 1 can be used for ``on'' and 0 for ``off''. If none
-of these is given, we will assume ``on''. A deprecated way of turning
-something off is by prefacing it with ``no''.
-
-Each @code{set} command has a corresponding @code{show} command which
-allows you to see the current value.
-
-@menu
-* Args::              Annotation Level
-* Autoeval::          Evaluate unrecognized commands
-* Autolist::          Execute ``list'' command on every breakpoint
-* Autoirb::           Invoke IRB on every stop
-* Autoreload::        Reload source code when changed
-* Basename::          Report file basename only showing file names
-* Callstyle::         Show Report file basename only showing file names
-* Forcestep::         Make sure 'next/step' commands always move to a new line
-* Fullpath::          Display full file names in frames
-* History::           Generic command for showing command history parameters.
-* Keepframebindings:: Save frame binding on each call
-* Linetrace::         line execution tracing
-* Linetrace+::        line tracing style
-* Listsize::          Number of lines to try to show in a 'list' command
-* Post-mortem::       Whether post-mortem handling is in effect.
-* Trace::             Display stack trace when 'eval' raises exception
-* Width::             Number of characters byebug thinks are in a line
-@end menu
-
-@node Args
-@subsection Set/Show args
-
-@table @code
-@kindex set args @ovar{parameters}
-@item set args @ovar{parameters}
-Specify the arguments to be used if your program is rerun.  If
-@code{set args} has no arguments, @code{restart} executes your program
-with no arguments.  Once you have run your program with arguments,
-using @code{set args} before the next @code{restart} is the only way to run
-it again without arguments.
-
-@kindex show args
-@item show args
-Show the arguments to give your program when it is started.
-@end table
-
-@node Autoeval
-@subsection Set/Show auto-eval
-
-@table @code
-@kindex set autoeval @r{[} on | 1 | off | 0 @r{]}
-@item set autoeval @r{[} on | 1 | off | 0 @r{]}
-Specify that byebug input that isn't recognized as a command should
-be passed to Ruby for evaluation (using the current debugged program
-namespace). Note however that we @emph{first} check input to see if it
-is a byebug command and @emph{only} if it is not do we consider it
-as Ruby code. This means for example that if you have variable called
-@code{n} and you want to see its value, you could use @code{p n},
-because just entering @code{n} will be interpreted as byebug
-``next'' command.
-
-See also @ref{irb} and @ref{Autoirb}.
-
-When autoeval is set on, you'll get a different error message when you
-invalid commands are encountered. Here's a session fragment to show
-the difference
-@smallexample
-(byebug:1) @b{stepp}
-Unknown command
-(byebug:1) @b{set autoeval on}
-autoeval is on.
-(byebug:1) @b{stepp}
-NameError Exception: undefined local variable or method `stepp' for ...
-@end smallexample
-
-@kindex show autoeval
-@item show args
-Shows whether Ruby evaluation of byebug input should occur or not.
-@end table
-
-@node Autolist
-@subsection Execute ``list'' command on every breakpoint
-
-@node Autoirb
-@subsection Set/Show auto-irb
-
-@table @code
-@kindex set autoirb @r{[} on | 1 | off | 0 @r{]}
-@item set autoirb @r{[} on | 1 | off | 0 @r{]}
-
-When your program stops, normally you go into a byebug command loop
-looking for byebug commands. If instead you would like to directly
-go into an irb shell, set this on. See also @ref{Autoeval} or
-@ref{irb} if you tend to use byebug commands but still want Ruby
-evaluation occasionally.
-
-@kindex show autoirb
-@item show autoirb
-Shows whether byebug will go into irb on stop or not.
-@end table
-
-@node Autoreload
-@subsection Set/Show auto-reload
-@table @code
-@kindex set autoreload @r{[} on | 1 | off | 0 @r{]}
-Set this on if byebug should check to see if the source has
-changed since the last time it reread in the file if it has.
-@end table
-
-@node Basename
-@subsection Set/Show basename
-
-@table @code
-@kindex set basename @r{[} on | 1 | off | 0 @r{]}
-@item set basename @r{[} on | 1 | off | 0 @r{]}
-Source filenames are shown as the shorter ``basename''
-only. (Directory paths are omitted). This is useful in running the
-regression tests and may useful in showing byebug examples as in
-this text. You may also just want less verbose filename display.
-
-By default filenames are shown as with their full path.
-
-@kindex show basename
-@item show basename
-Shows the whether filename display shows just the file basename or not.
-@end table
-
-@node Callstyle
-@subsection Set/Show call style
-
-@table @code
-@ifset FINISHED
-@kindex set callstyle @r{[} short | long @r{]}
-@item set callstyle @r{[} short | long @r{]}
-@else
-@kindex set callstyle @r{[} short | long
-@item set callstyle @r{[} short | long
-@end ifset
-
-Sets how you want call parameters displayed
-
-@code{short} shows current method and parameter names.
-@code{long} shows current class, current method, parameter names and the class
-of each parameter as it currently exist. Note the type could have changed
-since the call was made.
-@end table
-
-@node Forcestep
-@subsection Set/Show Forces Different Line Step/Next
-
-@table @code
-@kindex set forcestep @r{[} on | 1 | off | 0 @r{]}
-@item set forcestep @r{[} on | 1 | off | 0 @r{]}
-
-Due to the interpretive, expression-oriented nature of the Ruby
-Language and implementation, each line often contains many possible
-stopping points, while in a byebug it is often desired to treat each
-line as an individual stepping unit.
-
-Setting forcestep on will cause each @code{step} or @code{next}
-command to stop at a different line number. See also @ref{Step} and
-@ref{Next}.
-
-@kindex show forcestep
-@item show forcestep
-Shows whether forcestep is in effect or not.
-@end table
-
-@node Fullpath
-@subsection Set/Show Frame full path
-
-@node History
-@subsection Command History Parameters
-@table @code
-@item show commands
-@kindex show commands
-Display the last ten commands in the command history.
-
-@item show commands @var{n}
-@kindex show commands @var{n}
-Print ten commands centered on command number @var{n}.
-
-@item show history filename
-@kindex show history filename
-Show the filename in which to record the command history
-(the list of previous commands of which a record is kept).
-
-@item set history save @r{[} on | 1 | off | 0 @r{]}
-@kindex set history save @r{[} on | 1 | off | 0 @r{]}
-Set whether to save the history on exit.
-
-@item show history save
-@kindex show history save
-Show saving of the history record on exit.
-
-@item set history size @var{number}
-@kindex set history size @var{number}
-Set the maximum number of commands to save in the history.
-
-@item show history size
-@kindex show history size
-Show the size of the command history, i.e. the number of previous
-commands to keep a record of.
-@end table
-
-@node Keepframebindings
-@subsection Save frame binding on each call
-
-@node Linetrace
-@subsection Set/Show Line tracing
-
-@table @code
-@kindex set linetrace @r{[} on | 1 | off | 0 @r{]}
-@item set linetrace @r{[} on | 1 | off | 0 @r{]}
-
-Setting linetrace on will cause lines to be shown before run.
-
-@kindex show linetrace
-@item show linetrace
-Shows whether line tracing is in effect or not.
-@end table
-
-@node Linetrace+
-@subsection Set/Show Line tracing style
-
-@table @code
-@kindex set linetrace_plus @r{[} on | 1 | off | 0 @r{]}
-@item set linetrace_plus @r{[} on | 1 | off | 0 @r{]}
-
-Setting linetrace_plus on will cause every trace line to be printed, even if
-it's a duplicate of the preceding trace line. Note however that this setting
-doesn't by itself turn on or off line tracing.
-
-@kindex show linetrace_plus
-@item show linetrace_plus
-Shows whether the line tracing style is to show all lines or remove duplicates
-linetrace lines when it is a repeat of the previous line.
-@end table
-
-@node Listsize
-@subsection Set/Show lines in a List command
-
-@table @code
-@kindex set listsize @var{number-of-lines}
-@item set listsize @var{number-of-lines}
-Set number of lines to try to show in a @code{list} command.
-@kindex show listsize
-@item show listsize
-Shows the list-size setting.
-@end table
-
-@node Post-mortem
-@subsection Show Post-mortem handling
-@table @code
-@kindex show post-mortem
-Shows wither post-mortem debugging is in effect. Right now we don't have the
-ability to change that state inside byebug.
-@end table
-
-@node Trace
-@subsection Display stack trace when 'eval' raises exception
-
-@node Width
-@subsection Set/Show Line width
-
-@table @code
-@kindex set width @var{column-width}
-@item set width @var{column-width}
-Set number of characters per line of byebug output. By default it is the number
-of columns in the current terminal.
-@kindex show width
-@item show width
-Shows the current width setting.
-@end table
-
-@node Program Information
-@section Program Information (@samp{info})
-
-This @code{info} command (abbreviated @code{i}) is for describing the state of
-your program.  For example, you can list the current parameters with
-@code{info args} or list the breakpoints you have set with
-@code{info breakpoints} or @code{info watchpoints}.  You can get a complete list
-of @code{info} sub-commands with @w{@code{help info}}.
-
-@table @code
-@kindex info args
-@item info args
-Method arguments of the current stack frame.
-
-@kindex info breakpoints
-@item info breakpoints
-Status of user-settable breakpoints
-
-@kindex info display
-@item info display
-All display expressions.
-
-@kindex info files
-@item info files
-Source files in the program.
-
-@kindex info file
-@item info file @var{filename} @ovar{all|basic|path|lines|mtime|sha1}
-Information about a specific file. Parameter @code{path} gives the full path
-name of the file. Parameter @code{lines} gives the number of lines in the file,
-@code{mtime} shows the modification time of the file (if available), @code{sha1}
-computes a SHA1 hash of the data in the file. @code{all} gives all of the above
-information and @code{basic} is equivalent to @code{path} and @code{lines}.
-
-@kindex info line
-@item info line
-Line number and file name of current position in source.
-
-@kindex info locals
-@item info locals
-Local variables of the current stack frame.
-
-@kindex info program
-@item info program
-Display information about the status of your program: whether it is running or
-not and why it stopped. If an unhandled exception occurred, the exception class
-and @code{to_s} method is called.
-
-@kindex info stack
-@item info stack
-Backtrace of the stack. An alias for @code{where}. @xref{Backtrace}.
-
-@kindex info variables
-@item info variables
-Local and instance variables.
-@end table
-
-@node Post-Mortem Debugging
-@chapter Post-Mortem Debugging
-@cindex post-mortem debugging
-
-It is also to possible enter byebug when you have an uncaught exception that is
-about to terminate our program. This is called @emph{post-mortem debugging}. In
-this state many byebug commands for examining variables and moving around the
-stack still work. However some commands, such as those implying a continuation
-of running code, no longer work.
-
-The most reliable way to set up post-mortem debugging is to use the
-@option{--post-mortem} option in invoking @code{byebug}. See @ref{byebug
-command-line options}. This traps/wraps at byebug ``load'' of your Ruby script.
- When this is done, your program is stopped after the exception takes place, but
-before the stack has been unraveled. (Alas, it would be nice to if one could
-allow resetting the exception and continuing...)
-
-If however you haven't invoked @code{byebug} at the outset, but instead call
-@code{byebug} from inside your program, to set up post-mortem debugging set the
-@code{post_mortem} key in @code{Byebug.start}. Here's an example:
-
-@smallexample
-    $ @b{cat t.rb }
-    require 'rubygems'
-    require 'byebug' ; Byebug.start(post_mortem: true)
-
-    def t1
-      raise 'test'
-    end
-    def t2
-      t1
-    end
-    t2
-
-    $ @b{ruby t.rb }
-    t.rb:8: raise 'test'
-    (byebug:post-mortem) @b{l=}
-    [3, 12] in t.rb
-       3
-       4  Byebug.start
-       5  Byebug.post_mortem
-       6
-       7  def t1
-    => 8    raise 'test'
-       9  end
-       10  def t2
-       11    t1
-       12  end
-    (byebug:post-mortem)
-@end smallexample
-
-Alternatively you can call @code{Byebug.post_mortem()} after byebug has
-been started. The @code{post_mortem()} method can be called in two
-ways. Called without a block, it installs a global @code{at_exit()} hook
-that intercepts exceptions not handled by your Ruby script. In
-contrast to using the @option{--post-mortem} option, when this hook
-occurs after the call stack has been rolled back. (I'm not sure if
-this in fact makes any difference operationally; I'm just stating it
-because that's how it works.)
-
-If you know that a particular block of code raises an exception you
-can enable post-mortem mode by wrapping this block inside a
-@code{Byebug.post_mortem} block
-
-@smallexample
-def offender
-  1/0
-end
-...
-require "ruby-gems"
-require "byebug"
-Byebug.post_mortem do
-  ...
-  offender
-  ...
-end
-@end smallexample
-
-Once inside byebug in post-mortem debugging, the prompt should
-be @code{(byebug:post-mortem)}.
-
-@node Byebug Module and Class
-@chapter The Byebug Module and Class
-
-@menu
-* Byebug Module::            byebug's Byebug module
-* Byebug Class::             Byebug class
-* Kernel routines::            Routines added to Kernel
-@end menu
-
-@node Byebug Module
-@section The Byebug Module
-
-@menu
-* Byebug.run::
-@ifset LATER
-* Byebug.post-mortem::
-@end ifset
-* Byebug.context::
-* Byebug.settings::
-@end menu
-
-@node Byebug.run
-@subsection @code{Byebug.start}, @code{Byebug.started?}, @code{Byebug.stop}, @code{Byebug.run_script}
-
-In order to provide better debugging information regarding the stack frame(s),
-byebug has to intercept each call, save some information and on return remove
-it. Therefore one has to issue a call to indicate byebug to start saving
-information and another call to stop. Of course, if you call byebug from the
-outset via @code{byebug} this is done for you.
-
-@table @code
-@item Byebug.start(@ovar{options}) @ovar{block}
-@vindex @code{Byebug.start(options)}
-@vindex @code{Byebug.start(block)}
-Turn on add additional instrumentation code to facilitate debugging. A
-system even table hook is installed and some variables are set up.
-
-This needs to be done before entering byebug; therefore a call
-to byebug issue a @code{Byebug.start} call if necessary.
-
-If called without a block, @code{Byebug.start} returns @code{true} if
-byebug was already started. But if you want to know if the
-byebug has already been started @code{Byebug.started?} can tell
-you.
-
-If a block is given, byebug is started and @code{yields} to
-block. When the block is finished executing, byebug stopped with
-the @code{Byebug.stop method}. You will probably want to put a call
-to @code{byebug} somwhere inside that block
-
-But if you want to completely stop byebug, you must call
-@code{Byebug.stop} as many times as you called Byebug.start
-method.
-
-The first time Byebug.start is called there is also some additional
-setup to make the @code{restart} command work. In particular, @code{$0} and
-@code{ARGV} are used to set internal byebug variables.
-
-Therefore you should make try to make sure that when
-@code{Byebug.start} is called neither of these variables has been
-modified. If instead you don't want this behavior you can pass an
-options has and set the @code{:init} key to @code{false}. That is
-@smallexample
-  Byebug.start(:init => false) # or Byebug.start(@{:init => false@})
-@end smallexample
-
-If you want post-mortem debugging, you can also supply
-@code{:post_mortem => true} in @code{Byebug.start}.
-
-@item Byebug.started?
-@vindex @code{Byebug.started?}
-Boolean. Return @code{true} if byebug has been started.
-
-@item Byebug.stop
-@vindex @code{Byebug.stop}
-Turn off instrumentation to allow debugging. Return @code{true} is returned
-if byebug is disabled, otherwise it returns @code{false}.
-@emph{Note that if you want to stop byebug, you must call Byebug.stop
-as many times as you called the @code{Byebug.start} method.}
-
-@item Byebug.run_script(@var{byebug-command-file}, out = handler.interface)
-@vindex @code{Byebug.run_script}
-Reads/runs the given file containing byebug commands. @code{.byebugrc} is run this way.
-
-@item Byebug.last_exception
-@vindex @code{Byebug.last_exception}
-If not @code{nil}, this contains @code{$!} from the last exception.
-
-@end table
-
-@node Byebug.context
-@subsection @code{Byebug.context}
-As mentioned previously, @code{Byebug.start} instruments additional
-information to be obtained about the current block/frame stack. Here
-we describe these additional @code{Byebug.context} methods.
-
-Were a frame position is indicated, it is optional. The top or current frame
-position (position zero) is used if none is given.
-
-@table @code
-@item Byebug.context.frame_args @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_args}
-If track_frame_args? is true, return information saved about call
-arguments (if any saved) for the given frame position.
-
-@item Byebug.context.frame_args_info @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_args_info}
-
-@item Byebug.context.frame_class @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_args_info}
-Return the class of the current frame stack.
-
-@item Byebug.context.frame_file @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_file}
-Return the filename of the location of the indicated frame position.
-
-@item Byebug.context.frame_id @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_id}
-Same as @code{Byebug.context.method}.
-
-@item Byebug.context.frame_line @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_line}
-Return the filename of the location of the indicated frame position.
-
-@item Byebug.context.frame_method @ovar{frame-position=0}
-@vindex @code{Byebug.context.frame_method}
-Symbol of the method name of the indicated frame position.
-
-@item Byebug.context.calced_stack_size
-@vindex @code{Byebug.context.calced_stack_size}
-Returns the stack size calculated by byebug. This is initialized when byebug is
-started and after that is kept up-to-date using the TracePoint API events.
-@end table
-
-@node Byebug.settings
-@subsection @code{Byebug.settings}
-@vindex @code{Byebug.settings}
-Symbols listed here are keys into the Array @code{Byebug.settings}.
-These can be set any time after the @code{byebug} is loaded. For example:
-@smallexample
-  require "byebug/byebug"
-  Byebug.settings[:autoeval] = true  # try eval on unknown byebug commands
-  Byebug.listsize = 20  # Show 20 lines in a list command
-@end smallexample
-
-@table @code
-@item :argv
-Array of String. @code{argv[0]} is the debugged program name and
-@code{argv[1..-1]} are the command arguments to it.
-@item :autoeval
-Boolean. True if auto autoeval on. @xref{Autoeval}.
-@item :autoirb
-Fixnum: 1 if on or 0 if off. @xref{Autoirb}.
-@item :autolist
-Fixnum: 1 if on or 0 if off.
-@item :basename
-Boolean. True if basename on. @xref{Basename}.
-@item :callstyle
-Symbol: @code{:short} or @code{:long}. @xref{Callstyle}.
-@item :testing
-Boolean. True if currently testing byebug.
-@item :forcestep
-Boolean. True if stepping should go to a line different from the last
-step. @xref{Forcestep}.
-@item :fullpath
-Boolean. @xref{Fullpath}.
-@item :listsize
-Fixnum. Number of lines to show in a @code{list} command. @xref{Listsize}.
-@item :autoreload
-Boolean. True if we should reread the source every time it changes. @xref{Autoreload}.
-@item :stack_on_error
-Boolean. True if we should produce a stack trace on eval errors. @xref{Trace}.
-@item :width
-Fixnum. Number of characters byebug thinks are in a line. @xref{Width}.
-@end table
-
-@node Byebug Class
-@section The @code{Byebug} Class
-@menu
-* Byebug.Breakpoint::  Byebug::Breakpoint
-* Byebug.Context::     Byebug::Context
-* Byebug.Command::     Byebug::Command
-@end menu
-
-@table @code
-@item add_breakpoint(file, line, expr)
-@vindex @code{Byebug.add_breakpoint}
-Adds a breakpoint in file @var{file}, at line @var{line}. If @var{expr} is not
-nil, it is evaluated and a breakpoint takes effect at the indicated position
-when that expression is true. You should verify that @var{expr} is syntactically
-valid or a @code{SyntaxError} exception, and unless your code handles this the
-debugged program may terminate.
-
-@item remove_breakpoint(bpnum)
-@vindex @code{Byebug.remove_breakpoint}
-When a breakpoint is added, it is assigned a number as a way to uniquely
-identify it. (There can be more than one breakpoint on a given line.) To remove
-a breakpoint, use @code{remove_breakpoint} with breakpoint number @var{bpnum}.
-
-@item breakpoints
-@vindex @code{Byebug.breakpoints}
-Return a list of the breakpoints that have been added but not removed.
-@end table
-
-@node Byebug.Breakpoint
-@subsection The @code{Byebug::Breakpoint} Class
-Breakpoints are objects in the @code{Byebug::Breakpoint} class.
-@table @code
-@item enabled?
-@vindex @code{Byebug::Breakpoints.enabled?}
-Returns whether breakpoint is enabled or not.
-
-@item enabled=
-@vindex @code{Byebug::Breakpoints.enabled=}
-Sets a breakpoint as enabled or not.
-
-@item expr
-@vindex @code{Byebug::Breakpoints.expr}
-Returns an expression which has to be true at the point where the breakpoint is
-set before we stop.
-
-@item expr=
-@vindex @code{Byebug::Breakpoints.expr=}
-Sets an expression which has to be true at the point where the breakpoint is set
-before we stop.
-
-@item hit_condition
-@item hit_condition=
-@vindex @code{Byebug::Breakpoints.condition}
-@vindex @code{Byebug::Breakpoints.condition=}
-
-@item hit_count
-@vindex @code{Byebug::Breakpoints.hit_count}
-Returns the hit count of the breakpoint.
-
-@item hit_value
-@vindex @code{Byebug::Breakpoints.hit_value}
-Returns the hit value of the breakpoint.
-
-@item hit_value=
-@vindex @code{Byebug::Breakpoints.hit_value=}
-Sets the hit value of the breakpoint.
-
-@item id
-@cindex @code{Byebug::Breakpoints.id}
-A numeric name for the breakpoint which is used in listing breakpoints and
-removing, enabling or disabling the breakpoint.
-
-@item pos
-@vindex @code{Byebug::Breakpoints.pos=}
-Returns the line number of this breakpoint.
-@item pos=
-@vindex @code{Byebug::Breakpoints.pos=}
-Sets the line number of this breakpoint.
-
-@item source
-@vindex @code{Byebug::Breakpoints.source}
-Returns the file name in which the breakpoint occurs.
-
-@item source=
-@vindex @code{Byebug::Breakpoints.source=}
-Sets the file name in which the breakpoint occurs.
-@end table
-
-@node Byebug.Context
-@subsection The @code{Byebug::Context} Class
-Callbacks in @code{Byebug:Context} get called when a stopping point or an event
-is reached. It has information about the suspended program which enable byebug
-to inspect the frame stack, evaluate variables from the perspective of the
-debugged program, and contains information about the place the debugged program
-is stopped.
-
-@table @code
-@item at_line(@var{file}, @var{line})
-@vindex Byebug::Context::at_line(@var{file}, @var{line})
-This routine is called when byebug encounters a ``line'' event for which it has
-been indicated we want to stop at, such as by hitting a breakpoint or by some
-sort of stepping.
-
-@item at_return(@var{file}, @var{line})
-@vindex Byebug::Context::at_return(@var{file}, @var{line})
-This routine is called when byebug encounters a ``return'' event for which it
-has been indicated we want to stop at, such as by hitting a @code{finish}
-statement.
-
-@item debug_load(@var{file}, @var{stop-initially})
-@vindex Byebug::Context::debug_load(@var{file}, @var{stop-initially})
-This method should be used to debug a file. If the file terminates normally,
-@code{nil} is returned. If not a backtrace is returned.
-
-The @var{stop-initially} parameter indicates whether the program should stop
-after loading. If an explicit call to byebug is in the debugged program, you may
-want to set this @code{false}.
-@end table
-
-@node Byebug.Command
-@subsection The @code{Byebug::Command} Class
-Each command you run is in fact its own class. Should you want to extend byebug,
-it's pretty easy to do since after all byebug is Ruby.
-
-Each @code{Byebug#Command} class should have a @code{regexp} method. This method
-returns regular expression for command-line strings that match your command.
-It's up to you to make sure this regular expression doesn't conflict with
-another one. If it does, it's undefined which one will get matched and run.
-
-In addition the instance needs these methods:
-@table @code
-@item execute
-Code which gets run when you type a command (string) that matches the command's
-regular expression.
-@item description
-A string which gets displayed when folks ask for help on that command.
-@item names
-Names and aliases of the command as an array of strings.
-@end table
-
-Here's a small example of a new command:
-@smallexample
-module Byebug
-  class MyCommand < Command
-    def regexp
-      /^\s*me$/ # Regexp that will match your command
-    end
-
-    def execute
-      puts "hi" # What you want to happen when your command runs
-    end
-    class << self
-      def names
-        %w(me)
-      end
-      def description
-        %@{This does whatever it is I want to do@}
-     end
-  end
-end
-@end smallexample
-
-Now here's an example of how you can load/use it:
-@smallexample
-  require 'rubygems'
-  require 'byebug'
-  require '/tmp/mycmd.rb' # or wherever
-  Byebug.start
-  x=1
-  byebug
-  y=2
-@end smallexample
-
-And now an example of invoking it:
-@smallexample
-ruby /tmp/testit.rb:
-/tmp/testit.rb:7
-y=2
-(byebug:1) help
-byebug help v1.1.0
-Type 'help <command-name>' for help on a specific command
-Available commands:
-backtrace delete  enable help method putl    set    trace
-break     disable eval   info next   quit    show   undisplay
-catch     display exit   irb  p      reload  source up
-condition down    finish list pp     restart step   var
-continue edit     frame  me   ps     save    where
-                  ^^ This is you
-
-(byebug:1) help me
-This does whatever it is I want to do
-(byebug:1) me
-hi
-(byebug:1)
-@end smallexample
-
-@node Kernel routines
-@section Additions to @code{Kernel}
-
-@table @code
-
-@item byebug @ovar{steps=1}
-@vindex @code{Kernel::byebug}
-Enters byebug after @var{steps} line-event steps. Before entering byebug, the
-startup script is read.
-
-Setting @var{steps} to 0 will cause a break in byebug subroutine and not wait
-for any line event to occur. This could be useful you want to stop right after
-the last statement in some scope.
-
-Consider this example:
-@smallexample
-$ cat scope-test.rb
-require 'byebug' ; Byebug.start
-1.times do
-  a = 1
-  byebug   # implied steps=1
-end
-y = 1
-
-$ ruby scope-test.rb
-y = 1
-(byebug:1) p a
-NameError Exception: undefined local variable or method `a' for main:Object
-(byebug:1)
-@end smallexample
-
-Byebug will stop at the line event which follows @samp{a=1}. This is outside the
-@code{do} block scope where @var{a} is defined. If instead you want to stop
-before leaving the @code{do} loop it is possible to stop right inside
-@code{byebug}; call byebug with 0 zero parameter:
-
-@smallexample
-$ cat scope-test.rb
-require 'byebug' ; Byebug.start
-1.times do
-   a = 1
-   byebug(0)
-end
-y = 1
-
-$ ruby scope-test.rb
-../lib/byebug.rb:386
-Byebug.context.after_frame = 0
-(byebug:1) where
---> #0 Kernel.byebug(steps#Fixnum) at ../lib/byebug-base.rb:386
-    #1 at scope-test.rb:4
-    #2 at scope-test.rb:2
-(byebug:1) up
-#1 at scope-test.rb:4
-(byebug:1) p a
-1
-(byebug:1)
-@end smallexample
-
-As seen above you will have to position the frame up one to be back in your
-debugged program rather than in byebug.
-
-@item breakpoint @ovar{steps=1}
-@vindex @code{Kernel::breakpoint}
-An alias for byebug.
-
-@item binding_n @ovar{n=0}
-@vindex @code{Kernel::binding_n}
-Returns a @samp{binding()} for the @var{n}-th call frame. Note however that you
-need to first call @samp{Byebug.start} before issuing this call.
-
-@end table
-
-@node Contributing
-@appendix Guidelines for contributing
-
-@menu
-* Testing Byebug:: Running Regression Tests
-@end menu
-
-@node Testing Byebug
-@section Testing Byebug
-
-We've put together some basic tests to make sure byebug is doing
-what we think it should do. To run these (from @code{trunk}):
-
-@smallexample
-  rake test
-@end smallexample
-
-If you didn't build byebug shared library and skipped step 2,
-don't worry @code{rake test} will do step 2 for you. You should see a
-line that ends something like:
-
-@smallexample
-Finished tests in 2.358177s, 155.2046 tests/s, 172.1669 assertions/s.
-
-366 tests, 406 assertions, 0 failures, 0 errors, 17 skips
-@end smallexample
-
-The number of seconds, tests, and assertions may be different from the above.
-However you @emph{should} see exactly ``0 failures, 0 errors.''
-
-@node Class Module Method Index
-@unnumbered Class, Module and Method Index
-@printindex vr
-
-@node Command Index
-@unnumbered Command Index
-@printindex ky
-
-@node General Index
-@unnumbered General Index
-@printindex cp
-
-@tex
-% I think something like @colophon should be in texinfo.  In the meantime:
-\long\def\colophon{\hbox to0pt{}\vfill
-\centerline{The body of this manual is set in}
-\centerline{\fontname\tenrm,}
-\centerline{with headings in {\bf\fontname\tenbf}}
-\centerline{and examples in {\tt\fontname\tentt}.}
-\centerline{{\it\fontname\tenit\/},}
-\centerline{{\bf\fontname\tenbf}, and}
-\centerline{{\sl\fontname\tensl\/}}
-\centerline{are used for emphasis.}\vfill}
-\page\colophon
-% Blame: doc@cygnus.com, 1991.
-@end tex
-
-@bye