ruby-debug 0.10.3 → 0.10.4

data/cli/ruby-debug/processor.rb

@@ -1,26 +1,38 @@
 require 'ruby-debug/interface'
 require 'ruby-debug/command'
 
+# _Debugger_ is the module name space for ruby-debug.
 module Debugger
 
-  # Should this be a mixin?
-  class Processor # :nodoc
+  # A processor handles the kind of front-end to program interaction.
+  # Debugger::Processor is the the base class with subclasses
+  # Debugger::CommandProcessor and Debugger::ControlCommandProcessor.
+  class Processor 
     attr_accessor :interface
+    attr_reader   :processor
+    attr_reader   :commands
 
-    # Format msg with gdb-style annotation header
+    # Format _msg_ with gdb-style annotation header.
     def afmt(msg, newline="\n")
       "\032\032#{msg}#{newline}"
     end
     
+    # Print "annotation" message _msg_. Annotation messages are used
+    # by the GNU-Emacs front-end to get status about stacks and
+    # the state of the debugger without having to poll it for information
     def aprint(msg)
       print afmt(msg) if Debugger.annotate.to_i > 2
     end
 
-    # FIXME: use delegate? 
+    # Print a debugger error message; _args_ should be compatible
+    # with something you would pass to Kernel::print.
     def errmsg(*args)
       @interface.errmsg(*args)
     end
 
+    # Print a normal debugger message; _args_ should be compatible
+    # with something you would pass to Kernel::print.
+    # 
     # Callers of this routine should make sure to use comma to
     # separate format argments rather than %. Otherwise it seems that
     # if the string you want to print has format specifier, which
@@ -33,7 +45,10 @@ module Debugger
     
   end
 
-  class CommandProcessor < Processor # :nodoc:
+  # A Debugger::CommandProcessor is the kind of Debugger::Processor
+  # used when you are running inside the same process as the debugged
+  # program.
+  class CommandProcessor < Processor 
     attr_reader   :display
 
     # FIXME: get from Command regexp method.
@@ -60,7 +75,8 @@ module Debugger
     
     def initialize(interface = LocalInterface.new)
       @interface = interface
-      @display = []
+      @commands  = []
+      @display   = []
       
       @mutex = Mutex.new
       @last_cmd = nil
@@ -80,7 +96,7 @@ module Debugger
     
     require 'pathname'  # For cleanpath
     
-    # Regularize file name. 
+    # Regularize or "canonicalize" file name _filename_.
     # This is also used as a common funnel place if basename is 
     # desired or if we are working remotely and want to change the 
     # basename. Or we are eliding filenames.
@@ -100,12 +116,15 @@ module Debugger
       # FIXME: use annotations routines
       if Debugger.annotate.to_i > 2
         file_line = "\032\032source #{file_line}"
-      elsif ENV['EMACS']
+      elsif Debugger.inside_emacs?
         file_line = "\032\032#{file_line}"
       end
       print file_line
     end
-  
+
+    # Create a "protected" version of method _mname_. A protected
+    # method handles all unhandled exceptions that would cause the
+    # program to terminate.
     def self.protect(mname)
       alias_method "__#{mname}", mname
       module_eval %{
@@ -116,13 +135,17 @@ module Debugger
           end
         rescue IOError, Errno::EPIPE
           self.interface = nil
+        rescue SignalException
+          raise
         rescue Exception
           print "INTERNAL ERROR!!! #\{$!\}\n" rescue nil
           print $!.backtrace.map{|l| "\t#\{l\}"}.join("\n") rescue nil
         end
       }
     end
-    
+
+    # This is a callback routine when the debugged program hits a 
+    # breakpoint event. For example ruby-debug-base calls this.
     def at_breakpoint(context, breakpoint)
       aprint 'stopped' if Debugger.annotate.to_i > 2
       n = Debugger.breakpoints.index(breakpoint) + 1
@@ -135,11 +158,13 @@ module Debugger
     end
     protect :at_breakpoint
     
+    # This is a callback routine when the debugged program hits a 
+    # catchpoint. For example ruby-debug-base calls this.
     def at_catchpoint(context, excpt)
       aprint 'stopped' if Debugger.annotate.to_i > 2
       file = CommandProcessor.canonic_file(context.frame_file(0))
       line = context.frame_line(0)
-      print afmt("%s:%d" % [file, line]) if ENV['EMACS']
+      print afmt("%s:%d" % [file, line]) if Debugger.inside_emacs?
       print "Catchpoint at %s:%d: `%s' (%s)\n", file, line, excpt, excpt.class
       fs = context.stack_size
       tb = caller(0)[-fs..-1]
@@ -167,19 +192,52 @@ module Debugger
     end
     protect :at_tracing
 
+    # This is a callback routine when the debugged program hits a
+    # "line" (or statement boundary) event. For example
+    # ruby-debug-base calls this.
     def at_line(context, file, line)
       process_commands(context, file, line)
     end
     protect :at_line
     
+    # This is a callback routine when the debugged program hits a
+    # "return" event. For example ruby-debug-base calls this.
+    # Note: right now ruby-debug-base does not call this. Perhaps 
+    # other bases routines such as the one in JRuby do.
     def at_return(context, file, line)
       context.stop_frame = -1
       process_commands(context, file, line)
     end
+
+    # Return the command object to run given input string _input_.
+    def lookup(input)
+      @commands.find{ |c| c.match(input) }
+    end
+
+    # Run a single command specified by string _input_; _commands_ is and 
+    # Array of possible debugger command objects and _context_ is
+    # a Debugger::Context object.
+    def one_cmd(commands, context, input)
+      if cmd = lookup(input)
+        if context.dead? && cmd.class.need_context
+          p cmd
+          print "Command is unavailable\n"
+        else
+          cmd.execute
+        end
+      else
+        unknown_cmd = commands.find{|cmd| cmd.class.unknown }
+        if unknown_cmd
+            unknown_cmd.execute
+        else
+          errmsg "Unknown command: \"#{input}\".  Try \"help\".\n"
+        end
+      end
+    end
     
     private
 
-    # The prompt shown before reading a command.
+    # Return a prompt string to show before reading a command.
     def prompt(context)
       p = '(rdb:%s) ' % (context.dead?  ? 'post-mortem' : context.thnum)
       p = afmt("pre-prompt")+p+"\n"+afmt("prompt") if 
@@ -187,19 +245,19 @@ module Debugger
       return p
     end
 
-    # Run these commands, for example display commands or possibly
-    # the list or irb in an "autolist" or "autoirb".
-    # We return a list of commands that are acceptable to run bound
-    # to the current state.
+    # Run commands that we always have to run before a entering a
+    # command loop.  For example commands registered via debugger "set
+    # display", "set autolist", or set "autoirb".  We return a list of
+    # commands that are acceptable to run bound to the current state.
     def always_run(context, file, line, run_level)
       event_cmds = Command.commands.select{|cmd| cmd.event }
 
-      # Remove some commands in post-mortem
+      # Remove some commands if we are post mortem.
       event_cmds = event_cmds.find_all do |cmd| 
         cmd.allow_in_post_mortem
       end if context.dead?
 
-      state = State.new do |s|
+      state = State.new(self) do |s|
         s.context = context
         s.file    = file
         s.line    = line
@@ -219,10 +277,12 @@ module Debugger
       return state, commands
     end
 
-    # Handle debugger commands
+    # This the main debugger command-line loop. Here we read a
+    # debugger command, perform it, and ask for another one unless we
+    # are told to continue execution or terminate.
     def process_commands(context, file, line)
-      state, commands = always_run(context, file, line, 1)
-      
+      state, @commands = always_run(context, file, line, 1)
+      $rdebug_state = state if Command.settings[:debuggertesting]
       splitter = lambda do |str|
         str.split(/;/).inject([]) do |m, v|
           if m.empty?
@@ -239,7 +299,7 @@ module Debugger
         end
       end
       
-      preloop(commands, context)
+      preloop(@commands, context)
       CommandProcessor.print_location_and_text(file, line)
       while !state.proceed? 
         input = if @interface.command_queue.empty?
@@ -256,32 +316,18 @@ module Debugger
             @last_cmd = input
           end
           splitter[input].each do |cmd|
-            one_cmd(commands, context, cmd)
-            postcmd(commands, context, cmd)
+            one_cmd(@commands, context, cmd)
+            postcmd(@commands, context, cmd)
           end
         end
       end
-      postloop(commands, context)
+      postloop(@commands, context)
     end # process_commands
-    
-    def one_cmd(commands, context, input)
-      if cmd = commands.find{ |c| c.match(input) }
-        if context.dead? && cmd.class.need_context
-          p cmd
-          print "Command is unavailable\n"
-        else
-          cmd.execute
-        end
-      else
-        unknown_cmd = commands.find{|cmd| cmd.class.unknown }
-        if unknown_cmd
-            unknown_cmd.execute
-        else
-          errmsg "Unknown command: \"#{input}\".  Try \"help\".\n"
-        end
-      end
-    end
-    
+
+    # Things we do before entering the debugger command loop.
+    # Note: in the trepanning debuggers this and always_run have been
+    # merged. To do this and get the order right we add a priority level
+    # for each hook.
     def preloop(commands, context)
       aprint('stopped') if Debugger.annotate.to_i > 2
       if context.dead?
@@ -306,6 +352,7 @@ module Debugger
       end
     end
     
+    # Things we do after leaving the debugger command loop.
     def postcmd(commands, context, cmd)
       if Debugger.annotate.to_i > 0
         cmd = @last_cmd unless cmd
@@ -326,9 +373,14 @@ module Debugger
       end
     end
 
+    # Things we do after leaving the debugger command loop.
     def postloop(commands, context)
     end
 
+    # Run a command in String _cmd_, but tag output with annotation
+    # specified in String _label+. +commands_ is an Array of all
+    # possible debugger command objects, and _context_ is a
+    # Debugger::Context object.
     def annotation(label, commands, context, cmd)
       print afmt(label)
       one_cmd(commands, context, cmd)
@@ -354,25 +406,37 @@ module Debugger
     class State # :nodoc:
       attr_accessor :context, :file, :line, :binding
       attr_accessor :frame_pos, :previous_line, :display
-      attr_accessor :interface, :commands
+      attr_accessor :interface, :commands, :processor
 
-      def initialize
+      def initialize(processor=nil)
         super()
-        @frame_pos = 0
+        @frame_pos     = 0
         @previous_line = nil
-        @proceed = false
+        @proceed       = false
+        @processor     = processor
         yield self
       end
 
-      # FIXME: use delegate? 
+    # Print a debugger error message; _args_ should be compatible
+    # with something you would pass to Kernel::print.
       def errmsg(*args)
         @interface.errmsg(*args)
       end
 
+      # Print a normal debugger message; _args_ should be compatible
+      # with something you would pass to Kernel::print.
+      # 
+      # Callers of this routine should make sure to use comma to
+      # separate format argments rather than %. Otherwise it seems that
+      # if the string you want to print has format specifier, which
+      # could happen if you are trying to show say a source-code line
+      # with "puts" or "print" in it, this print routine will give an
+      # error saying it is looking for more arguments.
       def print(*args)
         @interface.print(*args)
       end
 
+      # confirm is called before performing a dangerous action. 
       def confirm(*args)
         @interface.confirm(*args)
       end
@@ -387,19 +451,25 @@ module Debugger
     end
   end
   
-  class ControlCommandProcessor < Processor # :nodoc:
+  # A Debugger::ControlCommandProcessor is the kind of Debugger::Processor
+  # used the debugged program is running remotely. It is also entered
+  # after the debugged program has terminated.
+  class ControlCommandProcessor < Processor
     def initialize(interface)
       super()
       @interface = interface
       @debugger_context_was_dead = true # Assume we haven't started.
     end
-    
+
+    # This the main debugger command-line loop. Here we read a
+    # debugger command, perform it, and ask for another one unless we
+    # are told to continue execution or terminate.
     def process_commands(verbose=false)
       control_cmds = Command.commands.select do |cmd| 
         cmd.allow_in_control 
       end
       state = State.new(@interface, control_cmds)
-      commands = control_cmds.map{|cmd| cmd.new(state) }
+      @commands = control_cmds.map{|cmd| cmd.new(state) }
 
       unless @debugger_context_was_dead
         if Debugger.annotate.to_i > 2
@@ -412,7 +482,7 @@ module Debugger
       while input = @interface.read_command(prompt(nil))
         print "+#{input}" if verbose
         catch(:debug_error) do
-          if cmd = commands.find{|c| c.match(input) }
+          if cmd = @commands.find{|c| c.match(input) }
             cmd.execute
           else
             errmsg "Unknown command\n"
@@ -427,8 +497,9 @@ module Debugger
       @interface.close
     end
 
-    # The prompt shown before reading a command.
-    # Note: have an unused 'context' parameter to match the local interface.
+    # Return a prompt string to show before reading a command.  Note: The 
+    # _context_ parameter is not used. It must be provided so that the 
+    # interface matches Debugger::CommandProcessor#prompt.
     def prompt(context)
       p = '(rdb:ctrl) '
       p = afmt("pre-prompt")+p+"\n"+afmt("prompt") if 
@@ -447,14 +518,27 @@ module Debugger
       def proceed
       end
       
+      # Print a debugger error message; _args_ should be compatible
+      # with something you would pass to Kernel::print.
       def errmsg(*args)
         @interface.print(*args)
       end
       
+    # Print a normal debugger message; _args_ should be compatible
+    # with something you would pass to Kernel::print.
+    # 
+    # Callers of this routine should make sure to use comma to
+    # separate format argments rather than %. Otherwise it seems that
+    # if the string you want to print has format specifier, which
+    # could happen if you are trying to show say a source-code line
+    # with "puts" or "print" in it, this print routine will give an
+    # error saying it is looking for more arguments.
       def print(*args)
         @interface.print(*args)
       end
-      
+
+      # confirm is called before performing a dangerous action. In
+      # control processor we always return "yes" or "y".
       def confirm(*args)
         'y'
       end

data/runner.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+ruby=${RUBY:-ruby}
+dir=`dirname $0`
+rdebug=${RDEBUG:-${dir}/bin/rdebug}
+$ruby -I${dir}/ext:${dir}/lib:${dir}/cli -- $rdebug $*
+exit $?

data/test/base/reload_bug.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+class TestReloadBug < Test::Unit::TestCase
+  def test_reload_bug
+    top_srcdir = File.join(File.dirname(__FILE__), '..', '..')
+    assert_equal({}, Debugger::source_reload)
+  end
+end

data/test/brkpt-class-bug.rb

@@ -0,0 +1,8 @@
+class A
+  def A.show
+    puts "hi"
+  end
+end
+x = 1
+A.show
+y = 2

data/test/cli/commands/unit/regexp.rb

@@ -9,6 +9,17 @@ class TestCommandREs < Test::Unit::TestCase
   require File.join(base_dir, 'commands', 'frame')
   include Debugger
  
+  def test_quit
+    c = QuitCommand.new(nil)
+    assert c.regexp.match('quit')
+    assert c.regexp.match('q')
+    assert c.regexp.match('quit!')
+    assert c.regexp.match('q!')
+    assert c.regexp.match('quit unconditionally')
+    assert c.regexp.match('exit')
+    assert c.regexp.match('exit!')
+  end
+
   def test_up
     c = UpCommand.new(nil)
     assert c.regexp.match('up')