trepanning 0.1.6 → 1.93.32

data/processor/command/info_subcmd/macro.rb

@@ -14,7 +14,7 @@ class Trepan::Subcommand::InfoMacro < Trepan::Subcommand
 In the first form a list of the existing macro names are shown
 in column format.
 
-In the second form, all macro names and their definitions are show.
+In the second form, all macro names and their definitions are shown.
 
 In the last form the only definitions of the given macro names is shown.
     HELP

data/processor/command/info_subcmd/program.rb

@@ -15,18 +15,21 @@ class Trepan::Subcommand::InfoProgram < Trepan::Subcommand
   def run(args)
     frame = @proc.frame
     m = 'Program stop event: %s' % @proc.event
-    m += 
+    m +=
       if frame.iseq
-        '; PC offset %d of instruction sequence: %s' % 
+        '; PC offset %d of instruction sequence: %s' %
           [frame.pc_offset, frame.iseq.name]
       else
         '.'
       end
     msg m
-    if 'return' == @proc.event 
-      msg 'R=> %s' % @proc.frame.sp(1).inspect 
+    if 'return' == @proc.event
+      msg 'R=> %s' % @proc.frame.sp(1).inspect
     elsif 'raise' == @proc.event
-      msg @proc.core.hook_arg.inspect if @proc.core.hook_arg
+        msg @proc.core.hook_arg.inspect if @proc.core.hook_arg
+        if @proc.frame.iseq.catch_table_size == 0
+            msg "Warning: exception raised is non-local!"
+        end
     end
 
     if @proc.brkpt

data/processor/command/info_subcmd/registers.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../base/subsubcmd'
 require_relative '../base/subsubmgr'
 
@@ -7,18 +7,20 @@ class Trepan::SubSubcommand::InfoRegisters < Trepan::SubSubcommandMgr
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
     HELP = <<-EOH
-#{CMD} [lfp|pc|sp]
+**#{CMD}** [**lfp**|**pc**|**sp**]
 
 List of contents for the registers of the current stack frame.
 If a register name given, only only that register is show.
 
 Examples:
-#{CMD}     # show all registers
-#{CMD} pc   # show only the pc register
-info reg sp        # show all stack pointer registers
-info reg sp 1 3    # show sp(1) and sp(3)
-info reg sp size   # show sp size
-info reg lfp       # show lfp(0)
+---------
+
+    #{CMD}     # show all registers
+    #{CMD} pc   # show only the pc register
+    info reg sp        # show all stack pointer registers
+    info reg sp 1 3    # show sp(1) and sp(3)
+    info reg sp size   # show sp size
+    info reg lfp       # show lfp(0)
     EOH
     MIN_ABBREV   = 'reg'.size  # Note we have "info return"
     NEED_STACK   = true
@@ -28,14 +30,14 @@ info reg lfp       # show lfp(0)
   def run(args)
 
     args = @parent.last_args
-    unavailable_regs = 
+    unavailable_regs =
       if 'CFUNC' == @proc.frame.type
-        %w(inforegisterslfp inforegisterspc) 
+        %w(inforegisterslfp inforegisterspc)
       else
         []
       end
     all_regs = @subcmds.subcmds.keys.sort - unavailable_regs
-      
+
     if args.size == 2
       # Form is: "info registers"
       all_regs.sort.each do |subcmd_name|
@@ -49,10 +51,10 @@ info reg lfp       # show lfp(0)
         subcmd = @subcmds.subcmds[key_name]
         if @proc.ok_for_running(subcmd, subcmd.class.const_get('CMD'),
                                 remain_args.size)
-          @subcmds.subcmds[key_name].run(remain_args) 
+          @subcmds.subcmds[key_name].run(remain_args)
         end
       elsif unavailable_regs.member?(key_name)
-        msg("info registers: %s can not be displayed for frame type %s." % 
+        msg("info registers: %s can not be displayed for frame type %s." %
             [subcmd_name, @proc.frame.type])
       else
         errmsg("info registers: %s is not a valid register name" % subcmd_name)

data/processor/command/kill.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../command'
 require_relative '../../app/complete'
 class Trepan::Command::KillCommand < Trepan::Command
@@ -6,26 +6,32 @@ class Trepan::Command::KillCommand < Trepan::Command
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} [signal-number|signal-name]
+**#{NAME}** [signal-number|signal-name]
 
 Kill execution of program being debugged.
 
-Equivalent of Process.kill('KILL', Process.pid). This is an unmaskable
+Equivalent of `Process.kill('KILL', Process.pid)`. This is an unmaskable
 signal. When all else fails, e.g. in thread code, use this.
 
 If you are in interactive mode, you are prompted to confirm killing.
-However when this command is aliased from a command ending in !, no 
+However when this command is aliased from a command ending in "!", no
 questions are asked.
 
 Examples:
+---------
 
-  #{NAME}  
-  #{NAME} unconditionally
-  #{NAME} KILL # same as above
-  #{NAME} kill # same as above
-  #{NAME} -9   # same as above
-  #{NAME}  9   # same as above
-  #{NAME}! 9   # above, but unconditional
+    #{NAME}
+    #{NAME} unconditionally
+    #{NAME} KILL # same as above
+    #{NAME} kill # same as above
+    #{NAME} -9   # same as above
+    #{NAME}  9   # same as above
+    #{NAME}! 9   # above, but unconditional
+
+See also:
+---------
+
+`quit`, `exit`
     HELP
 
     ALIASES      = %w(kill!)
@@ -33,15 +39,15 @@ Examples:
     MAX_ARGS     = 1  # Need at most this many
     SHORT_HELP  = 'Send this process a POSIX signal (default "9" is "kill -9")'
   end
-  
+
   def complete(prefix)
     completions = Signal.list.keys + Signal.list.keys.map{|k| k.downcase} +
-      Signal.list.values.map{|i| i.to_s} + 
-      Signal.list.values.map{|i| (-i).to_s} + 
+      Signal.list.values.map{|i| i.to_s} +
+      Signal.list.values.map{|i| (-i).to_s} +
       ['unconditionally']
     Trepan::Complete.complete_token(completions, prefix)
   end
-    
+
   # This method runs the command
   def run(args) # :nodoc
     unconditional = ('!' == args[0][-1..-1])
@@ -54,7 +60,7 @@ Examples:
     else
       if unconditional || confirm('Really quit?', false)
         sig = 'KILL'
-      else 
+      else
         msg('Kill not confirmed.')
         return
       end
@@ -71,7 +77,7 @@ end
 if __FILE__ == $0
   require_relative '../mock'
   dbgr, cmd = MockDebugger::setup
-  %w(fooo 100 1 -1 HUP -9).each do |arg| 
+  %w(fooo 100 1 -1 HUP -9).each do |arg|
     puts "#{cmd.name} #{arg}"
     cmd.run([cmd.name, arg])
     puts '=' * 40

data/processor/command/list.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 # -*- coding: utf-8 -*-
 require 'linecache'
 require_relative '../command'
@@ -8,79 +8,86 @@ class Trepan::Command::ListCommand < Trepan::Command
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME}[>] [MODULE] [FIRST [NUM]]
-#{NAME}[>] LOCATION [NUM]
+**#{NAME}[>]** [*module*] [*first* [*num*]]
+**#{NAME}[>]** *location [*num*]
 
-#{NAME} source code. 
+List source code.
 
-Without arguments, prints lines centered around the current
-line. If this is the first #{NAME} command issued since the debugger
-command loop was entered, then the current line is the current
-frame. If a subsequent #{NAME} command was issued with no intervening
-frame changing, then that is start the line after we last one
-previously shown.
+Without arguments, prints lines centered around the current line. If
+this is the first #{NAME} command issued since the debugger command
+loop was entered, then the current line is the current frame. If a
+subsequent #{NAME} command was issued with no intervening frame
+changing, then that is start the line after we last one previously
+shown.
 
-If the command has a '>' suffix, then line centering is disabled and
+If the command has a ">" suffix, then line centering is disabled and
 listing begins at the specificed location.
 
 The number of lines to show is controlled by the debugger "listsize"
 setting. Use 'set max list' or 'show max list' to see or set the
 value.
 
-\"#{NAME} -\" shows lines before a previous listing. 
+\"#{NAME} -\" shows lines before a previous listing.
 
-A LOCATION is a either 
-  - number, e.g. 5, 
-  - a function, e.g. join or os.path.join
-  - a module, e.g. os or os.path
-  - a filename, colon, and a number, e.g. foo.rb:5,  
-  - or a module name and a number, e.g,. os.path:5.  
-  - a '.' for the current line number
-  - a '-' for the lines before the current line number
+A *location* is a either:
+
+* number, e.g. 5,
+* a function, e.g. *join* or *os.path.join*
+* a module, e.g. *os* or *os.path*
+* a filename, colon, and a number, e.g. *foo.rb:5*,
+* or a module name and a number, e.g,. *os.path:5*.
+* a "." for the current line number
+* a "-" for the lines before the current line number
 
 If the location form is used with a subsequent parameter, the
 parameter is the starting line number.  When there two numbers are
 given, the last number value is treated as a stopping line unless it
 is positive and less than the start line. In this case, it is taken to
-mean the number of lines to list instead. If last is negative, we start
-that many lines back from first and list to first.
+mean the number of lines to list instead. If last is negative, we
+start that many lines back from first and list to first.
 
-Wherever a number is expected, it does not need to be a constant --
+Wherever a number is expected, it does not need to be a constant,
 just something that evaluates to a positive integer.
 
-Some examples:
-
-#{NAME} 5            # List centered around line 5
-#{NAME} @5           # List lines centered around bytecode offset 5.
-#{NAME} 5>           # List starting at line 5
-#{NAME} foo.rb:5     # List centered around line 5 of foo.rb
-#{NAME} foo.rb 5     # Same as above.
-#{NAME}> foo.rb:5    # List starting around line 5 of foo.rb
-#{NAME} foo.rb  5 6  # list lines 5 and 6 of foo.rb
-#{NAME} foo.rb  5 2  # Same as above, since 2 < 5.
-#{NAME} foo.rb:5 2   # Same as above
-#{NAME} foo.rb 15 -5 # List lines 10..15 of foo
-#{NAME} FileUtils.cp # List lines around the FileUtils.cp function.
-#{NAME} .            # List lines centered from where we currently are stopped
-#{NAME} . 3          # List 3 lines starting from where we currently are stopped
-                     # if . > 3. Otherwise we list from . to 3.
-#{NAME} -            # List lines previous to those just shown
+Examples:
+---------
+
+    #{NAME} 5            # List centered around line 5
+    #{NAME} @5           # List lines centered around bytecode offset 5.
+    #{NAME} 5>           # List starting at line 5
+    #{NAME} foo.rb:5     # List centered around line 5 of foo.rb
+    #{NAME} foo.rb 5     # Same as above.
+    #{NAME}> foo.rb:5    # List starting around line 5 of foo.rb
+    #{NAME} foo.rb  5 6  # list lines 5 and 6 of foo.rb
+    #{NAME} foo.rb  5 2  # Same as above, since 2 < 5.
+    #{NAME} foo.rb:5 2   # Same as above
+    #{NAME} foo.rb 15 -5 # List lines 10..15 of foo
+    #{NAME} FileUtils.cp # List lines around the FileUtils.cp function.
+    #{NAME} .            # List lines centered from where we currently are stopped
+    #{NAME} . 3          # List 3 lines starting from where we currently are stopped
+                         # if . > 3. Otherwise we list from . to 3.
+    #{NAME} -            # List lines previous to those just shown
 
 The output of the #{NAME} command gives a line number, and some status
-information about the line and the text of the line. Here is some 
+information about the line and the text of the line. Here is some
 hypothetical #{NAME} output modeled roughly around line 251 of one
 version of this code:
 
-  251    	  cmd.proc.frame_setup(tf)
-  252  ->	  brkpt_cmd.run(['break'])
-  253 B01   	  line = __LINE__
-  254 b02   	  cmd.run(['list', __LINE__.to_s])
-  255 t03   	  puts '--' * 10
+    251    	  cmd.proc.frame_setup(tf)
+    252  ->	  brkpt_cmd.run(['break'])
+    253 B01   	  line = __LINE__
+    254 b02   	  cmd.run(['list', __LINE__.to_s])
+    255 t03   	  puts '--' * 10
 
 Line 251 has nothing special about it. Line 252 is where we are
 currently stopped. On line 253 there is a breakpoint 1 which is
 enabled, while at line 255 there is an breakpoint 2 which is
 disabled.
+
+See also:
+---------
+
+`set max list`, `show max list`, `disassemble`, `help syntax location`
     HELP
 
     ALIASES       = %W(l #{NAME}> l> cat)
@@ -95,14 +102,14 @@ disabled.
       return
     end
     listsize = settings[:maxlist]
-    center_correction = 
+    center_correction =
       if args[0][-1..-1] == '>'
         0
       else
         (listsize-1) / 2
       end
 
-    iseq, filename, first, last = 
+    iseq, filename, first, last =
       @proc.parse_list_cmd(@proc.cmd_argstr, listsize, center_correction)
     return unless filename
     container = iseq ? iseq.source_container : ['file', filename]
@@ -110,7 +117,7 @@ disabled.
 
     # We now have range information. Do the listing.
     max_line = LineCache::size(filename)
-    unless max_line 
+    unless max_line
       errmsg('File "%s" not found.' % filename)
       return
     end
@@ -140,14 +147,14 @@ disabled.
         end
         line.chomp!
         s = '%3d' % lineno
-        s = s + ' ' if s.size < 4 
+        s = s + ' ' if s.size < 4
         s += if breaklist.member?(lineno)
                bp = breaklist[lineno]
                a_pad = '%02d' % bp.id
                bp.icon_char
-             else 
+             else
                a_pad = '  '
-               ' ' 
+               ' '
              end
         s += (frame && lineno == @proc.frame_line &&
               filename == frame.source_container[1]) ? '->' : a_pad
@@ -164,7 +171,7 @@ if __FILE__ == $0
   if !(ARGV.size == 1 && ARGV[0] == 'noload')
     ARGV[0..-1]    = ['noload']
     load(__FILE__)
-  else    
+  else
     require_relative '../location'
     require_relative '../mock'
     require_relative '../frame'
@@ -185,7 +192,7 @@ if __FILE__ == $0
       puts "%s %s %s" % [seps, args.join(' '), seps]
       run_cmd(cmd,args)
     end
-      
+
 
     load 'tmpdir.rb'
     run_cmd2(cmd, %w(list tmpdir.rb 10))
@@ -204,7 +211,7 @@ if __FILE__ == $0
     run_cmd2(cmd, %w(list 3000))
     run_cmd2(cmd, %w(list run_cmd2))
 
-    p = Proc.new do 
+    p = Proc.new do
       |x,y| x + y
     end
     require 'thread_frame'
@@ -221,7 +228,7 @@ if __FILE__ == $0
     # Start line and count, since 3 < 30
     run_cmd2(cmd, %W(#{cmd.name} Columnize.columnize 30 3))
 
-    # Start line finish line 
+    # Start line finish line
     run_cmd2(cmd, %W(#{cmd.name} Columnize.columnize 40 50))
 
     # puts '--' * 10

data/processor/command/macro.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../command'
 require_relative '../eval'
 class Trepan::Command::MacroCommand < Trepan::Command
@@ -7,65 +7,82 @@ class Trepan::Command::MacroCommand < Trepan::Command
   unless defined?(HELP)
     NAME          = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} MACRO-NAME PROC-OBJECT
+**#{NAME}** *macro-name* *Proc-object*
 
-Define MACRO-NAME as a debugger macro. Debugger macros get a list of
-arguments. Debugger macros get a list of arguments which you supply
-without parenthesis or commas. See below for an example.
+Define *macro-name* as a debugger macro. Debugger macros get a list of
+arguments which you supply without parenthesis or commas. See below
+for an example.
 
-The macro (really a Ruby Proc) should return either a String or an
-Array of Strings. The string in both cases are strings of debugger
-commands.  If the return is a String, that gets tokenized by a simple
-String#split .  Note that macro processing is done right after
-splitting on ;; so if the macro returns a string containing ;; this
-will not be handled on the string returned.
+The macro (really a Ruby *Proc()*) should return either a *String* or
+an *Array* of *Strings*. Each component string in either case
+refers to a debugger command.
 
-If instead, Array of Strings is returned, then the first string is
+If the return is a *String*, that gets tokenized by a simple
+*String#split*.  Note that macro processing is done right after
+splitting on `;;` so if the macro returns a string containing `;;`
+this will not be handled on the string returned.
+
+Here is a simple macro using a string:
+
+    macro resize Proc.new{"set max width"}
+
+We have to use a macro here rather than an *alias*, because the
+expansion is more than to a command name, but contains the 3 tokens,
+"set", "max", and "width".
+
+If an Array of Strings is returned instead, then the first string is
 shifted from the array and executed. The remaining strings are pushed
 onto the command queue. In contrast to the first string, subsequent
 strings can contain other macros, and ;; in those strings will be
 split into separate commands.
 
-Here is an example. The below creates a macro called fin+ which
-issues two commands 'finish' followed by 'step':
+Here is an example using na Array of Strings. The below creates a
+macro called fin+ which issues two commands 'finish' followed by
+'step':
 
-  macro fin+ Proc.new{|*args| %w(finish step)}
+    macro fin+ Proc.new{|*args| %w(finish step)}
 
 If you wanted to parameterize the argument of the 'finish' command
 you could do that this way:
 
-  macro fin+ Proc.new{|*args| ['finish \#{args[0]}' 'step']}
+    macro fin+ Proc.new{|*args| ["finish \#{args[0]}" 'step']}
+
+Invoking with:
 
-Invoking with 
-  fin+ 3
+    fin+ 3
 
 would expand to ["finish 3", "step"]
 
-If you were to add another parameter for 'step', the note that the 
-invocation might be 
-  fin+ 3 2
+If you were to add another parameter for 'step', the note that the
+invocation might be:
+
+   fin+ 3 2
 
 rather than 'fin+(3,2)' or 'fin+ 3, 2'.
 
 Here is another example using arguments. I use the following to debug
 a debugger command:
 
-  macro dbgcmd Proc.new{|*args| ["set debug dbgr", "debug $trepan_cmdproc.commands['\#{args[0]}'].run(\#{args.inspect})"]}
+    macro dbgcmd Proc.new{|*args| ["set debug dbgr", "debug $trepan_cmdproc.commands['\#{args[0]}'].run(\#{args.inspect})"]}
+
+With the above, 'dbgcmd list 5' will ultimately expand to:
 
-With the above, 'dbgcmd list 5' will ultimately expand to: 
-  set debug dbgr
-  debug $trepan_cmdproc.commands['list'].run(['5'])
+    set debug dbgr
+    debug $trepan_cmdproc.commands['list'].run(['5'])
 
 and will debug the debugger's 'list' command on the command 'list 5'.
 
-See also 'info macro'.
+See also:
+---------
+
+`alias` and `info macro`.
     HELP
 
     CATEGORY      = 'support'
     MIN_ARGS      = 2  # Need at least this many
     SHORT_HELP    = 'Define a macro'
   end
-  
+
   def run(args)
     cmd_name = args[1]
     cmd_argstr = @proc.cmd_argstr[cmd_name.size..-1].lstrip
@@ -80,7 +97,7 @@ See also 'info macro'.
     end
   end
 end
-        
+
 if __FILE__ == $0
   require_relative '../mock'
   dbgr, cmd = MockDebugger::setup