byebug 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 889f4fe2a663bd2b3f7bf9d03f6b82971cfcb3ad
-  data.tar.gz: 1d8c1667bb48110e5cca851b5f50a799fa0b54dc
+  metadata.gz: f2ab6f03625dc6bba2088e27bff9ec5f6c335b57
+  data.tar.gz: 48cca8a66cb638c91a26728a334613c33359236b
 SHA512:
-  metadata.gz: 6f268a0212666405a1f80188575158ad64d19853e11950bc50decf2a36b81eecca3565513e068bb004a391038354a0f016226e561e12a4988e213993a773345e
-  data.tar.gz: 1cf89b9b021e749a06cbe2141146b632846d7cd7d1f21f584870967fb85f8e278195050829e16380cbc6bc1d4ab92bc79c62966872275819752b113ccd89ef30
+  metadata.gz: 0a7c63ad6c37d3d23f13aa5db25db6dec3bed363ece29fc40402d3fa852ab2255183bb3d705c394d4a6c8a62a81f88e45e8bab5786dc06aff92eea02b9309112
+  data.tar.gz: 5274f6aa1ab234bd028ae07943cdbfa0bfa9f02a82e5925566a55e6f6a383fbabfeb6cbc9da64efb56b3098fbeb4320ba207485ccf4ed2aa812efe98c35bc1c7

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.3.0
+
+* Support colon-delimited include paths in command-line front-end (@ender672)
+
+
 ## 1.2.0
 
 * Added 'pry' command.

data/GUIDE.md

@@ -190,7 +190,7 @@ resumes execution.  Notice the difference between `display a` and
 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
+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.
@@ -200,9 +200,9 @@ 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]()).
+trace (see [callstyle]()).
 
-Now let's more around the callstack.
+Now let's move around the callstack.
 
 ```
 (byebug) undisplay
@@ -223,9 +223,215 @@ NameError Exception: undefined local variable or method `i_args' for main:Object
 
 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.
+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.
+
+
+## Unit Testing Session
+
+In the previous sessions we've been calling byebug right at the outset, but this
+is probably not the mode of operation you will use the most. There are a number
+of situations where calling byebug at the outset is impractical for a couple of
+reasons:
+
+* Byebug just doesn't work when run at the outset. Any debugging changes the
+behavior or the program in slight and subtle ways, and sometimes this can hinder
+finding bugs.
+* 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.
+
+In this section we'll show how to enter the code in the middle of your program,
+while delving more into byebug's operation. 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 `triangle` code from the first session and write a
+unit test for that. In a sense we did write a tiny test for the program which
+was basically the last line where we printed the value of `triangle(3)`. This
+test however wasn't automated: the expectation 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 `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. _NOTE: `byebug` resets `$0` to try to make things like this work._
+
+```
+if __FILE__ == $0
+  t = triangle(3)
+  puts t
+end
+```
+
+Okay, we're now ready to write our unit test. We'll use `test/unit` which comes
+with the standard Ruby distribution.  Here's the test code; it should be in the
+same directory as `triangle.rb`.
+
+```ruby
+require 'test/unit'
+require_relative 'triangle.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
+```
+
+Let's say we want to stop before the first statement in our test method, we'll
+add the following:
+
+```ruby
+...
+def test_basic
+  require 'byebug'
+  byebug
+  solutions = []
+...
+```
+
+Now we run the program..
+```
+$ ruby test-triangle.rb
+Run options:
+
+# Running tests:
+
+[1/1] TestTri#test_basic[5, 14] in test-triangle.rb
+    5: 
+    6: class TestTri < Test::Unit::TestCase
+    7:   def test_basic
+    8:     require 'byebug'
+    9:     byebug
+=> 10:     solutions = []
+   11:     0.upto(5) do |i|
+   12:       solutions << triangle(i)
+   13:     end
+   14:     assert_equal([0, 1, 3, 6, 10, 15], solutions,
+(byebug)
+```
+
+and we see that we are stopped at line 10 just before the initialization of the
+list `solutions`.
+
+Now let's see where we are...
+```
+(byebug) where
+--> #0  TestTri.test_basic at test-tri2.rb:10
+Warning: saved frames may be incomplete; compare with caller(0)
+(byebug)
+```
+
+Something seems wrong here; `TestTri.test_basic` indicates that we are in class
+`TestTri` in method `test_basic`. However we don't see the call to this like we
+did in the last example when we used the `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 `where`.
+
+If we want call stack information, we have to turn call-stack tracking on
+_beforehand_. This is done by adding `Byebug.start`.
+
+Here's what our test program looks like after we modify it to start tracking
+calls from the outset
+
+```ruby
+require 'test/unit'
+require_relative 'triangle.rb'
+require 'byebug'
+Byebug.start
+
+class TestTri < Test::Unit::TestCase
+  def test_basic
+    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
+```
+
+Now when we run this:
+```
+$ ruby test-triangle.rb
+Run options:
+
+# Running tests:
+
+[1/1] TestTri#test_basic[5, 14] in test-triangle.rb
+    5: 
+    6: class TestTri < Test::Unit::TestCase
+    7:   def test_basic
+    8:     require 'byebug'
+    9:     byebug
+=> 10:     solutions = []
+   11:     0.upto(5) do |i|
+   12:       solutions << triangle(i)
+   13:     end
+   14:     assert_equal([0, 1, 3, 6, 10, 15], solutions,
+(byebug) where
+--> #0  TestTri.test_basic at test-triangle.rb:10
+    #1  MiniTest::Unit::TestCase.run_test(name#String)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:858
+    #2  MiniTest::Unit::TestCase.run(runner#Test::Unit::Runner)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1301
+    #3  Test::Unit::TestCase.run(runner#Test::Unit::Runner)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit/testcase.rb:17
+    #4  MiniTest::Unit._run_suite(suite#Class, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:919
+    #5  Array.map(suite#Class, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:912
+    #6  MiniTest::Unit._run_suite(suite#Class, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:912
+    #7  Test::Unit::Runner._run_suites(suites#Array, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:657
+    #8  Array.each(suites#Array, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:655
+    #9  Test::Unit::Runner._run_suites(suites#Array, type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:655
+    #10 MiniTest::Unit._run_anything(type#Symbol)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:867
+    #11 MiniTest::Unit.run_tests
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1060
+    #12 MiniTest::Unit._run(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1047
+    #13 Array.each(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1046
+    #14 MiniTest::Unit._run(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1046
+    #15 MiniTest::Unit._run(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1042
+    #16 MiniTest::Unit.run(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/minitest/unit.rb:1035
+    #17 Test::Unit::RunCount.run(args#NilClass)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:21
+    #18 Test::Unit::Runner.run(args#Array)
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:774
+    #19 #<Class:Test::Unit::Runner>.autorun
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:366
+    #20 Test::Unit::RunCount.run_once
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:27
+    #21 #<Class:Test::Unit::Runner>.autorun
+      at /home/davidr/.rvm/rubies/ruby-2.0.0-p195/lib/ruby/2.0.0/test/unit.rb:367
+    #22 <main> at test-triangle.rb:6
+(byebug)
+```
+
+Much better. But again let me emphasize that the parameter types are those of
+the corresponding variables that _currently_ exist, and this might have changed
+since the time when the call was made.
+

data/README.md

@@ -1,5 +1,8 @@
 # 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)
 
+<img src="https://raw.github.com/deivid-rodriguez/byebug/master/logo.png"
+     alt="Byebug logo" align="right" />
+
 _Debugging in Ruby 2.0_
 
 Byebug is a simple to use, feature rich debugger for Ruby 2.0. It uses the new
@@ -32,10 +35,51 @@ in your Gemfile and run
 
 ## Usage
 
-Simply drop `byebug` wherever you want to start debugging and the execution
-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.
+Simply drop
+
+    byebug
+
+wherever you want to start debugging and the execution will 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.
+
+_If you are coming from debugger, notice that stopping execution using the word
+ `debugger` doesn't work anymore unless you explicitly alias it._
+
+### Configuration
+
+You can automatically load some configurations at startup by dropping them in
+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.
+
+
+## What's different from debugger
+
+* Works on 2.0.0 and it doesn't on 1.9.x.
+* Has no MRI internal source code dependencies, just a clean API.
+* Fixes most of debugger's current open issues:
+  - Post mortem mode segfaulting.
+  - Line number wrongly shown as zero in backtrace.
+  - Line tracing.
+  - Colon delimited include paths.
+  - Nice markdow guide.
+  - Ruby 2.0 support.
+* Very actively mantained.
+* Editor agnostic: no external editor built-in support.
+* No thread support as not supported by the new API yet (I hope it will come
+  soon!).
+* Pry command is built-in. No need of external gem like debugger-pry.
+
 
 ## Getting Started
 
@@ -46,15 +90,15 @@ 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:
+    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)
 ```
@@ -81,41 +125,41 @@ 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:
+    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:
+    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:
+    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
@@ -168,14 +212,14 @@ 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:
+    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 =
@@ -189,23 +233,7 @@ 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, 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.
+### The rest of the tutorial is available [here](https://github.com/deivid-rodriguez/byebug/blob/master/GUIDE.md)
 
 
 ## Related projects
@@ -225,3 +253,4 @@ software, specially:
 * Koichi Sasada, author of the new C debugging API for Ruby.
 * Dennis Ushakov, author of [debase](https://github.com/denofevil/debase), the
 starting point of this.
+* Logo by [Ivlichev Victor Petrovich](http://www.aha-soft.com/)