byebug 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c587e41bb9bea57e9e9cc27cec5d670fb7d66f81
-  data.tar.gz: b565d9e7848ef7772edfcc9521f4e11accc50ef6
+  metadata.gz: 889f4fe2a663bd2b3f7bf9d03f6b82971cfcb3ad
+  data.tar.gz: 1d8c1667bb48110e5cca851b5f50a799fa0b54dc
 SHA512:
-  metadata.gz: e8cc31ecfc37cfeac40245ef53ca93eb88f6902821fb698374dd48dbe21c1bb97a203e565c0021cc97aca5b3b67fdc1a18b424cefa945f2dd0dfd75dfb08f0f6
-  data.tar.gz: 8ec279d81317f14ac91289c7a11776b931fe6931069c5acfe39cd422f2cce994b3940abb5548dda6493a3a58fc8a7c2d7f52ad43cb971b7fcda4ad27192c2344
+  metadata.gz: 6f268a0212666405a1f80188575158ad64d19853e11950bc50decf2a36b81eecca3565513e068bb004a391038354a0f016226e561e12a4988e213993a773345e
+  data.tar.gz: 1cf89b9b021e749a06cbe2141146b632846d7cd7d1f21f584870967fb85f8e278195050829e16380cbc6bc1d4ab92bc79c62966872275819752b113ccd89ef30

data/CHANGELOG.md

@@ -1,9 +1,16 @@
+## 1.2.0
+
+* Added 'pry' command.
+* Ctrl+C during command line editing is handled and works like pry/irb
+
+
 ## 1.1.1
 
 * Better help system
 * Code cleanup
 * First version compatible with pry-byebug
 
+
 ## 1.1.0
 
 * Post mortem support

data/GUIDE.md

@@ -0,0 +1,231 @@
+## Second Sample Session: Delving Deeper
+
+In this section we'll introduce breakpoints, the call stack and restarting.
+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.
+
+```
+$ byebug hanoi.rb
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    1: # Solves the classic Towers of Hanoi puzzle.
+=>  2: def hanoi(n,a,b,c)
+    3:   if n-1 > 0
+    4:     hanoi(n-1, a, c, b)
+    5:   end
+    6:   puts "Move disk %s to %s" % [a, b]
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+(byebug)
+```
+
+Recall in the first section iwe said that before the `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 `def hanoi`.
+
+```
+(byebug) private_methods
+[:public, :private, :include, :using, :define_method, :default_src_encoding, ...
+```
+
+`private_methods` is not a byebug command but a Ruby feature. By default, when
+byebug doesn't understand a command, it will evaluate it as if it was a Ruby
+command. If you don't want this behaviour, you can use `set autoeval off` or
+even drop it in your `.byebugrc` file if you want that behaviour permanently.
+The output of `private_methods`, thought, is unwieldy for our porpuse: check
+whether `hanoi` method is in the list. Fortunately, byebug has nice formatting
+features: we can sort the output and put it into columns list using the print
+command `ps`.
+
+```
+(byebug) ps private_methods
+Array             debug_program         open                        sprintf    
+Complex           default_src_encoding  p                           srand      
+DelegateClass     define_method         pp                          syscall    
+Digest            eval                  print                       system     
+Float             exec                  printf                      test       
+Hash              exit                  private                     throw      
+Integer           exit!                 proc                        trace_var  
+Pathname          fail                  process_options             trap       
+Rational          fork                  public                      untrace_var
+String            format                putc                        using      
+__callee__        gem                   puts                        warn       
+__dir__           gem_original_require  raise                       whence_file
+__method__        gets                  rand                      
+`                 global_variables      readline                  
+abort             include               readlines                 
+at_exit           initialize            require                   
+autoload          initialize_clone      require_relative          
+autoload?         initialize_copy       respond_to_missing?       
+binding           initialize_dup        select                    
+block_given?      iterator?             set_trace_func            
+caller            lambda                singleton_method_added    
+caller_locations  load                  singleton_method_removed  
+catch             local_variables       singleton_method_undefined
+dbg_print         loop                  sleep                     
+dbg_puts          method_missing        spawn                     
+(byebug)
+```
+
+Now let's see what happens after stepping:
+
+```
+(byebug) private_methods.member?(:hanoi)
+false
+(byebug:1) step
+[7, 16] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+   11:
+=> 12: i_args=ARGV.length
+   13: if i_args > 1
+   14:   puts "*** Need number of disks or no parameter"
+   15:   exit 1
+   16: end
+(byebug) private_methods.member?(:hanoi)
+true
+(byebug)
+```
+
+Okay, lets go on and talk about program arguments.
+
+```
+(byebug) ARGV
+[]
+```
+
+Ooops. We forgot to specify any parameters to this program. Let's try again. We can
+use the `restart` command here.
+
+```
+(byebug) restart 3
+Re exec'ing:
+  /home/davidr/.rvm/gems/ruby-2.0.0-p195@byebug/gems/byebug-1.1.1/bin/byebug /home/davidr/Proyectos/byebug/old_doc/hanoi.rb 3
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    1: # Solves the classic Towers of Hanoi puzzle.
+=>  2: def hanoi(n,a,b,c)
+    3:   if n-1 > 0
+    4:     hanoi(n-1, a, c, b)
+    5:   end
+    6:   puts "Move disk %s to %s" % [a, b]
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+(byebug) break 4
+Created breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+(byebug) continue
+Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    1: # Solves the classic Towers of Hanoi puzzle.
+    2: def hanoi(n,a,b,c)
+=>  3:   if n-1 > 0
+    4:     hanoi(n-1, a, c, b)
+    5:   end
+    6:   puts "Move disk %s to %s" % [a, b]
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+(byebug) display n
+1: n = 3
+(byebug) display a
+2: a = a
+(byebug) undisplay 2
+(byebug) display a.inspect
+3: a.inspect = :a
+(byebug) display b.inspect
+4: b.inspect = :b
+(byebug) continue
+Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    1: # Solves the classic Towers of Hanoi puzzle.
+    2: def hanoi(n,a,b,c)
+=>  3:   if n-1 > 0
+    4:     hanoi(n-1, a, c, b)
+    5:   end
+    6:   puts "Move disk %s to %s" % [a, b]
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+1: n = 2
+3: a.inspect = :a
+4: b.inspect = :c
+(byebug) c
+Stopped by breakpoint 1 at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/hanoi.rb
+    1: # Solves the classic Towers of Hanoi puzzle.
+    2: def hanoi(n,a,b,c)
+=>  3:   if n-1 > 0
+    4:     hanoi(n-1, a, c, b)
+    5:   end
+    6:   puts "Move disk %s to %s" % [a, b]
+    7:   if n-1 > 0
+    8:     hanoi(n-1, c, b, a)
+    9:   end
+   10: end
+1: n = 1
+3: a.inspect = :a
+4: b.inspect = :b
+(byebug) where
+--> #0  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol)
+      at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:3
+    #1  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol)
+      at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:4
+    #2  Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol)
+      at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:4
+    #3  <main> at /home/davidr/Proyectos/byebug/old_doc/hanoi.rb:34
+(byebug)
+```
+
+In the above we added new commands: `break` (see [breakpoints]()), which
+indicates to stop just before that line of code is run, and `continue`, which
+resumes execution.  Notice the difference between `display a` and 
+`display a.inspect`. An implied string conversion is performed on the expression
+after it is evaluated. To remove a display expression `undisplay` is used. If we
+give a display number, just that display expression is removed.
+
+We also used a new command `where`(see [Backtrace]()) to show the call stack. In
+the above situation, starting from the bottom line we see we called the `hanoi`
+method from line 34 of the file `hanoi.rb` and the `hanoi` method called itself
+two more times at line 4.
+
+In the call stack we show a _current frame_ mark, the frame number, the method
+being called, the names of the parameters, the types those parameters
+_currently_ have and the file-line position. Remember it's possible that when
+the program was called the parameters had different types, since the types of
+variables can change dynamically. You can alter the style of what to show in the
+trace (see [Callstyle]()).
+
+Now let's more around the callstack.
+
+```
+(byebug) undisplay
+Clear all expressions? (y/n) y
+(byebug:1) i_args
+NameError Exception: undefined local variable or method `i_args' for main:Object
+(byebug:1) frame -1
+#3 at hanoi.rb:34
+(byebug:1) i_args
+1
+(byebug:1) p n
+3
+(byebug:1) down 2
+#1 Object.hanoi(n#Fixnum, a#Symbol, b#Symbol, c#Symbol) at hanoi.rb:4
+(byebug:1) p n
+2
+```
+
+Notice in the above to get the value of variable `n` we had to use a print
+command like `p n`. If we entered just `n`, that would be taken to mean byebug
+command ``next''. In the current scope, variable `i_args` is not defined.
+However I can change to the top-most frame by using the `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 `up 3`. Note that in the outside
+frame #3, the value of `i_args` can be shown. Also note that the value of
+variable `n` is different.

data/README.md

@@ -1,12 +1,33 @@
 # Byebug [![Gem Version](https://badge.fury.io/rb/byebug.png)](http://badge.fury.io/rb/byebug) [![Build Status](https://secure.travis-ci.org/deivid-rodriguez/byebug.png)](http://travis-ci.org/deivid-rodriguez/byebug) [![Code Climate](https://codeclimate.com/github/deivid-rodriguez/byebug.png)](https://codeclimate.com/github/deivid-rodriguez/byebug) [![Dependency Status](https://gemnasium.com/deivid-rodriguez/byebug.png)](https://gemnasium.com/deivid-rodriguez/byebug)
 
-A Ruby 2.0 debugger.
+_Debugging in Ruby 2.0_
+
+Byebug is a simple to use, feature rich debugger for Ruby 2.0. It uses the new
+TracePoint API, so it doesn't depend on internal core sources. It's developed as
+a C extension, so it's fast. And it has a full test suite so it's (I hope)
+reliable.
+
+It allows you to see what is going on _inside_ a Ruby program while it executes
+and can do four main kinds of things (plus other things in support of these) to
+help you catch bugs in the act:
+
+* Start your program or attach to it, specifying anything that might affect its
+behavior.
+* Make your program stop on specified conditions.
+* Examine what has happened when your program has stopped.
+* Change things in your program, so you can experiment with correcting the
+effects of one bug and go on to learn about another.
 
 
 ## Install
 
-Just type `gem install byebug` or drop `gem 'byebug'` in your Gemfile and run
-`bundle install`.
+Just drop
+
+    gem 'byebug'
+
+in your Gemfile and run
+
+    bundle install
 
 
 ## Usage
@@ -16,14 +37,181 @@ stop there. If you are debugging rails, start the server in normal mode with
 `rails server` and once the execution get to your `byebug` command you will get
 a debugging terminal.
 
+## Getting Started
+
+A handful of commands are enough to get started using `byebug`. The following
+session illustrates these commands. Below is Ruby code to compute a triangle
+number of a given length (there are shorter ways to do it, of course).
+
+```
+$ byebug triangle.rb
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+   1:  # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
+=> 2:  def triangle(n)
+   3:    tri = 0
+   4:    0.upto(n) do |i|
+   5:      tri += i
+   6:    end
+   7:    tri
+   8:  end
+   9:
+   10: t = triangle(3)
+(byebug)
+```
+
+We are currently stopped before the first executable line of the program: line 2
+of `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 2 is
+executed.
+
+Byebug's prompt is `(byebug)`. If the program has died and you are in
+post-mortem debugging, `(byebug:post-mortem)` is used instead. If the program
+has terminated normally, the string this position will be `(byebug:ctrl)`. The
+commands 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 is marked with `=>`, so the range
+byebug would like to show is [-3..6]. 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.
+
+```
+(byebug) step
+[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+   2:  def triangle(n)
+   3:    tri = 0
+   4:    0.upto(n) do |i|
+   5:      tri += i
+   6:    end
+   7:    tri
+   8:  end
+   9:
+=> 10: t = triangle(3)
+   11: puts t
+(byebug) <RET> # hit enter
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+   1:  # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
+   2:  def triangle(n)
+=> 3:    tri = 0
+   4:    0.upto(n) do |i|
+   5:      tri += i
+   6:    end
+   7:    tri
+   8:  end
+   9:
+   10: t = triangle(3)
+(byebug) p tri
+nil
+(byebug) step
+[1, 10] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+   1:  # Compute the n'th triangle number: triangle(n) == (n*(n+1))/2
+   2:  def triangle(n)
+   3:    tri = 0
+=> 4:    0.upto(n) do |i|
+   5:      tri += i
+   6:    end
+   7:    tri
+   8:  end
+   9:
+   10: t = triangle(3)
+(byebug) p tri
+0
+```
+
+The first `step` command runs the script one executable unit. The second command
+we entered was just hitting the return key; `byebug` remembers the last command
+you entered was `step` and it runs it again.
+
+One way to print the values of variables is `p` (there are other ways). When we
+look at the value of `tri` the first time, we see it is `nil`. Again we are
+stopped _before_ the assignment on line 3, and this variable hasn't been set
+previously. However after issuing another `step` command we see that the value
+is 0 as expected. If every time we stop we want to see the value of `tri` to see
+how things are going, there is a better way by setting a display expression:
+
+```
+(byebug) display tri
+1: tri = 0
+```
+
+Now let us run the program until we return from the function. We'll want to see
+which lines get run, so we turn on _line tracing_. If we don't want whole paths
+to be displayed when tracing, we can turn on _basename_.
+
+```
+(byebug) display i
+2: i =
+(byebug) set linetrace on
+line tracing is on.
+(byebug) set basename on
+basename is on.
+(byebug) finish
+Tracing: triangle.rb:5 tri += i
+1: tri = 0
+2: i = 0
+Tracing: triangle.rb:5 tri += i
+1: tri = 0
+2: i = 1
+Tracing: triangle.rb:5 tri += i
+1: tri = 1
+2: i = 2
+Tracing: triangle.rb:5 tri += i
+1: tri = 3
+2: i = 3
+Tracing: triangle.rb:7 tri
+1: tri = 6
+2: i =
+Tracing: triangle.rb:11 puts t
+1: tri =
+2: i =
+[2, 11] in /home/davidr/Proyectos/byebug/old_doc/triangle.rb
+   2:  def triangle(n)
+   3:    tri = 0
+   4:    0.upto(n) do |i|
+   5:      tri += i
+   6:    end
+   7:    tri
+   8:  end
+   9:
+   10: t = triangle(3)
+=> 11: puts t
+1: tri =
+2: i =
+(byebug) quit
+Really quit? (y/n) y
+```
+
+So far, so good. As you can see from the above to get out of `byebug`, one
+can issue a `quit` command (`q` and `exit` are just as good). If you want to
+quit without being prompted, suffix the command with an exclamation mark, e.g.,
+`q!`.
+
+### The rest of the tutorial is available
+[here](https://github.com/deivid-rodriguez/byebug/blob/master/GUIDE.md)
 
 ## Configuration
 
 You can automatically load some configurations at startup by dropping them in
-the startup file `.byebugrc`, for example, `set listsize 20`. If you are coming
-from [debugger](https://github.com/cldwalker/debugger), notice however that you
-no longer need `set autolist`, `set autoreload` and `set autoeval` because they
-are default options in byebug.
+the startup file `.byebugrc`. For example, you can change the number of lines
+listed whenever byebug stops like this:
+
+    set listsize 20
+
+If you are coming from [debugger](https://github.com/cldwalker/debugger), notice
+however that you no longer need
+
+    set autoreload
+
+because it is a default option in byebug.
+
+
+## Related projects
+
+* [pry-byebug](https://github.com/deivid-rodriguez/pry-byebug) adds `next`,
+  `step`, `finish`, `continue` and `break` commands to pry using byebug.
 
 
 ## Credits