byebug 5.0.0 → 6.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96c7056e0b0872cdba9ffbc43941b6c804ee5db8
-  data.tar.gz: c06eaaf13304aca7e289301fa61a7c0735f16647
+  metadata.gz: f0c3c3868ab03af89e252040738d248a93ee7fd5
+  data.tar.gz: 86c48afc3df76c6ad06f71e4f187cf7ebfb4d753
 SHA512:
-  metadata.gz: 1fbf5703563d4b88ec8b5b843704a51b78d4f47f5f9e6735942fc1a75c881f440ff4569220e0c6c4f101bda57e1ec16f3089cf26fa3b068c32b97246ee60fd7e
-  data.tar.gz: 0ddec536c7c8ae53485105eaf226946d1fcc3510cd1b0a3220f446d18fbbe2433068de2e922ce44192dc5c559ad5fb74d9a76264327f273be3f127b6f32201f0
+  metadata.gz: f1afe8ff550a182da17c136b3a49030f8370974e3c9b5e818da6f8c5d3c6e4fbe78731ee1840d848e7fbac0baa0b87ea031df44f4c316f69c6ac162bcd523187
+  data.tar.gz: 4c1abe7a5407b9483ebdc7f7c14ac2f142434b699566a06127759593917b466b8986e4cff3b583206a5bd72ac56d9fc38c1dff6ff4b9421ca246885b251f7d74

data/CHANGELOG.md

@@ -1,4 +1,29 @@
-## 5.0.0
+## 6.0.0 - 2015-08-17
+### Removed
+* `autoeval` setting. I haven't heard of anyone setting it to false.
+* `pp`, `putl`, `eval`. People just want to evaluate Ruby code, so the less
+magic the better. Most of the people probably were not aware that `byebug`
+was overriding stuff like `pp` or `eval`. Only keeping `ps` as the single
+"enhanced evaluation" command.
+* `verbose` setting.
+* `info catch` command. Use `catch` without arguments instead.
+* `R` command alias for `restart`.
+
+### Changed
+* `info args` is now `var args`.
+* `interrupt` is now aliased to `int`, not to `i`.
+* API to define custom commands and subcommands (see the Command class).
+
+### Fixed
+* [#140](https://github.com/deivid-rodriguez/byebug/issues/140). `help` command
+not showing the list of available commands and their descriptions.
+* [#147](https://github.com/deivid-rodriguez/byebug/issues/147). Setting
+breakpoints at symlinked files.
+
+### Added
+* API to define custom command processors (see the CommandProcessor class).
+
+## 5.0.0 - 2015-05-18
 ### Fixed
 * [#136](https://github.com/deivid-rodriguez/byebug/issues/136). `frame`
 command not working with negative numbers (thanks @ark6).

data/CONTRIBUTING.md

@@ -1,30 +1,52 @@
 ## Getting started
 
-The following steps should help you getting started:
+### Development dependencies
 
-* `Byebug` depends on the TracePoint API provided by `ruby-core`. This is a
+* `Byebug` depends on Ruby's TracePoint API provided by `ruby-core`. This is a
 young API and a lot of bugs have been recently corrected, so make sure you
 always have the lastest patch level release installed.
-* Get a local clone of `byebug`'s source code.
-* Run `bundle install` to get development & test dependencies installed.
-* Install the [overcommit][] hooks using `bundle exec overcommit --install`.
-They will review your changes before they are committed, checking they are
-consistent with the project's code style. If you're changing C files, make sure
-you have the GNU indent utility installed in your system. `sudo apt-get install
-indent` for linux or `brew install gnu-indent --with-default-names` should do
-the job.
+
+* The recommended tool to manage development dependencies is `bundler`. Run
+`gem install bundler` to install it.
+
+* Running `bundle install` inside a local clone of `byebug` will get development
+dependencies installed.
+
+
+### Running the test suite
+
 * Make sure you compile the C-extension using `bundle exec rake compile`.
 Otherwise you won't be able to use `byebug`.
+
 * Run the test suite using the default rake task (`bundle exec rake`). This
 task is composed of 2 subtasks: `bundle exec rake compile` && `bundle exec rake
 test`.
 
-After having done this, just read the code and improve it! Your contribution is
-appreciated a lot!
+* If you want to run specific tests, use the provided test runner, like so:
+
+  - Specific test files. For example,
+`script/minitest_runner test/commands/break_test.rb`
+
+  - Specific test classes. For example,
+`script/minitest_runner Byebug::BreakAtLinesTestCase`
+
+  - Specific tests. For example,
+`script/minitest_runner test_catch_removes_specific_catchpoint`
+
+  - You can combine any of them and you will get the union of all filters. For
+example: `script/minitest_runner Byebug::BreakAtLinesTestCase
+test_catch_removes_specific_catchpoint`
+
+
+### Code style
+
+* Byebug uses [overcommit][] to enforce code style. Install the git hooks using
+`bundle exec overcommit --install`. They will review your changes before they
+are committed, checking they are consistent with the project's code style.
 
 [overcommit]: https://github.com/brigade/overcommit/
 
-## Byebug as a C-extension
+### Byebug as a C-extension
 
 Byebug is a gem developed as a C-extension. The debugger internal's
 functionality is implemented in C (the interaction with the TracePoint API).

data/GUIDE.md

@@ -157,10 +157,9 @@ 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!`.
+So far, so good. As you can see from the above, to get out of `byebug`, one
+can issue a `quit` command (or the abbreviation `q`). If you want to quit
+without being prompted, suffix the command with an exclamation mark, e.g., `q!`.
 
 
 ### Second Sample Session: Delving Deeper
@@ -206,54 +205,194 @@ $ byebug path/to/hanoi.rb
     9:   hanoi(n - 1, c, b, a) if n - 1 > 0
    10: end
 (byebug) private_methods
-[:public, :private, :include, :using, :define_method, :default_src_encoding, ...
+public
+private
+include
+using
+define_method
+default_src_encoding
+DelegateClass
+Digest
+timeout
+initialize_copy
+initialize_dup
+initialize_clone
+sprintf
+format
+Integer
+Float
+String
+Array
+Hash
+warn
+raise
+fail
+global_variables
+__method__
+__callee__
+__dir__
+eval
+local_variables
+iterator?
+block_given?
+catch
+throw
+loop
+respond_to_missing?
+trace_var
+untrace_var
+at_exit
+syscall
+open
+printf
+print
+putc
+puts
+gets
+readline
+select
+readlines
+`
+p
+test
+srand
+rand
+trap
+load
+require
+require_relative
+autoload
+autoload?
+proc
+lambda
+binding
+caller
+caller_locations
+exec
+fork
+exit!
+system
+spawn
+sleep
+exit
+abort
+Rational
+Complex
+set_trace_func
+gem_original_require
+Pathname
+pp
+y
+URI
+rubygems_require
+initialize
+singleton_method_added
+singleton_method_removed
+singleton_method_undefined
+method_missing
+(byebug) private_methods.member?(:hanoi)
+false
 ```
 
 `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 noautoeval` or
-even drop it in your `.byebugrc` file if you want that behaviour permanently.
-The output of `private_methods`, thought, is unwieldy for our purpose: 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`. It also has a `width` setting that let's us adapt the width of
-the output so that it nicely fits our screen.
+command. You can use any Ruby to inspect your program's state at the place it
+is stopped. Additional, `byebug` provides a specific evaluation command, `ps`
+that automatically enhances the evaluated results a bit. For example, it
+automatically sorts arrays.
+
+```
+[:Array,
+ :Complex,
+ :DelegateClass,
+ :Digest,
+ :Float,
+ :Hash,
+ :Integer,
+ :Pathname,
+ :Rational,
+ :String,
+ :URI,
+ :__callee__,
+ :__dir__,
+ :__method__,
+ :`,
+ :abort,
+ :at_exit,
+ :autoload,
+ :autoload?,
+ :binding,
+ :block_given?,
+ :caller,
+ :caller_locations,
+ :catch,
+ :default_src_encoding,
+ :define_method,
+ :eval,
+ :exec,
+ :exit,
+ :exit!,
+ :fail,
+ :fork,
+ :format,
+ :gem_original_require,
+ :gets,
+ :global_variables,
+ :include,
+ :initialize,
+ :initialize_clone,
+ :initialize_copy,
+ :initialize_dup,
+ :iterator?,
+ :lambda,
+ :load,
+ :local_variables,
+ :loop,
+ :method_missing,
+ :open,
+ :p,
+ :pp,
+ :print,
+ :printf,
+ :private,
+ :proc,
+ :public,
+ :putc,
+ :puts,
+ :raise,
+ :rand,
+ :readline,
+ :readlines,
+ :require,
+ :require_relative,
+ :respond_to_missing?,
+ :rubygems_require,
+ :select,
+ :set_trace_func,
+ :singleton_method_added,
+ :singleton_method_removed,
+ :singleton_method_undefined,
+ :sleep,
+ :spawn,
+ :sprintf,
+ :srand,
+ :syscall,
+ :system,
+ :test,
+ :throw,
+ :timeout,
+ :trace_var,
+ :trap,
+ :untrace_var,
+ :using,
+ :warn,
+ :y]
 
-```bash
-(byebug) set width 80
-Maximum width of byebug's output is 80
-(byebug) ps private_methods
-Array             default_src_encoding  open                        sleep
-Complex           define_method         p                           spawn
-Digest            eval                  pp                          sprintf
-Float             exec                  print                       srand
-Hash              exit                  printf                      syscall
-Integer           exit!                 private                     system
-Pathname          fail                  proc                        test
-Rational          fork                  public                      throw
-String            format                putc                        timeout
-URI               gem_original_require  puts                        trace_var
-__callee__        gets                  raise                       trap
-__dir__           global_variables      rand                        untrace_var
-__method__        include               readline                    using
-`                 initialize            readlines                   warn
-abort             initialize_clone      require                     y
-at_exit           initialize_copy       require_relative
-autoload          initialize_dup        respond_to_missing?
-autoload?         iterator?             rubygems_require
-binding           lambda                select
-block_given?      load                  set_trace_func
-caller            local_variables       singleton_method_added
-caller_locations  loop                  singleton_method_removed
-catch             method_missing        singleton_method_undefined
-(byebug)
 ```
 
 Now let's see what happens after stepping:
 
 ```bash
-(byebug) private_methods.member?(:hanoi)
-false
 (byebug) step
 
 [5, 14] in /path/to/hanoi.rb
@@ -1146,7 +1285,7 @@ letter option name, such as `-h`. The list of options is detailed below:
 
 #### -h | --help
 
-It causes `byebug` to print some basic help and exit
+It causes `byebug` to print some basic help and exit.
 
 
 #### -v | --version
@@ -1233,12 +1372,14 @@ You can also request the execution of a command file with the `source` command
 
 ### Quitting byebug
 
-To exit `byebug`, use the `quit` command (abbreviated `q` and aliased `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
-`quit unconditionally` (abbreviated `q!`). Another way to terminate byebug is to
-use the `kill` command. This does the more forceful `kill -9`. It can be used in
-cases where `quit` doesn't work (I haven't seen those yet).
+To exit `byebug`, use the `quit` command (abbreviated to `q`). Normally, if you
+are in an interactive session, this command will prompt to ask if you really
+want to quit. If you want to quit without being prompted, enter `quit
+unconditionally` (abbreviated to `q!`).
+
+Another way to terminate byebug is to use the `kill` command. This does the
+more forceful `kill -9`. It can be used in cases where `quit` doesn't work (I
+haven't seen those yet).
 
 
 ### Calling byebug from inside your program
@@ -1335,8 +1476,8 @@ Multiple commands can be put on a line by separating each with a semicolon `;`.
 You can disable the meaning of a semicolon to separate commands by escaping it
 with a backslash.
 
-For example, if you have [autoeval]() set, which is the default, you might want
-to enter the following code to compute the 5th Fibonacci number.
+For example, you might want to enter the following code to compute the 5th
+Fibonacci number.
 
 ```bash
 (byebug) fib1=0; fib2=1; 5.times {|temp| temp=fib1; fib1=fib2; fib2 += temp }
@@ -1389,26 +1530,61 @@ short list of named classes of commands
 
 ```bash
 (byebug) help
-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      skip  up      continue  edit       frame      list
-pry        restart  source  var
+
+  break      -- Sets breakpoints in the source code
+  catch      -- Handles exception catchpoints
+  condition  -- Sets conditions on breakpoints
+  continue   -- Runs until program ends, hits a breakpoint or reaches a line
+  delete     -- Deletes breakpoints
+  disable    -- Disables breakpoints or displays
+  display    -- Evaluates expressions every time the debugger stops
+  down       -- Moves to a lower frame in the stack trace
+  edit       -- Edits source files
+  enable     -- Enables breakpoints or displays
+  finish     -- Runs the program until frame returns
+  frame      -- Moves to a frame in the call stack
+  help       -- Helps you using byebug
+  history    -- Shows byebug's history of commands
+  info       -- Shows several informations about the program being debugged
+  interrupt  -- Interrupts the program
+  irb        -- Starts an IRB session
+  kill       -- Sends a signal to the current process
+  list       -- Lists lines of source code
+  method     -- Shows methods of an object, class or module
+  next       -- Runs one or more lines of code
+  pry        -- Starts a Pry session
+  ps         -- Evaluates an expression and prettyprints & sort the result
+  quit       -- Exits byebug
+  restart    -- Restarts the debugged program
+  save       -- Saves current byebug session to a file
+  set        -- Modifies byebug settings
+  show       -- Shows byebug settings
+  source     -- Restores a previously saved byebug session
+  step       -- Steps into blocks or methods one or more times
+  thread     -- Commands to manipulate threads
+  tracevar   -- Enables tracing of a global variable
+  undisplay  -- Stops displaying all or some expressions when program stops
+  untracevar -- Stops tracing a global variable
+  up         -- Moves to a higher frame in the stack trace
+  var        -- Shows variables and its values
+  where      -- Displays the backtrace
+
 ```
 
-With a command name as `help` argument, `byebug` displays short information on how to
-use that command.
+With a command name, `help` displays information on how to use the command.
 
 ```bash
 (byebug) help list
-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'
+
+  l[ist][[-=]][ nn-mm]
+
+  Lists lines of source code
+
+  Lists lines forward from current line or from the place where code was
+  last listed. If "list-" is specified, lists backwards instead. If
+  "list=" is specified, lists from current line regardless of where code
+  was last listed. A line range can also be specified to list specific
+  sections of code.
 (byebug)
 ```
 
@@ -1461,10 +1637,10 @@ With an integer argument, list info on that breakpoint.
 
 #### Quit
 
-To exit `byebug`, type `quit` (abbreviated `q` and aliased `exit`). Normally if
-you are in an interactive session, this command will prompt you to confirm you
-really want to quit. If you don't want any questions asked, enter
-`quit unconditionally` (abbreviated `q!`).
+To exit `byebug`, type `quit` (abbreviated to `q`). Normally, if you are in an
+interactive session, this command will prompt you to confirm you really want to
+quit. If you want to quit without being prompted, enter `quit unconditionally`
+(abbreviated to `q!`).
 
 #### Restart
 
@@ -1529,135 +1705,17 @@ later. To do that, use `disable display` or `enable display` followed by the
 expression number.
 
 
-### Print Commands
+### Evaluation of expressions: display
 
-One way to examine and change data in your script is with the `eval` command
-(abbreviated `p`). `byebug` by default evaluates any input that is not
-recognized as a command, so in most situations `eval` is not necessary and
-`byebug` will work like a REPL. One case where it's necessary could be when
-trying to print a variable called `n`. In this case, you have no choice because
+To examine and change data in your script you can just evaluate any Ruby code
+from `byebug`'s prompt. Any input that is not recognized as a command will be
+evaluated, so `byebug` essentially works as a REPL. If you want to evaluate
+something that conflicts with a `byebug` command, just use Ruby's `eval`. For
+example, if you want to print a variable called `n `, type `eval n` because
 typing just `n` will execute `byebug`'s command `next`.
 
-A similar command to `eval|p` is `pp` which tries to pretty print the result.
-
-If the value you want to print is an array, sometimes a columnized list looks
-nicer. Use `putl` for that. Notice however that entries are sorted to run down
-first rather than across. If the value is not an array `putl` will just call
-pretty-print.
-
-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 `method` commands. Use `ps` for that. If the value is not an array `ps`
-will just call pretty-print.
-
-```bash
-(byebug) Kernel.instance_methods
-[:nil?, :===, :=~, :!~, :eql?, :hash, :<=>, :class, :singleton_class, :clone,
-:dup, :taint, :tainted?, :untaint, :untrust, :untrusted?, :trust, :freeze,
-:frozen?, :to_s, :inspect, :methods, :singleton_methods, :protected_methods,
-:private_methods, :public_methods, :instance_variables, :instance_variable_get,
-:instance_variable_set, :instance_variable_defined?, :remove_instance_variable,
-:instance_of?, :kind_of?, :is_a?, :tap, :send, :public_send, :respond_to?,
-:extend, :display, :method, :public_method, :define_singleton_method,
-:object_id, :to_enum, :enum_for, :gem, :pretty_inspect, :byebug]
-(byebug) p Kernel.instance_methods
-[:nil?, :===, :=~, :!~, :eql?, :hash, :<=>, :class, :singleton_class, :clone,
-:dup, :taint, :tainted?, :untaint, :untrust, :untrusted?, :trust, :freeze,
-:frozen?, :to_s, :inspect, :methods, :singleton_methods, :protected_methods,
-:private_methods, :public_methods, :instance_variables, :instance_variable_get,
-:instance_variable_set, :instance_variable_defined?, :remove_instance_variable,
-:instance_of?, :kind_of?, :is_a?, :tap, :send, :public_send, :respond_to?,
-:extend, :display, :method, :public_method, :define_singleton_method,
-:object_id, :to_enum, :enum_for, :gem, :pretty_inspect, :byebug]
-(byebug) pp Kernel.instance_methods
-[:nil?,
- :===,
- :=~,
- :!~,
- :eql?,
- :hash,
- :<=>,
- :class,
- :singleton_class,
- :clone,
- :dup,
- :taint,
- :tainted?,
- :untaint,
- :untrust,
- :untrusted?,
- :trust,
- :freeze,
- :frozen?,
- :to_s,
- :inspect,
- :methods,
- :singleton_methods,
- :protected_methods,
- :private_methods,
- :public_methods,
- :instance_variables,
- :instance_variable_get,
- :instance_variable_set,
- :instance_variable_defined?,
- :remove_instance_variable,
- :instance_of?,
- :kind_of?,
- :is_a?,
- :tap,
- :send,
- :public_send,
- :respond_to?,
- :extend,
- :display,
- :method,
- :public_method,
- :define_singleton_method,
- :object_id,
- :to_enum,
- :enum_for,
- :gem,
- :pretty_inspect,
- :byebug]
-(byebug) putl Kernel.instance_methods
-nil?             trust                       is_a?
-===              freeze                      tap
-=~               frozen?                     send
-!~               to_s                        public_send
-eql?             inspect                     respond_to?
-hash             methods                     extend
-<=>              singleton_methods           display
-class            protected_methods           method
-singleton_class  private_methods             public_method
-clone            public_methods              singleton_method
-dup              instance_variables          define_singleton_method
-itself           instance_variable_get       object_id
-taint            instance_variable_set       to_enum
-tainted?         instance_variable_defined?  enum_for
-untaint          remove_instance_variable    gem
-untrust          instance_of?                pretty_inspect
-untrusted?       kind_of?
-(byebug) ps Kernel.instance_methods
-!~                       instance_of?                public_send
-<=>                      instance_variable_defined?  remove_instance_variable
-===                      instance_variable_get       respond_to?
-=~                       instance_variable_set       send
-class                    instance_variables          singleton_class
-clone                    is_a?                       singleton_method
-define_singleton_method  itself                      singleton_methods
-display                  kind_of?                    taint
-dup                      method                      tainted?
-enum_for                 methods                     tap
-eql?                     nil?                        to_enum
-extend                   object_id                   to_s
-freeze                   pretty_inspect              trust
-frozen?                  private_methods             untaint
-gem                      protected_methods           untrust
-hash                     public_method               untrusted?
-```
-
 Finally, if you need more advanced functionality from REPL's, you can enter
-`irb` or `pry` using `irb` or `pry` commands. The bindings environment will be
+`irb` or `pry` using `irb` or `pry` commands. The binding's environment will be
 set to the current state in the program.  When you leave the repl and go back to
 `byebug`'s command prompt we show the file, line and text position of the
 program. If you issue a `list` without location information, the default
@@ -1698,7 +1756,7 @@ def triangle(n)
 (byebug)
 ```
 
-### Printing variables
+### Printing variables: var
 
 Byebug can print many different information about variables. Such as
 * `var const <object>`. Show the constants of `<object>`. This is basically
@@ -1712,8 +1770,8 @@ basically listing `<object>.instance_variables`.
 * `method instance <object>`. Show methods of `<object>`. Basically this is the
 same as running `ps <object>.instance_methods(false)`.
 * `method <class-or-module>`. Show methods of the class or module
-`<class-or-module>`. Basically this is the same as running
-`ps <class-or-module>.methods`.
+`<class-or-module>`. Basically this is the same as running `ps
+<class-or-module>.methods`.
 
 ### Examining Program Source Files: list