rb8-trepanning 0.1.3

data/processor/command/help.rb

@@ -0,0 +1,230 @@
+# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+require 'rubygems'; require 'require_relative'
+require_relative 'base/cmd'
+require_relative '../../app/complete'
+class Trepan::Command::HelpCommand < Trepan::Command
+  unless defined?(HELP)
+    NAME = File.basename(__FILE__, '.rb')
+    HELP = <<-HELP
+#{NAME} [command [subcommand]|expression]
+
+Without argument, print the list of available debugger commands.
+
+When an argument is given, it is first checked to see if it is command
+name. 'help where' gives help on the 'where' debugger command.
+
+If the environment variable $PAGER is defined, the file is
+piped through that command.  You'll notice this only for long help
+output.
+
+Some commands like 'info', 'set', and 'show' can accept an
+additional subcommand to give help just about that particular
+subcommand. For example 'help info line' give help about the
+info line command.
+
+See also 'examine' and 'whatis'.
+    HELP
+
+    ALIASES       = %w(?)
+    CATEGORIES    = {
+    'breakpoints' => 'Making the program stop at certain points',
+    'data'        => 'Examining data',
+    'files'       => 'Specifying and examining files',
+    'running'     => 'Running the program', 
+    'status'      => 'Status inquiries',
+    'support'     => 'Support facilities',
+    'stack'       => 'Examining the call stack',
+    'syntax'      => 'Debugger command syntax'
+    }
+    CATEGORY      = 'support'
+    NEED_STACK    = false
+    SHORT_HELP    = 'Print commands or give help for command(s)'
+
+    ROOT_DIR      = File.dirname(RequireRelative.abs_file)
+    HELP_DIR      = File.join(ROOT_DIR, 'help')
+  end
+
+  class Syntax
+    def initialize(syntax_files); @syntax_files = syntax_files; end
+    def complete(prefix)
+      matches = Trepan::Complete.complete_token(syntax_files, prefix)
+    end
+  end
+
+  def complete(prefix)
+    matches = Trepan::Complete.complete_token(CATEGORIES.keys + %w(* all) + 
+                                              @proc.commands.keys, prefix)
+    aliases = Trepan::Complete.complete_token_filtered(@proc.aliases, prefix, 
+                                                       matches)
+    (matches + aliases).sort
+  end    
+
+  def complete_token_with_next(prefix)
+    complete(prefix).map do |cmd| 
+      [cmd, @proc.commands.member?(cmd) ? @proc.commands[cmd] : nil]
+    end
+  end
+
+  # List the command categories and a short description of each.
+  def list_categories
+    section 'Help classes:'
+    CATEGORIES.keys.sort.each do |cat|
+      msg("%-13s -- %s" % [cat, CATEGORIES[cat]])
+    end
+    final_msg = '
+Type "help" followed by a class name for a list of help items in that class.
+Type "help aliases" for a list of current aliases.
+Type "help macros" for a list of current macros.
+Type "help *" for the list of all commands, macros and aliases.
+Type "help all" for the list of all commands.
+Type "help REGEXP" for the list of commands matching /^#{REGEXP}/.
+Type "help CLASS *" for the list of all commands in class CLASS.
+Type "help" followed by command name for full documentation.
+'
+    msg(final_msg)  
+  end
+
+  # This method runs the command
+  def run(args) # :nodoc
+    if args.size > 1
+      cmd_name = args[1]
+      if cmd_name == '*'
+        section 'All command names:'
+        msg columnize_commands(@proc.commands.keys.sort)
+        show_aliases  unless @proc.aliases.empty?
+        show_macros unless @proc.macros.empty?
+      elsif cmd_name =~ /^aliases$/i
+        show_aliases
+      elsif cmd_name =~ /^macros$/i
+        show_macros
+      elsif cmd_name =~ /^syntax$/i
+        show_command_syntax(args)
+      elsif cmd_name =~ /^all$/i
+        CATEGORIES.sort.each do |category|
+          show_category(category[0], [])
+        end
+      elsif CATEGORIES.member?(cmd_name)
+        show_category(args[1], args[2..-1])
+      elsif @proc.commands.member?(cmd_name) or @proc.aliases.member?(cmd_name)
+        real_name = 
+          if @proc.commands.member?(cmd_name) 
+            cmd_name
+          else
+            @proc.aliases[cmd_name]
+          end
+        cmd_obj = @proc.commands[real_name]
+        help_text = 
+          cmd_obj.respond_to?(:help) ? cmd_obj.help(args) : 
+          cmd_obj.class.const_get(:HELP)
+        if help_text
+          msg(help_text) 
+          if cmd_obj.class.constants.member?('ALIASES') and
+              args.size == 2
+            msg "Aliases: #{cmd_obj.class.const_get(:ALIASES).join(', ')}"
+          end
+        end
+      elsif @proc.macros.member?(cmd_name)
+        msg "#{cmd_name} is a macro which expands to:"
+        msg "  #{@proc.macros[cmd_name]}", {:unlimited => true}
+      else 
+        matches = @proc.commands.keys.grep(/^#{cmd_name}/).sort rescue []
+        if matches.empty?
+          errmsg("No commands found matching /^#{cmd_name}/. Try \"help\".")
+        else
+          section "Command names matching /^#{cmd_name}/:"
+          msg columnize_commands(matches.sort)
+        end
+      end
+    else
+      list_categories
+    end
+  end
+
+  def show_aliases
+    section 'All alias names:'
+    msg columnize_commands(@proc.aliases.keys.sort)
+  end
+
+  # Show short help for all commands in `category'.
+  def show_category(category, args)
+    
+    if args.size == 1 && args[0] == '*'
+      section "Commands in class %s:" % category
+      
+      cmds = @proc.commands.keys.select do |cmd_name|
+        category == @proc.commands[cmd_name].category
+      end.sort
+      width = settings[:maxwidth]
+      return columnize_commands(cmds)
+    end
+    
+    msg('')
+    section "Command class: %s" % category
+    msg('')
+    @proc.commands.keys.sort.each do |name|
+      next if category != @proc.commands[name].category
+      msg("%-13s -- %s" % [name, @proc.commands[name].short_help])
+    end
+  end
+  
+  def syntax_files
+    @syntax_files ||= Dir.glob(File.join(HELP_DIR, '*.txt')).map do |txt| 
+      basename = File.basename(txt, '.txt')
+    end
+  end
+  
+  def show_command_syntax(args)
+    if args.size == 2
+      @syntax_summary_help ||= {}
+      section "List of syntax help"
+      syntax_files.each do |name|
+        @syntax_summary_help[name] ||= 
+          File.open(File.join(HELP_DIR, "#{name}.txt")).readline.chomp
+        msg "  %-8s -- %s" % [name, @syntax_summary_help[name]]
+      end
+    else
+      args[2..-1].each do |name|
+        if syntax_files.member?(name)
+          @syntax_help ||= {}
+          @syntax_help[name] = 
+            File.open(File.join(HELP_DIR, "#{name}.txt")).readlines[2..-1].join
+          section "Debugger syntax for a #{name}:"
+          msg @syntax_help[name]
+        else
+          errmsg "No syntax help for #{name}"
+        end
+      end
+    end
+  end
+
+  def show_macros
+    section 'All macro names:'
+    msg columnize_commands(@proc.macros.keys.sort)
+  end
+
+end
+
+if __FILE__ == $0
+  # Demo it.
+  require_relative '../mock'
+  dbgr, cmd = MockDebugger::setup
+
+  cmd.run %W(#{cmd.name} help)
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} *)
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} fdafsasfda)
+  puts '=' * 40
+  cmd.run [cmd.name]
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} support)
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} support *)
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} s.*)
+  puts '=' * 40
+  cmd.run %W(#{cmd.name} s<>)
+  puts '=' * 40
+  p cmd.complete('br')
+  p cmd.complete('un')
+end

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,58 @@
+Overall Debugger Command Syntax
+
+If the first non-blank character of a line starts with #, 
+the command is ignored. 
+
+If a line starts with ! in column one, the line is eval'd. 
+
+If the command you want Ruby to eval uses ! 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.
+
+Resolving a command name involves possibly 4 steps. Some steps may be
+omitted depending on early success or some debugger settings:
+
+1. 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. See the "help macros" for
+help on how to define macros, and "info macro" for current macro
+definitions. 
+
+2. The leading token is next looked up in the debugger alias table and
+the name may be substituted there. See "help alias" for how to define
+aliases, and "show alias" for the current list of aliases.
+
+3. After the above, The leading token is looked up a table of debugger
+commands. If an exact match is found, the command name and arguments
+are dispatched to that command. Otherwise, we may check to see the the
+token is a unique prefix of a valid command. For example, "dis" is not
+a unique prefix because there are both "display" and "disable"
+commands, but "disp" is a unique prefix. You can allow or disallow
+abbreviations for commands using "set abbrev". The default is
+abbreviations are on.
+
+4. If after all of the above, we still don't find a command, the line
+may be evaluated as a Ruby statement in the current context of the
+program at the point it is stoppped. However this is done only if
+"autoeval" is on.  (It is on by default.)
+
+If "auto eval" is not set on, or if running the Ruby statement
+produces an error, 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.
+
+See also: 
+  "help syntax examples"
+  "help syntax suffix"

data/processor/command/help/examples.txt

@@ -0,0 +1,16 @@
+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 "show" variants of the above "set"
+commands.

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/help/suffixes.txt

@@ -0,0 +1,17 @@
+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 help on the commands listed above for the specific meaning of the suffix.

data/processor/command/info.rb

@@ -0,0 +1,28 @@
+# -*- coding: utf-8 -*-
+# Copyright (C) 2010, 2011 Rocky Bernstein <rockyb@rubyforge.net>
+require 'rubygems'; require 'require_relative'
+require_relative 'base/submgr'
+
+class Trepan::Command::InfoCommand < Trepan::SubcommandMgr
+  unless defined?(HELP)
+    HELP =
+'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 "info" for a list of "info" subcommands and what they do.
+Type "help info *" for just a list of "info" subcommands.
+'
+
+    ALIASES       = %w(i)
+    CATEGORY      = 'status'
+    NAME          = File.basename(__FILE__, '.rb')
+    SHORT_HELP    = 'Information about debugged program and its environment'
+  end
+end
+
+if __FILE__ == $0
+  require_relative '../mock'
+  dbgr, cmd = MockDebugger::setup
+end