trepanning 0.1.0 → 0.1.1

data/processor/command/help/.gitignore

@@ -0,0 +1 @@
+/*~

data/processor/command/help/README

@@ -0,0 +1,10 @@
+Files in this directory are help for "help syntax". 
+
+A list of sub-names is obtained by Dir.glob('*.txt') in this
+directory.
+
+Each file name without the trailing ".txt' is the name of the help
+subcategory under "help syntax". 
+
+The first line in the file is a summary shown in help summary. 
+Lines 3 on are shown as help text.

data/processor/command/help/command.txt

@@ -0,0 +1,48 @@
+overall debugger command syntax
+
+Command tokenization syntax is very simple-minded. 
+
+If a line starts with #, the command is ignored. 
+If a line starts with !, the line is eval'd. 
+
+If the command you want eval'd uses the Ruby ! initially, add that
+after the first ! or start the line with a space.
+
+Commands are split at whereever ;; appears. This process disregards
+any quotes or other symbols that have meaning in Ruby. The strings
+after the leading command string are put back on a command queue. 
+
+Within a single command, tokens are then white-space split. Again,
+this process disregards quotes or symbols that have meaning in Ruby.
+Some commands like 'eval', 'macro', and 'break' have access to the
+untokenized string entered and make use of that rather than the
+tokenized list.
+
+The leading token is first looked up in the macro table. If it is in
+the table, the expansion is replaces the current command and possibly
+other commands pushed onto a command queue.  Next, the leading token is
+looked up in the debugger alias table and the name may be substituted
+there. Finally, the leading token is looked up in the debugger alias
+table. If a match is found, the command name and arguments are
+dispatched to the command object that process the command.
+
+If the command is not found and "auto eval" is set on, then the
+command is eval'd in the context that the program is currently stopped
+at. If "auto eval" is not set on, then we display an error message
+that the entered string is "undefined".
+
+If you want irb-like command-processing, it's possible to go into an
+irb shell with the "irb" command. It is also possible to arrange going
+into an irb shell every time you enter the debugger.
+
+Examples:
+
+# This line does nothing. It is a comment
+s    # by default, this is an alias for the "step" command
+!s   # shows the value of variable step. 
+!!s  # Evaluates !s (or "not s"). The first ! is indicates evaluate.
+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 "alias", "irb", "set auto eval", and "set auto irb".

data/processor/command/help/filename.txt

@@ -0,0 +1,40 @@
+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. Some
+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>
+   \" => "
+   \\ => \
+
+Here are some examples of quoted filenames:
+
+  "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.txt

@@ -0,0 +1,37 @@
+syntax for source code locations; e.g. used "list" and "break"
+
+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" (without the quotes) 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/info_subcmd/.gitignore

@@ -0,0 +1 @@
+/*~

data/processor/command/info_subcmd/breakpoints.rb

@@ -5,8 +5,8 @@ require_relative '../base/subcmd'
 class Trepan::Subcommand::InfoBreakpoints < Trepan::Subcommand
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
-    HELP         = <<EOH
-info breakpoints [num1 ...] [verbose]
+    HELP         = <<-EOH
+#{PREFIX.join(' ')} [num1 ...] [verbose]
 
 Show status of user-settable breakpoints. If no breakpoint numbers are
 given, the show all breakpoints. Otherwise only those breakpoints
@@ -20,11 +20,10 @@ The "enb" column indicates whether the breakpoint is enabled.
 
 The "Where" column indicates where the breakpoint is located.
 EOH
-
-    MIN_ABBREV   = 'br'.size 
-    SHORT_HELP = "Status of user-settable breakpoints"
+    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  '
@@ -48,7 +47,8 @@ EOH
     msg("\t#{other_loc}") if verbose
 
     if bp.condition && bp.condition != 'true'
-      msg("\tstop only if %s" % bp.condition)
+      msg("\tstop %s %s" %
+          [bp.negate ? "unless" : "only if", bp.condition])
     end
     if bp.ignore > 0
       msg("\tignore next %d hits" % bp.ignore)
@@ -105,7 +105,7 @@ EOH
       msg('No breakpoints.')
     else
       # There's at least one
-      msg("Num Type          Disp Enb Where")
+      section("Num Type          Disp Enb Where")
       if show_all
         bpmgr.list.each do |bp|
           bpprint(bp, verbose)
@@ -133,7 +133,7 @@ if __FILE__ == $0
   require_relative '../../mock'
   name = File.basename(__FILE__, '.rb')
   dbgr, cmd = MockDebugger::setup('info')
-  subcommand = Trepan::Subcommand::InfoBreak.new(cmd)
+  subcommand = Trepan::Subcommand::InfoBreakpoints.new(cmd)
 
   puts '-' * 20
   subcommand.run(%w(info break))

data/processor/command/info_subcmd/{file.rb → files.rb}

@@ -1,24 +1,32 @@
 # -*- coding: utf-8 -*-
 # Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
 require 'linecache'
+require 'columnize'
 require_relative '../base/subcmd'
 require_relative '../../../app/file'
+require_relative '../../../app/complete'
 
-class Trepan::Subcommand::InfoFile < Trepan::Subcommand
+class Trepan::Subcommand::InfoFiles < Trepan::Subcommand
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
-    DEFAULT_FILE_ARGS = %w(size sha1)
+    DEFAULT_FILE_ARGS = %w(size mtime sha1)
 
-    HELP =
-"info file [{FILENAME|.} [all | brkpts | iseq | sha1 | size | stat]]
+    HELP = <<-EOH
+#{CMD} [{FILENAME|.|*} [all|ctime|brkpts|mtime|sha1|size|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. Sub options which can be shown about a file are:
+the program is running, then the current file associated with the
+current stack entry is used. Giving . has the same effect. 
+
+Given * 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.
@@ -26,18 +34,49 @@ stat   -- File.stat 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
+EOH
     MIN_ABBREV   = 'fi'.size  # Note we have "info frame"
     NEED_STACK   = false
   end
 
+  # completion %w(all brkpts iseq sha1 size stat)
+
   include Trepanning
+
+  def file_list
+    (LineCache.class_variable_get('@@file_cache').keys +
+     LineCache.class_variable_get('@@file2file_remap').keys).uniq
+  end
+  def complete(prefix)
+    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 
+    if '*' == args[2]
+      section 'Canonic Files names cached:'
+      primary = LineCache.class_variable_get('@@file_cache')
+      remap = LineCache.class_variable_get('@@file2file_remap')
+      msg columnize_commands(remap.keys.uniq.sort)
+      names = remap.keys - primary.keys
+      unless names.empty?
+        section 'Non-canonic names cached:'
+        msg columnize_commands(names.sort)
+      end
+      return
+    end
     filename = 
       if '.' == args[2]
         if not @proc.frame
@@ -45,36 +84,49 @@ If no sub-options are given #{DEFAULT_FILE_ARGS.join(' ')} are assumed.
           return false
           nil
         else
-          File.expand_path(@proc.frame.source_container[1])
+          frame_file = @proc.frame.source_container[1]
+          LineCache::map_file(frame_file) || File.expand_path(frame_file)
         end
       else
         args[2]
       end
     args += DEFAULT_FILE_ARGS if args.size == 3
 
-    m = filename + ' is'
-    canonic_name = LineCache::map_file(filename)
+    m = filename
+    canonic_name = @proc.canonic_file(filename)
+    canonic_name = LineCache::map_file(canonic_name) || canonic_name
     if LineCache::cached?(canonic_name)
-      m += " cached in debugger"
+      m += " is cached in debugger"
       if canonic_name != filename
-        m += (' as:' + canonic_name)
+        m += (" as:\n  " + canonic_name)
       end
       m += '.'
       msg(m)
     elsif !(matches = find_scripts(filename)).empty?
       if (matches.size > 1)
         msg("Multiple files found:")
-        matches.each { |match_file| msg "\t%s" % match_file }
+        matches.sort.each { |match_file| msg "\t%s" % match_file }
         return
       else
         msg('File "%s" just now cached.' % filename)
         LineCache::cache(matches[0])
-        LineCache::remap_file(matches[0], filename)
+        LineCache::remap_file(filename, matches[0])
         canonic_name = matches[0]
       end
     else
-      msg(m + ' not cached in debugger.')
-      return
+      matches = file_list.select{|try| try.end_with?(filename)}
+      if (matches.size > 1)
+        msg("Multiple files found ending filename string:")
+        matches.sort.each { |match_file| msg "\t%s" % match_file }
+        return
+      elsif 1 == matches.size
+        canonic_name = LineCache::map_file(matches[0])
+        m += " matched debugger cache file:\n  "  + canonic_name
+        msg m
+      else
+        msg(m + ' is not cached in debugger.')
+        return
+      end
     end
     seen = {}
     args[3..-1].each do |arg|
@@ -98,13 +150,21 @@ If no sub-options are given #{DEFAULT_FILE_ARGS.join(' ')} are assumed.
       if %w(all brkpts).member?(arg)
         unless seen[:brkpts]
           msg("Possible breakpoint line numbers:")
-          lines = LineCache::trace_line_numbers(canonic_name)
+          lines = LineCache.trace_line_numbers(canonic_name)
           fmt_lines = columnize_numbers(lines)
           msg(fmt_lines)
         end
         processed_arg = seen[:brkpts] = true
       end
 
+      if %w(all ctime).member?(arg)
+        unless seen[:ctime]
+          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) 
         unless seen[:iseq]
           if SCRIPT_ISEQS__.member?(canonic_name)
@@ -119,6 +179,14 @@ If no sub-options are given #{DEFAULT_FILE_ARGS.join(' ')} are assumed.
         processed_arg = seen[:iseq] = true
       end
 
+      if %w(all mtime).member?(arg)
+        unless seen[:mtime]
+          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)
@@ -141,21 +209,18 @@ if __FILE__ == $0
     load(__FILE__)
   else    
     require_relative '../../mock'
-    require_relative '../../subcmd'
-    name = File.basename(__FILE__, '.rb')
-    # FIXME: DRY the below code
-    dbgr, cmd = MockDebugger::setup('info')
-    subcommand = Trepan::Subcommand::InfoFile.new(cmd)
-    testcmdMgr = Trepan::Subcmd.new(subcommand)
-    
+    cmd = MockDebugger::sub_setup(Trepan::Subcommand::InfoFiles, false)
     [%w(info file nothere),
      %w(info file .),
+     %w(info file *),
      %w(info file),
      %w(info file file.rb),
+    %w(info file citrus/file.rb),
      %w(info file . all),
-     %w(info file . lines size sha1 sha1)].each do |args|
-      subcommand.run(args)
+     %w(info file . brkpts bad size sha1 sha1)].each do |args|
+      cmd.run(args)
       puts '-' * 40
     end
+    p cmd.complete('')
   end
 end

data/processor/command/info_subcmd/frame.rb

@@ -5,18 +5,51 @@ require_relative '../base/subcmd'
 class Trepan::Subcommand::InfoFrame < Trepan::Subcommand
   unless defined?(HELP)
     Trepanning::Subcommand.set_name_prefix(__FILE__, self)
-    HELP         = 'Show all information about the selected frame'
+    HELP = <<-EOH
+#{CMD} 
+
+Show information about the selected frame. The fields we list are:
+
+* A source container and name (e.g. "file" or "string" and the value)
+* 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 return value if the frame is at a return point
+* 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')
+
+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"
     NEED_STACK   = true
+    SHORT_HELP   = 'Show information about the selected frame'
   end
 
   def run(args)
     frame = @proc.frame
-    msg("Line %s of %s at PC offset %d, type: %s" %
-        [@proc.frame_line, frame.source_container[1], frame.pc_offset, 
-         frame.type])
-    if @proc.event == 'return'
-      msg("Return value class: #{@proc.frame.sp(1).class}")
+    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
     end
   end
 
@@ -25,14 +58,7 @@ end
 if __FILE__ == $0
   # Demo it.
   require_relative '../../mock'
-  require_relative '../../subcmd'
-  name = File.basename(__FILE__, '.rb')
-
-  # FIXME: DRY the below code
   dbgr, cmd = MockDebugger::setup('info')
-  subcommand = Trepan::Subcommand::InfoFrame.new(cmd)
-  testcmdMgr = Trepan::Subcmd.new(subcommand)
-
-  name = File.basename(__FILE__, '.rb')
-  subcommand.summary_help(name)
+  cmd = MockDebugger::sub_setup(Trepan::Subcommand::InfoFrame, false)
+  cmd.run(cmd.prefix)
 end