trepanning 0.1.6 → 1.93.32

data/processor/command/help/examples.md

@@ -0,0 +1,20 @@
+Command examples
+================
+
+	# This line does nothing. It is a comment. Useful in debugger command files.
+	    # This line also does nothing.
+	s    # by default, this is an alias for the "step" command
+	!s   # shows the value of variable "s".
+	!!s  # Evaluates "!s" (or "not s"). The first ! is indicates evaluate.
+	 !s   # Same as above, since there is a space in column one.
+
+	info program;; list # Runs two commands "info program" and "list"
+	pr  "hi ;;-)"  # Syntax error since ;; splits the line and " is not closed.
+	!puts "hi ;;-)" # One way to do the above.
+
+See also:
+---------
+
+`macro`, `alias`, `irb`, `set auto eval`, `set auto irb`, `set
+abbrev`, `info macro`, and the *show* variants of the above *set*
+commands.

data/processor/command/help/filename.md

@@ -0,0 +1,46 @@
+Syntax for Indicating a Filename
+================================
+
+There are two ways you can give a file name:
+
+* unadorned (without double-quotes) with possible escapes
+* as a double-quoted string with possible escapes in the string
+
+Probably most of the time a file name will be specified in the first
+form, without using quotes. If the file name however has a space or a
+colon in it, escape that character with a backslash. Also, if you need
+to enter a backslash and the character followinng that is unlucky
+enough to be a colon, space, or backslash use two backslashes.
+
+Filename Examples:
+------------------
+
+    irb.rb       => irb.rb
+    /tmp/irb.rb  =>  /tmp/irb.rb
+    C\:irb.rb    =>  C:irb.rb
+    C\:\irb.rb   =>  C:\irb.rb
+    C\:\\irb.rb  =>  C:\irb.rb  # Note: double slash not needed
+    \\new.rb    =>  \new.rb     # Note: double slash, or filename has newline
+    my\ file.rb  =>  my file.rb
+
+
+The quoted string is useful if you have a file name that contains
+several characters that normally confuse the debugger parser, notably
+a space, newline, or a colon. The quoted string starts with a double
+quote ("). Escape sequences are allowed inside the string to be able
+to enter tabs or newlines, or a double quote inside the string. The
+list of translations is as follows:
+
+
+    \t => <tab>
+    \n => <newline>
+    \" => "
+    \\ => \
+
+Quoted Filename Examples:
+-------------------------
+
+    "This is a file with blanks.rb" => This is a file with blanks.rb
+    "/tmp/RubyProgram \"foo\".rb    => /tmp/RubyProgram "foo".rb
+    "/Ruby\nProgram.rb"             => /tmp/Ruby
+	Program.rb

data/processor/command/help/location.md

@@ -0,0 +1,34 @@
+Syntax for Source-Code Locations
+================================
+
+Locations are used to indicates places in the source code or the
+places in bytecode compiled from source code. Locations are used in
+the listing commands like `list` or `disassemble`; they are also used
+in *breakpoint* commands like `break`, `tbreak` and `continue`.
+
+A location is either some sort of *container* and a position inside
+that container. A container is either a file name or a method
+name. And a position is either a line number or a bytecode offset.
+Bytecode offsets are prefaced with an "@". So 4 is a line number 4, but
+`@4` is bytecode offset 4.
+
+File names are distinguished from method names purely by semantic
+means.  That its *foo* could conceivably be either a method or a file
+name. The debugger does a file check to see if *foo* is a file.
+
+In *gdb*, locations are often given using a filename a colon and a line
+number. That is supported here are well. So `myfile.rb:5` indicates line 5
+of file *myfile.rb*. But since we also allow method names you can also use
+`gcd:5` to indicate line 5 of method *gcd()*.
+
+Line numbers in methods are not relative to the beginning of the
+method but relative the beginning of source text that contains the
+method. This is also how Ruby stores line numbers for methods which
+are shown for example in a backtrace. So all of this hopefully will
+feel familiar and consistent.
+
+Instead of using a colon to separate the container and the position,
+you can also use spacs. So `gcd 5` is the same as `gcd:5`.
+
+If the filename has an embedded blank in it, you can indicate that by
+using a backslash escape. For example: "file\ with\ blanks.rb"

data/processor/command/help/suffixes.md

@@ -0,0 +1,19 @@
+Command suffixes which have special meaning
+===========================================
+
+Some commands like `step`, or `list` do different things when an
+alias to the command ends in a particular suffix like `>`.
+
+Here are a list of commands and the special suffixes:
+
+    command   suffix
+    -------   ------
+    list       >
+    step       +,-,<,>
+    next       +,-,<,>
+    quit       !
+    kill       !
+    eval       ?
+
+See the help on the specific commands listed above for the specific
+meaning of the suffix.

data/processor/command/info.rb

@@ -1,18 +1,20 @@
 # -*- 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/submgr'
 
 class Trepan::Command::InfoCommand < Trepan::SubcommandMgr
   unless defined?(HELP)
     NAME = File.basename(__FILE__, '.rb')
     HELP = <<-HELP
-Generic command for showing things about the program being debugged. 
+**#{NAME}** [*info-subcommand*]
+
+Generic command for showing things about the program being debugged.
 
 You can give unique prefix of the name of a subcommand to get
 information about just that subcommand.
 
-Type "#{NAME}" for a list of "info" subcommands and what they do.
-Type "help #{NAME} *" for just a list of "info" subcommands.
+Type `#{NAME}` for a list of *#{NAME}* subcommands and what they do.
+Type `help #{NAME} `" for just a list of `*#{NAME}*` subcommands.
     HELP
 
     ALIASES       = %w(i)

data/processor/command/info_subcmd/breakpoints.rb

@@ -1,16 +1,16 @@
 # -*- 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/subcmd'
 
 class Trepan::Subcommand::InfoBreakpoints < Trepan::Subcommand
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
     HELP         = <<-EOH
-#{CMD} [num1 ...] [verbose]
+**#{CMD}** [*num1* ...] [**verbose**]
 
 Show status of user-settable breakpoints. If no breakpoint numbers are
 given, the show all breakpoints. Otherwise only those breakpoints
-listed are shown and the order given. If VERBOSE is given, more
+listed are shown and the order given. If *verbose* is given, more
 information provided about each breakpoint.
 
 The "Disp" column contains one of "keep", "del", the disposition of
@@ -23,7 +23,7 @@ EOH
     MIN_ABBREV   = 'br'.size
     SHORT_HELP   = 'Status of user-settable breakpoints'
   end
-  
+
   def bpprint(bp, verbose=false)
     disp  = bp.temp?    ? 'del  ' : 'keep '
     disp += bp.enabled? ? 'y  '   : 'n  '
@@ -31,7 +31,7 @@ EOH
     iseq = bp.iseq
     mess = '%-4dbreakpoint    %s at ' % [bp.id, disp]
 
-    line_loc = '%s:%d' % 
+    line_loc = '%s:%d' %
       [iseq.source_container.join(' '),
        iseq.offset2lines(bp.offset).join(', ')]
     vm_loc = "VM offset %d of instruction sequence \"%s\"" %
@@ -66,7 +66,7 @@ EOH
       iseq = bp.iseq
       next unless 'file' == iseq.source_container[0]
       loc = iseq.source_container[1] + ':'
-      loc += 
+      loc +=
         # if 'line' == bp.type
           iseq.offset2lines(bp.offset)[0].to_s
         # else
@@ -86,10 +86,10 @@ EOH
     end
 
 
-    show_all = 
+    show_all =
       if args.size > 2
         opts = {
-        :msg_on_error => 
+        :msg_on_error =>
         "An '#{CMD}' argument must eval to a breakpoint between 1..#{@proc.brkpts.max}.",
         :min_value => 1,
         :max_value => @proc.brkpts.max
@@ -99,9 +99,9 @@ EOH
       else
         true
       end
-    
+
     bpmgr = @proc.brkpts
-    if bpmgr.empty?  
+    if bpmgr.empty?
       msg('No breakpoints.')
     else
       # There's at least one
@@ -121,7 +121,7 @@ EOH
           end
         end
         errmsg "No breakpoint number(s) #{not_found.join(' ')}." unless
-          notfound.empty? 
+          notfound.empty?
       end
     end
     if @proc.traced_vars.empty?
@@ -152,9 +152,9 @@ if __FILE__ == $0
   tf = RubyVM::Frame.current
   pc_offset = tf.pc_offset
   def foo
-    5 
+    5
   end
-  
+
   brk_cmd = dbgr.core.processor.commands['break']
   brk_cmd.run(['break', "O#{pc_offset}"])
   cmd.run(%w(info break))

data/processor/command/info_subcmd/files.rb

@@ -12,37 +12,41 @@ class Trepan::Subcommand::InfoFiles < Trepan::Subcommand
     DEFAULT_FILE_ARGS = %w(size mtime sha1)
 
     HELP = <<-EOH
-#{CMD} [{FILENAME|.|*} [all|ctime|brkpts|mtime|sha1|size|stat]]
+**#{CMD}** [{*filename*|.|\\*} *attributes*
+
+*attributes* can be any set of of:
+  **all**, **ctime**, **brkpts**, **mtime**, **sha1**, **size** or **stat**
 
 Show information about the current file. If no filename is given and
 the program is running, then the current file associated with the
-current stack entry is used. Giving . has the same effect. 
+current stack entry is used. Giving . has the same effect.
 
-Given * gives a list of all files we know about.
+A `*` gives a list of all files we know about.
 
 Sub options which can be shown about a file are:
 
-brkpts -- Line numbers where there are statement boundaries. 
-          These lines can be used in breakpoint commands.
-ctime  -- File creation time
-iseq   -- Instruction sequences from this file.
-mtime  -- File modification time
-sha1   -- A SHA1 hash of the source text. This may be useful in comparing
-          source code.
-size   -- The number of lines in the file.
-stat   -- File.stat information
+    brkpts -- Line numbers where there are statement boundaries.
+              These lines can be used in breakpoint commands.
+    ctime  -- File creation time
+    iseq   -- Instruction sequences from this file.
+    mtime  -- File modification time
+    sha1   -- A SHA1 hash of the source text. This may be useful in comparing
+              source code.
+    size   -- The number of lines in the file.
+    stat   -- File.stat information
 
-all    -- All of the above information.
+    all    -- All of the above information.
 
-If no sub-options are given, "#{DEFAULT_FILE_ARGS.join(' ')}" are assumed.
+If no sub-options are given, `#{DEFAULT_FILE_ARGS.join(' ')}` are assumed.
 
 Examples:
+---------
 
-#{CMD}    # Show #{DEFAULT_FILE_ARGS.join(' ')} information about current file
-#{CMD} .  # same as above
-#{CMD} brkpts      # show the number of lines in the current file
-#{CMD} brkpts size # same as above but also list breakpoint line numbers
-#{CMD} *  # Give a list of files we know about
+    #{CMD}    # Show #{DEFAULT_FILE_ARGS.join(' ')} information about current file
+    #{CMD} .  # same as above
+    #{CMD} brkpts      # show the number of lines in the current file
+    #{CMD} brkpts size # same as above but also list breakpoint line numbers
+    #{CMD} *  # Give a list of files we know about
 EOH
     MIN_ABBREV   = 'fi'.size  # Note we have "info frame"
     NEED_STACK   = false
@@ -53,7 +57,7 @@ EOH
   include Trepanning
 
   def file_list
-    (LineCache.cached_files + 
+    (LineCache.cached_files +
      LineCache.class_variable_get('@@file2file_remap').keys).uniq
   end
 
@@ -61,11 +65,11 @@ EOH
     completions = ['.'] + file_list
     Trepan::Complete.complete_token(completions, prefix)
   end
-  
+
   # Get file information
   def run(args)
     return if args.size < 2
-    args << '.' if 2 == args.size 
+    args << '.' if 2 == args.size
     if '*' == args[2]
       section 'Canonic Files names cached:'
       primary = LineCache.class_variable_get('@@file_cache')
@@ -78,7 +82,7 @@ EOH
       end
       return
     end
-    filename = 
+    filename =
       if '.' == args[2]
         if not @proc.frame
           errmsg("No frame - no default file.")
@@ -133,7 +137,7 @@ EOH
     args[3..-1].each do |arg|
       processed_arg = false
 
-      if %w(all size).member?(arg) 
+      if %w(all size).member?(arg)
         unless seen[:size]
           max_line = LineCache::size(canonic_name)
           msg "File has %d lines." % max_line if max_line
@@ -165,19 +169,19 @@ EOH
 
       if %w(all ctime).member?(arg)
         unless seen[:ctime]
-          msg("create time:\t%s." % 
+          msg("create time:\t%s." %
               LineCache::stat(canonic_name).ctime.to_s)
         end
         processed_arg = seen[:ctime] = true
       end
-      
-      if %w(all iseq).member?(arg) 
+
+      if %w(all iseq).member?(arg)
         unless seen[:iseq]
           if SCRIPT_ISEQS__.member?(canonic_name)
             msg("File contains instruction sequences:")
             SCRIPT_ISEQS__[canonic_name].each do |iseq|
               msg("\t %s %s" % [iseq, iseq.name.inspect])
-            end 
+            end
           else
             msg("Instruction sequences not recorded; there may be some, though.")
           end
@@ -187,12 +191,12 @@ EOH
 
       if %w(all mtime).member?(arg)
         unless seen[:mtime]
-          msg("modify time:\t%s." % 
+          msg("modify time:\t%s." %
               LineCache::stat(canonic_name).mtime.to_s)
         end
         processed_arg = seen[:mtime] = true
       end
-      
+
       if %w(all stat).member?(arg)
         unless seen[:stat]
           msg("Stat info:\n\t%s." % LineCache::stat(canonic_name).inspect)
@@ -213,7 +217,7 @@ if __FILE__ == $0
     SCRIPT_ISEQS__ = {}
     ARGV[0..-1]    = ['noload']
     load(__FILE__)
-  else    
+  else
     require_relative '../../mock'
     cmd = MockDebugger::sub_setup(Trepan::Subcommand::InfoFiles, false)
     [%w(info file nothere),

data/processor/command/info_subcmd/frame.rb

@@ -1,12 +1,12 @@
 # -*- 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/subcmd'
 
 class Trepan::Subcommand::InfoFrame < Trepan::Subcommand
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
     HELP = <<-EOH
-#{CMD} 
+**#{CMD}**
 
 Show information about the selected frame. The fields we list are:
 
@@ -14,47 +14,96 @@ Show information about the selected frame. The fields we list are:
 * The actual number of arguments passed in
 * The 'arity' or permissible number of arguments passed it. -1 indicates
   variable number
-* The frame "type", e.g. TOP, METHOD, BLOCK, EVAL, CFUNC etc.
+* The frame "type", e.g. `TOP`, `METHOD`, `BLOCK`, `EVAL`, `CFUNC`, etc.
 * The return value if the frame is at a return point
-* The PC offset we are currently at; May be omitted of no instruction 
+* The PC offset we are currently at; May be omitted of no instruction
   sequence
 
 A backtrace shows roughly the same information in a more compact form.
 
-Example form inside File.basename('foo')
+Example from inside File.basename('foo'):
+-----------------------------------------
 
-Frame basename
-  file  : /tmp/c-func.rb # actually location of caller
-  line  : 2  # inherited from caller
-  argc  : 1  # One out argument supplied: 'foo'
-  arity : -1 # Variable number of args, can have up to 2 arguments.
-  type  : CFUNC  (A C function)
+    Frame basename
+      file  : /tmp/c-func.rb # actually location of caller
+      line  : 2  # inherited from caller
+      argc  : 1  # One out argument supplied: 'foo'
+      arity : -1 # Variable number of args, can have up to 2 arguments.
+      type  : CFUNC  (A C function)
 
+See also:
+---------
+`backtrace`
+      EOH
+        MIN_ABBREV   = 'fr'.size # Note we have "info file"
+        MIN_ARGS     = 0
+        MAX_ARGS     = 0
+        NEED_STACK   = true
+        SHORT_HELP   = 'Show information about the selected frame'
+    end
 
-See also: backtrace
-    EOH
-    MIN_ABBREV   = 'fr'.size # Note we have "info file"
-    MIN_ARGS     = 0
-    MAX_ARGS     = 0
-    NEED_STACK   = true
-    SHORT_HELP   = 'Show information about the selected frame'
-  end
-
-  def run(args)
-    frame = @proc.frame
-    section "Frame %2d: #{frame.method}" % @proc.frame_index
-    msg "  %-6s: %s" % frame.source_container
-    msg "  line  : %s" % @proc.frame_line
-    msg "  argc  : %d" % frame.argc
-    msg "  arity : %d" % frame.arity
-    msg "  type  : %s" % frame.type
-    msg "  offset: %d" % frame.pc_offset if frame.iseq
-    if %w(return c-return).member?(@proc.event)
-      ret_val = Trepan::Frame.value_returned(@proc.frame, @proc.event)
-      msg "  Return: %s" % ret_val
+    def print_frame_c_params(frame)
+        argc = frame.argc
+        # FIXME should figure out why exception is raised.
+        begin
+            if 0 == argc
+                return
+            elsif frame
+                1.upto(argc).map do
+                    |i|
+                    msg "  \t#{frame.sp(argc-i+3).inspect}"
+                end
+            else
+                msg "  \t??"
+            end
+        rescue NotImplementedError
+            msg "  \t??"
+        end
     end
-  end
 
+    def run(args)
+        if args.size == 2
+            frame = @proc.frame
+            frame_num = @proc.frame_index
+        else
+            frame_arg = args[2]
+            low, high = @proc.frame_low_high(nil)
+            opts={
+                :msg_on_error =>
+                "The '#{NAME}' command requires a frame number. Got: #{frame_arg}",
+                :min_value => low, :max_value => high
+            }
+            frame_num = @proc.get_an_int(frame_arg, opts)
+            frame, frame_num = @proc.get_frame(frame_num, true)
+        end
+        meth = frame.method rescue nil
+
+        section "Frame %2d: #{frame.method}" % @proc.frame_index
+        msg "  %-6s: %s" % frame.source_container if frame.source_container
+        msg "  line  : %s" % @proc.frame_line
+        msg "  argc  : %d" % frame.argc if frame.argc
+        msg "  arity : %d" % frame.arity if frame.arity
+        msg "  type  : %s" % frame.type
+        msg "  offset: %d" % frame.pc_offset if frame.iseq
+        msg "  label:  %s" % frame.label if frame.label unless meth
+        if frame.argc and frame.argc > 0
+            msg "  parameters:"
+            if meth and frame.type != 'IFUNC'
+                iseq = frame.iseq
+                if 'CFUNC' == frame.type
+                    print_frame_c_params(frame)
+                elsif iseq
+                    all_param_names(iseq).each do |param|
+                        msg "  \t#{param}"
+                    end
+                end
+            end
+        end
+
+        if %w(return c_return b_return).member?(@proc.event.to_s)
+            @proc.commands['info'].run(%W(info return))
+        end
+    end
 end
 
 if __FILE__ == $0