trepanning 0.1.6 → 1.93.32

data/processor/command/break.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 '../breakpoint'
 require_relative '../../app/breakpoint'
@@ -7,24 +7,27 @@ class Trepan::Command::BreakCommand < Trepan::Command
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} 
-#{NAME} LOCATION [ {if|unless} CONDITION ]
+**#{NAME}**
+**#{NAME}** *location* [ {if|unless} *condition* ]
 
-Set a breakpoint. In the second form where CONDITIOn is given, the
+Set a breakpoint. In the second form where *condition* is given, the
 condition is evaluated in the context of the position. We stop only If
-CONDITION evalutes to non-false/nil and the "if" form used, or it is
+*condition* evalutes to non-false/nil and the "if" form used, or it is
 false and the "unless" form used.\
 
 Examples:
-   #{NAME}
-   #{NAME} 10               # set breakpoint on line 10
-   #{NAME} 10 if 1 == a     # like above but only if a is equal to 1
-   #{NAME} 10 unless 1 == a # like above but only if a is equal to 1
-   #{NAME} me.rb:10
-   #{NAME} @20   # set breakpoint VM Instruction Sequence offset 20
-   #{NAME} Kernel.pp # Set a breakpoint at the beginning of Kernel.pp
+---------
+    #{NAME}
+    #{NAME} 10               # set breakpoint on line 10
+    #{NAME} 10 if 1 == a     # like above but only if a is equal to 1
+    #{NAME} 10 unless 1 == a # like above but only if a is equal to 1
+    #{NAME} me.rb:10
+    #{NAME} @20   # set breakpoint VM Instruction Sequence offset 20
+    #{NAME} Kernel.pp # Set a breakpoint at the beginning of Kernel.pp
 
-See also condition, continue and "help location".
+See also:
+---------
+`condition`, `continue`, `help syntax location`, and `tbreak`
     HELP
 
     ALIASES      = %w(b)
@@ -39,10 +42,10 @@ See also condition, continue and "help location".
     if args.size == 1
       # usage is "break"  which means break right here
       # FIXME: should handle condition
-      bp = @proc.breakpoint_offset(@proc.frame.pc_offset, 
-                                   @proc.frame.iseq, 'true', false) 
+      bp = @proc.breakpoint_offset(@proc.frame.pc_offset,
+                                   @proc.frame.iseq, 'true', false)
     else
-      iseq, line_number, vm_offset, condition, negate = 
+      iseq, line_number, vm_offset, condition, negate =
         @proc.breakpoint_position(@proc.cmd_argstr, true)
       return false unless iseq && vm_offset
       bp = @proc.breakpoint_offset(vm_offset, iseq, condition, negate, temp)
@@ -56,13 +59,13 @@ See also condition, continue and "help location".
         mess = "Breakpoint %d set at " % bp.id
       end
 
-      line_loc = "line %s in %s" % 
+      line_loc = "line %s in %s" %
         [bp.source_location.join(', '),
          @proc.canonic_container(bp.iseq.source_container).join(' ')]
 
-      vm_loc = "VM offset %d of instruction sequence \"%s\"" % 
+      vm_loc = "VM offset %d of instruction sequence \"%s\"" %
         [bp.offset, bp.iseq.name]
-      
+
       loc, other_loc =
         if 'line' == bp.type
           [line_loc, vm_loc]
@@ -78,7 +81,7 @@ if __FILE__ == $0
   require_relative '../mock'
   dbgr, cmd = MockDebugger::setup
   # require_relative '../../lib/trepanning'
-  def run_cmd(cmd, args) 
+  def run_cmd(cmd, args)
     cmd.proc.instance_variable_set('@cmd_argstr', args[1..-1].join(' '))
     cmd.run(args)
   end
@@ -90,7 +93,7 @@ if __FILE__ == $0
   pc_offset = tf.pc_offset
   run_cmd(cmd, [cmd.name, "@#{pc_offset}"])
   def foo
-    5 
+    5
   end
   run_cmd(cmd, [cmd.name, 'foo', (__LINE__-2).to_s])
   run_cmd(cmd, [cmd.name, 'foo'])

data/processor/command/complete.rb

@@ -1,4 +1,4 @@
-# Copyright (C) 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../command'
 require_relative '../load_cmds'
 class Trepan::Command::CompleteCommand < Trepan::Command
@@ -6,9 +6,12 @@ class Trepan::Command::CompleteCommand < Trepan::Command
   unless defined?(HELP)
     NAME          = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} COMMAND-PREFIX
+**#{NAME}** *command-prefix*
 
 List the completions for the rest of the line as a command.
+
+This is a gdb command. One use is an a front-end which supports
+completion. GNU Emacs for example has been known to use this.
     HELP
     CATEGORY      = 'support'
     NEED_STACK    = false

data/processor/command/condition.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 '../breakpoint'
 require_relative '../../app/breakpoint'
@@ -10,18 +10,23 @@ class Trepan::Command::ConditionCommand < Trepan::Command
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} BP_NUMBER CONDITION
+**#{NAME}** *bp-number* *condition*
 
-BP_NUMBER is a breakpoint number.  CONDITION is an expression which
-must evaluate to True before the breakpoint is honored.  If CONDITION
+*bp-number* is a breakpoint number.  *condition* is an expression which
+must evaluate true before the breakpoint is honored.  If *condition*
 is absent, any existing condition is removed; i.e., the breakpoint is
 made unconditional.
 
 Examples:
-   #{NAME} 5 x > 10  # Breakpoint 5 now has condition x > 10
-   #{NAME} 5         # Remove above condition
+---------
 
-See also "break", "enable" and "disable".
+    #{NAME} 5 x > 10  # Breakpoint 5 now has condition x > 10
+    #{NAME} 5         # Remove above condition
+
+See also:
+--------
+
+`break`, `enable` and `disable`.
     HELP
 
     ALIASES       = %w(cond)
@@ -37,7 +42,7 @@ See also "break", "enable" and "disable".
     bpnum = @proc.get_an_int(args[1])
     bp = @proc.breakpoint_find(bpnum)
     return unless bp
-    
+
     if args.size > 2
       condition = args[2..-1].join(' ')
       return unless valid_condition?(condition)
@@ -54,7 +59,7 @@ if __FILE__ == $0
   require_relative '../mock'
   dbgr, cmd = MockDebugger::setup
   cmd.proc.frame_setup(RubyVM::Frame::current)
-  
+
   cmd.run([cmd.name, '1'])
   cmdproc = dbgr.core.processor
   cmds = cmdproc.commands

data/processor/command/debug.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2010, 2012 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010, 2012, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require 'thread_frame'
 require_relative '../command'
 
@@ -7,9 +7,9 @@ class Trepan::Command::DebugCommand < Trepan::Command
   unless defined?(HELP)
     NAME          = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} RUBY-CODE
+**#{NAME}** *ruby-code*
 
-Enter the debugger recursively on RUBY-CODE.
+Enter the debugger recursively on *ruby-code*.
     HELP
 
     CATEGORY      = 'data'
@@ -27,12 +27,12 @@ Enter the debugger recursively on RUBY-CODE.
     arg_str    = args[1..-1].join(' ')
     hidelevels = @proc.hidelevels[th]
 
-    stack_diff = RubyVM::Frame.current.stack_size - frame.stack_size 
+    stack_diff = RubyVM::Frame.current.stack_size - frame.stack_size
 
     # Ignore tracing in support routines:
     # FIXME remvoe 1.9.3 hack
     if '1.9.3' != RUBY_VERSION
-      tf = @proc.dbgr.trace_filter 
+      tf = @proc.dbgr.trace_filter
       [self.method(:run), @proc.method(:debug_eval),
        @proc.method(:debug_eval_with_exception),
        @proc.method(:get_binding_and_filename),
@@ -44,9 +44,9 @@ Enter the debugger recursively on RUBY-CODE.
     @proc.hidelevels[th] += stack_diff + EXTRA_DEBUG_SETUP_CALLS
 
     # Values we need to save before munging them
-    old_tracing            = th.tracing
+    old_tracing            = th.tracing?
     old_exec_event_tracing = th.exec_event_tracing?
-    old_mutex              = @proc.core.mutex 
+    old_mutex              = @proc.core.mutex
     old_next_level         = @proc.next_level
     old_step_count         = @proc.core.step_count
 
@@ -61,7 +61,7 @@ Enter the debugger recursively on RUBY-CODE.
 
     RubyVM::Frame.current.trace_off = false
     @proc.core.step_count  = 0
-    retval = @proc.debug_eval(arg_str, 15, 
+    retval = @proc.debug_eval(arg_str, 15,
                               RUBY_VERSION == '1.9.3') # FIXME
 
     # Restore munged values

data/processor/command/down.rb

@@ -1,19 +1,19 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010, 2011, 2013 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative 'up'
 
-# Debugger "down" command. Is the same as the "up" command with the 
+# Debugger "down" command. Is the same as the "up" command with the
 # direction (set by DIRECTION) reversed.
 class Trepan::Command::DownCommand < Trepan::Command::UpCommand
 
   Trepan::Util.suppress_warnings {
-    old_verbose = $VERBOSE  
+    old_verbose = $VERBOSE
     $VERBOSE    = nil
     HELP = <<-HELP
 #{NAME} [count]
 
 Move the current frame down in the stack trace (to a newer frame). 0
-is the most recent frame. If no count is given, move down 1.
+is the most-recent frame. If no count is given, move down 1.
 
 See also 'up' and 'frame'.
   HELP
@@ -37,10 +37,10 @@ if __FILE__ == $0
 
   def sep ; puts '=' * 40 end
   cmd.run [cmd.name]
-  %w(-1 0 1 -2).each do |count| 
+  %w(-1 0 1 -2).each do |count|
     puts "#{cmd.name} #{count}"
     cmd.run([cmd.name, count])
-    sep 
+    sep
   end
   def foo(cmd, name)
     cmd.proc.frame_setup(RubyVM::Frame::current)

data/processor/command/edit.rb

@@ -51,6 +51,10 @@ Examples:
       errmsg "edit needs at most 2 args." 
     end
     editor = ENV['EDITOR'] || '/bin/ex'
+    unless File.executable?(editor)
+      errmsg "Editor #{editor} is not executable. Trying anyway..." 
+    end
+
     if File.readable?(file)
       file = File.basename(file) if settings[:basename]
       edit_cmd = "#{editor} +#{line} \"#{file}\""

data/processor/command/eval.rb

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2011, 2012 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative './../command'
 require_relative '../../app/util'
 
@@ -19,7 +19,7 @@ next to the inspect output of the value.
 
 If no string is given, we run the string from the current source code
 about to be run. If the command ends ? (via an alias) and no string is
-given we will the following translations occur:
+given, the following translations occur:
 
    {if|elsif|unless} expr [then]  => expr
    {until|while} expr [do]        => expr

data/processor/command/exit.rb

@@ -1,20 +1,23 @@
-# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2011, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../command'
 class Trepan::Command::ExitCommand < Trepan::Command
 
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-#{NAME} [exitcode] 
+**#{NAME}** [*exitcode*]
 
-hard exit of the debugged program.  
+hard exit of the debugged program.
 
-The program being debugged is exited via exit!() which does not run
-the Kernel at_exit finalizers. If a return code is given, that is the
-return code passed to exit() - presumably the return code that will be
-passed back to the OS. If no exit code is given, 0 is used.
+The program being debugged is exited via *exit!()* which does not run
+the Kernel *at_exit()* finalizers. If a return code is given, that is
+the return code passed to exit() - presumably the return code that
+will be passed back to the OS. If no exit code is given, 0 is used.
 
-See also the commands "quit" and "kill".
+See also:
+---------
+
+`quit` and `kill`.
     HELP
 
     CATEGORY     = 'support'
@@ -27,7 +30,7 @@ See also the commands "quit" and "kill".
 
   # This method runs the command
   def run(args)
-    unconditional = 
+    unconditional =
       if args.size > 1 && args[1] == 'unconditionally'
         args.shift
         true

data/processor/command/finish.rb

@@ -1,42 +1,44 @@
 # -*- coding: utf-8 -*-
-# Copyright (C) 2010-2012 Rocky Bernstein <rockyb@rubyforge.net>
+# Copyright (C) 2010-2012, 2015 Rocky Bernstein <rockyb@rubyforge.net>
 require_relative '../command'
 
 class Trepan::Command::FinishCommand < Trepan::Command
 
-  unless defined?(HELP)
-    NAME = File.basename(__FILE__, '.rb')
-    HELP = <<-HELP
-#{NAME} [levels]
+    unless defined?(HELP)
+        NAME = File.basename(__FILE__, '.rb')
+        HELP = <<-HELP
+**#{NAME}** [*levels*]
 
 Continue execution until the program is about to:
 
-* leave the current function, or 
-* switch context via yielding back or finishing a block which was
-  yielded to. 
+* leave the current function, or
+* switch context via yielding back or finishing a block which was yielded to.
 
-Sometimes this is called 'step out'.
+Sometimes this is called "step out".
 
-When `levels' is specified, that many frame levels need to be
-popped. The default is 1.  Note that 'yield' and exceptions raised my
-reduce the number of stack frames. Also, if a thread is switched, we
-stop ignoring levels.
+When *levels* is specified, that many frame levels need to be
+popped. The default is 1.  Note that running a *yield* or raing an
+exception may reduce the number of stack frames. Also, if a thread is
+switched, we stop ignoring levels.
 
-'next>' is similar in that it stops at a return, but it doesn't
+`next>` is similar in that it stops at a return, but it doesn't
 guarantee the stack level is the same as or less than the current
-one. 
+one.
 
-See the break command if you want to stop at a particular point in a
-program. In general, '#{NAME}', 'step' and 'next' may slow a program down
-while 'break' will have less overhead.
+See also:
+--------
+
+The `break` command if you want to stop at a particular point in a
+program. In general, `#{NAME}`, `step` and `next` may slow a program
+down while `break` will have less overhead.
 
     HELP
     ALIASES      = %w(fin)
     CATEGORY     = 'running'
     # execution_set = ['Running']
 
-    # Need at most this many. 
-    MAX_ARGS     = 1   
+    # Need at most this many.
+    MAX_ARGS     = 1
     NEED_STACK   = true
     SHORT_HELP   = 'Step to end of current method (step out)'
   end
@@ -50,15 +52,15 @@ while 'break' will have less overhead.
     else
       count_str = args[1]
       opts = {
-        :msg_on_error => 
-        "The '#{NAME}' command argument must eval to an integer. Got: %s" % 
+        :msg_on_error =>
+        "The '#{NAME}' command argument must eval to an integer. Got: %s" %
         count_str,
         :min_value => 1
       }
       count = @proc.get_an_int(count_str, opts)
       return unless count
       # step 1 is core.level_count = 0 or "stop next event"
-      level_count = count - 1  
+      level_count = count - 1
     end
     if 0 == level_count and %w(return c-return yield leave).member?(@proc.event)
       errmsg "You are already at the requested return event."

data/processor/command/frame.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/frame'
 
@@ -7,10 +7,11 @@ class Trepan::Command::FrameCommand < Trepan::Command
   include Trepan::Frame
 
   unless defined?(HELP)
-    HELP = 
-"frame [thread-Name] [frame-number]
-    
-Change the current frame to frame `frame-number' if specified, or the
+    NAME = File.basename(__FILE__, '.rb')
+    HELP = <<-HELP
+**#{NAME}** [*thread-Name*] [*frame-number*]
+
+Change the current frame to frame `*rame-number* if specified, or the
 most-recent frame, 0, if no frame number specified.
 
 If a thread name or thread number is given, change the current frame
@@ -18,56 +19,59 @@ to a frame in that thread. Dot (.) can be used to indicate the name of
 the current frame the debugger is stopped in.
 
 A negative number indicates the position from the other or
-least-recently-entered end.  So 'frame -1' moves to the oldest frame.
+least-recently-entered end.  So `frame -1` moves to the oldest frame.
 Any variable or expression that evaluates to a number can be used as a
 position, however due to parsing limitations, the position expression
 has to be seen as a single blank-delimited parameter. That is, the
 expression '(5*3)-1' is okay while '( (5 * 3) - 1 )' isn't.
 
 Examples:
-   frame     # Set current frame at the current stopping point
-   frame 0   # Same as above
-   frame 5-5 # Same as above. Note: no spaces allowed in expression 5-5
-   frame .   # Same as above. 'current thread' is explicit.
-   frame . 0 # Same as above.
-   frame 1   # Move to frame 1. Same as: frame 0; up
-   frame -1  # The least-recent frame
-   frame MainThread 0 # Switch to frame 0 of thread MainThread
-   frame MainThread   # Same as above
-   frame -2434343 0   # Use a thread number instead of name
-
-See also 'up', 'down' 'where' and 'info thread'.
-"
+---------
+
+    frame     # Set current frame at the current stopping point
+    frame 0   # Same as above
+    frame 5-5 # Same as above. Note: no spaces allowed in expression 5-5
+    frame .   # Same as above. 'current thread' is explicit.
+    frame . 0 # Same as above.
+    frame 1   # Move to frame 1. Same as: frame 0; up
+    frame -1  # The least-recent frame
+    frame MainThread 0 # Switch to frame 0 of thread MainThread
+    frame MainThread   # Same as above
+    frame -2434343 0   # Use a thread number instead of name
+
+See also:
+---------
+`up`, `down`, `where`, and `info thread`.
+    HELP
 
     CATEGORY      = 'stack'
     MAX_ARGS      = 2  # Need at most this many
-    NAME          = File.basename(__FILE__, '.rb')
     NEED_STACK    = true
     SHORT_HELP    = 'Select and print a stack frame'
   end
-  
+
   def complete(prefix)
     @proc.frame_complete(prefix, nil)
   end
-  
+
   # The simple case: thread frame switching has been done or is
   # not needed and we have an explicit position number as a string
   def one_arg_run(position_str)
     low, high = @proc.frame_low_high(nil)
     opts={
-      :msg_on_error => 
+      :msg_on_error =>
       "The '#{NAME}' command requires a frame number. Got: #{position_str}",
       :min_value => low, :max_value => high
     }
     frame_num = @proc.get_an_int(position_str, opts)
     return false unless frame_num
-      
+
     # FIXME: move into @proc and test based on NEED_STACK.
     if not @proc.top_frame
       errmsg('No frames recorded.')
       return false
     end
-        
+
     @proc.adjust_frame(frame_num, true)
     return true
   end
@@ -82,7 +86,7 @@ See also 'up', 'down' 'where' and 'info thread'.
       # Form is: "frame position"
       position_str = args[1]
     elsif args.size == 3
-      # Form is: frame <position> <thread> 
+      # Form is: frame <position> <thread>
       name_or_id = args[1]
       thread_str = args[2]
       th = @proc.get_thread_from_string(thread_str)