rb8-trepanning 0.1.3-universal-ruby-1.9.2

data/README.textile

@@ -0,0 +1,59 @@
+h1. rb8-trepanning a Ruby MRI 1.8 and 1.9 debugger using _ruby-debug-base_.
+
+This is a rewrite of _ruby-debug_, but still using _ruby-debug base_. 
+
+Right now, I've mostly tested on MRI 1.8, it sort of works on MRI 1.9.2 Ruby. Since the code is pure Ruby, it probably will work on other Rubies that have _ruby-debug-base_ installed to some degree.
+
+h2. Features
+
+* Syntax highlighting (if "coderay":http://coderay.rubychan.de/ and term-ansicolor are installed)
+* tab completion of commands
+* expanded on-line help
+* easy evaluation of the statement or expression in a statement about to be run (eval and eval? with no arguments)
+* cleaner, more modular and more testable code
+
+I realize the last item may not be of importance to many, but it's _very_ important as a developer of the code. 
+
+There is a "google group mailing list":http://groups.google.com/group/ruby-debugger for Ruby debuggers.
+
+h2. Installing (from git)
+
+bq.   $ git://github.com/rocky/rb8-trepanning.git
+   $ cd rb8-trepanning
+   $ rake test
+   $ rake install
+
+h2. Background
+
+_ruby-debug_ is cool, but it became getting harder to work on and to extend it while keeping compatibility. The code never started out from a test-driven development standpoint--tests were bolted on afterwards.
+
+Over time, I gained a better understanding of what was important (to me), and I learned how to do things better. So I decided to rewrite
+the code. This code base is a backport of the "trepanning debugger for
+Rubinius":https://github.com/rocky/rbx-trepanning/wiki which in turn
+is a port of the "trepanning debugger for a patched MRI YARV
+1.9.2":https://github.com/rocky/rb-trepanning/wiki which is a port of "a debugger for Python":http://code.google.com/p/pydbgr/ which is a port of ruby-debug)
+
+h2. Compatibility with ruby-debug
+
+Compatiblity between _ruby-debug_ and _trepanning_ is like compatibility between Ruby 1.8 and Ruby 1.9. 
+
+Here are some incompatibilities. Depending on your point of view, I hope you will find as I do that these are improvements:
+
+* "set autoeval" is on by default
+* ";;" rather than ";" separates debugger commands. This way, ";" can be used in a Ruby statement to evaluate.
+* Command names can be abbreviated if they are unique. For example "st" and "ste" are abbreviations of "step". To turn this off, "set abbrev off". 
+
+
+h2. Dependencies
+
+The debugger needs to work in more limited environments, so there are a number packages which are _optional_ but not required. They are:
+
+* _coderay_ and _term-ansicolor_ for syntax and terminal highlighting
+* _rb-readline_ (>= 0.4.0) on MRI 1.8 for better tab completion.
+* _ParseTree_ (>= 3.0.7) and its dependencies for showing method S-expressions 
+* _linecache_ (>= 0.45dev) for syntax highlighting
+
+Required dependencies are the same as ruby-debug:
+* _ruby-debug-base_ -- for run-time debugging support
+* _linecache_ or _linecache19_ -- for caching source-code lines and figuring out breakpoint lines)
+* _columnize_ -- for showing commands in columns

data/Rakefile

@@ -0,0 +1,215 @@
+#!/usr/bin/env rake
+# -*- Ruby -*-
+require 'rubygems'; require 'require_relative'
+
+ROOT_DIR = File.dirname(__FILE__)
+Gemspec_filename='trepan8.gemspec'
+require_relative './app/options'
+
+def gemspec
+  @gemspec ||= eval(File.read(Gemspec_filename), binding, Gemspec_filename)
+end
+
+require 'rake/gempackagetask'
+desc 'Build the gem'
+task :package=>:gem
+task :gem=>:gemspec do
+  Dir.chdir(ROOT_DIR) do
+    sh "gem build #{Gemspec_filename}"
+    FileUtils.mkdir_p 'pkg'
+    FileUtils.mv gemspec.file_name, 'pkg'
+  end
+end
+
+desc 'Install the gem locally'
+task :install => :gem do
+  Dir.chdir(ROOT_DIR) do
+    sh %{gem install --local pkg/#{gemspec.file_name}}
+  end
+end
+
+require 'rake/testtask'
+require 'rbconfig'
+
+def RbConfig.ruby
+  File.join(RbConfig::CONFIG['bindir'],  
+            RbConfig::CONFIG['RUBY_INSTALL_NAME'] + 
+            RbConfig::CONFIG['EXEEXT'])
+end unless defined? RbConfig.ruby
+
+def run_standalone_ruby_files(list, opts={})
+  puts '*' * 40
+  list.each do |ruby_file|
+    system(RbConfig.ruby, ruby_file)
+    p $?.exitstatus
+    break if $?.exitstatus != 0 && !opts[:continue]
+  end
+end
+
+def run_standalone_ruby_file(directory, opts={})
+  puts(('*' * 10) + ' ' + directory + ' ' + ('*' * 10))
+  Dir.chdir(directory) do
+    Dir.glob('*.rb').each do |ruby_file|
+      puts(('-' * 20) + ' ' + ruby_file + ' ' + ('-' * 20))
+      system(RbConfig.ruby, ruby_file)
+      break if $?.exitstatus != 0 && !opts[:continue]
+    end
+  end
+end
+
+desc 'Create a GNU-style ChangeLog via git2cl'
+task :ChangeLog do
+  system('git log --pretty --numstat --summary | git2cl > ChangeLog')
+end
+
+desc 'Test units - the smaller tests'
+Rake::TestTask.new(:'test:unit') do |t|
+  t.test_files = FileList['test/unit/**/test-*.rb']
+  # t.pattern = 'test/**/*test-*.rb' # instead of above
+  t.options = '--verbose' if $VERBOSE
+end
+
+desc 'Test functional - the medium-sized tests'
+Rake::TestTask.new(:'test:functional') do |t|
+  t.test_files = FileList['test/functional/**/test-*.rb']
+  t.options = '--verbose' if $VERBOSE
+end
+
+desc 'Test integration - end-to-end blackbox tests'
+Rake::TestTask.new(:'test:integration') do |t|
+  t.test_files = FileList['test/integration/**/test-*.rb']
+  t.options = '--verbose' if $VERBOSE
+end
+
+desc 'Test everything - unit tests for now.'
+task :test do
+  exceptions = %w(test:unit test:integration).collect do |task|
+    begin
+      Rake::Task[task].invoke
+      nil
+    rescue => e
+      e
+    end
+  end.compact
+  
+  exceptions.each {|e| puts e;puts e.backtrace }
+  raise 'Test failures' unless exceptions.empty?
+end
+
+desc 'Run each Ruby app file in standalone mode.'
+task :'check:app' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} app)))
+end
+
+desc 'Run each command in standalone mode.'
+task :'check:commands' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} processor command)))
+end
+
+desc 'Run each of the sub-sub commands in standalone mode.'
+task :'check:sub:commands' do
+  p "#{ROOT_DIR}/processor/command/*_subcmd/*_subcmd/*.rb"
+  Dir.glob("#{ROOT_DIR}/processor/command/*_subcmd").each do |sub_dir|
+    run_standalone_ruby_file(sub_dir)
+  end
+end
+
+desc 'Run each of the sub-sub commands in standalone mode.'
+task :'check:subsub:commands' do
+  subsub_files = FileList["#{ROOT_DIR}/processor/command/*_subcmd/*_subcmd/*.rb"]
+  run_standalone_ruby_files(subsub_files)
+end
+
+desc 'Run each processor Ruby file in standalone mode.'
+task :'check:lib' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} lib)))
+end
+
+desc 'Run each processor Ruby file in standalone mode.'
+task :'check:processor' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} processor)))
+end
+
+desc 'Run each processor Ruby file in standalone mode.'
+task :'check:unit' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} test unit)))
+end
+
+desc 'Run functional tests in standalone mode.'
+task :'check:functional' do
+  run_standalone_ruby_file(File.join(%W(#{ROOT_DIR} test functional)))
+end
+
+desc 'Run command parser grammar.'
+task :'check:cmd_parse' do
+  sh "kpeg --test --debug #{File.join(ROOT_DIR, %w(app cmd_parse.kpeg))}"
+end
+
+desc 'Generate command parser.'
+task :'cmd_parse' do
+  require 'tmpdir'
+  temp_file = 
+    File.join(Dir.tmpdir, 
+              Dir::Tmpname.make_tmpname(['cmd_parser_', '.rb'], nil))
+
+  sh('kpeg --name CmdParse --verbose --stand-alone  ' + 
+     "#{File.join(ROOT_DIR, %w(app cmd_parse.kpeg))} " + 
+     "--output #{temp_file}")
+end
+
+task :'check:integration' do
+  run_standalone_ruby_files(FileList['test/integration/**/test-*.rb'])
+end
+
+task :check => %w(check:lib check:processor check:commands).map{|c| c.to_sym}
+
+desc "Default action is same as 'test'."
+task :default => :test
+
+desc 'Generate the gemspec'
+task :generate do
+  puts gemspec.to_ruby
+end
+
+desc 'Validate the gemspec'
+task :gemspec do
+  gemspec.validate
+end
+
+# ---------  RDoc Documentation ------
+require 'rake/rdoctask'
+desc 'Generate rdoc documentation'
+Rake::RDocTask.new('rdoc') do |rdoc|
+  rdoc.rdoc_dir = 'doc'
+  rdoc.title    = "Trepanning #{Trepan::VERSION} Documentation"
+
+  rdoc.rdoc_files.include(%w(lib/*.rb 
+                          app/*.rb intf/*.rb io/*.rb
+                          bin/trepan8
+                         ))
+end
+
+desc 'Same as rdoc'
+task :doc => :rdoc
+
+task :clobber_package do
+  FileUtils.rm_rf File.join(ROOT_DIR, 'pkg')
+end
+
+task :clobber_rdoc do
+  FileUtils.rm_rf File.join(ROOT_DIR, 'doc')
+end
+
+desc 'Remove residue from running patch'
+task :rm_patch_residue do
+  FileUtils.rm_rf FileList['**/*.{rej,orig}'].to_a, :verbose => true
+end
+
+desc 'Remove ~ backup files'
+task :rm_tilde_backups do
+  FileUtils.rm_rf Dir.glob('**/*~'), :verbose => true
+  FileUtils.rm_rf Dir.glob('**/*.rbc'), :verbose => true
+end
+
+desc 'Remove built files'
+task :clean => [:clobber_package, :clobber_rdoc, :rm_patch_residue, :rm_tilde_backups]

data/app/.gitignore

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

data/app/cmd_parse.kpeg

@@ -0,0 +1,241 @@
+# -*- Ruby -*-
+
+%% {
+##################################################### 
+  # Structure to hold composite method names
+  SymbolEntry = Struct.new(:type, :name, :chain)
+
+
+  # Structure to hold position information
+  Position = Struct.new(:container_type, :container,
+                       :position_type,  :position)
+
+  # Structure to hold breakpoint information
+  Breakpoint = Struct.new(:position, :negate, :condition)
+
+  # Structure to hold list information
+  List = Struct.new(:position, :num)
+
+  DEFAULT_OPTS = {
+    :debug=>false, 
+    :file_exists_proc => Proc.new{|filename|
+        File.readable?(filename) && !File.directory?(filename)
+    }
+  }
+  def initialize(str, opts={})
+    @opts = DEFAULT_OPTS.merge(opts)
+    setup_parser(str, opts[:debug])
+    @file_exists_proc = @opts[:file_exists_proc]
+  end
+
+
+   }
+#####################################################
+
+      upcase_letter = /[A-Z]/
+    downcase_letter = /[a-z]/
+      suffix_letter = /[=!?]/ 
+             letter = upcase_letter
+                    | downcase_letter
+          id_symbol = letter | "_" | [0-9]
+
+
+# An variable or a method identifier
+# Examples: 
+#   var1
+#   my_var? 
+# But not: Variable or @var
+vm_identifier = < (downcase_letter | "_") id_symbol* suffix_letter? >
+    { 
+      SymbolEntry.new(:variable, text)
+    }
+
+# Examples: 
+#   var1
+# But not: my_var?, my_var! 
+variable_identifier = < (downcase_letter | "_") id_symbol* >
+    { 
+      SymbolEntry.new(:variable, text)
+    }
+
+# Examples: 
+#   MY_CONSTANT
+#   MyConstant_01
+# But not:
+#   MyConstant_01?
+constant_identifier = < upcase_letter id_symbol* >
+    { 
+      SymbolEntry.new(:constant, text)
+    }
+
+# Examples:
+#   $global_variable
+# We won't try for funny global names like $$, $? $:, $', etc
+global_identifier = < "$" (constant_identifier | variable_identifier) >
+    {
+      SymbolEntry.new(:global, text)
+    }
+
+# Examples: 
+#   Foo
+#   foo
+# But not:
+#   foo!, @foo, Class.foo
+local_internal_identifier = constant_identifier | variable_identifier
+
+# Examples: 
+#   Foo, foo, foo!
+#   foo
+# But not:
+#   @foo, Class.foo
+local_identifier = constant_identifier | vm_identifier
+
+# Example: @foo
+instance_identifier = < '@' local_identifier >
+    {
+      SymbolEntry.new(:instance, text)
+    }     
+
+
+# Example: @@foo
+classvar_identifier = ('@@' local_identifier:id )
+    {
+     SymbolEntry.new(:classvar, id)
+    }     
+
+identifier = global_identifier 
+       | instance_identifier 
+       | classvar_identifier 
+       | local_identifier 
+
+id_separator = < '::'|'.' > { text }
+
+# Like of class_module_chain *after* the first name. So we don't
+# allow sigils in the initial id. That is we don't allow:
+#   Class.@name1.@@name2.$name3  
+# But we do allow final sigils:
+#   class.name!, class.name=
+internal_class_module_chain = 
+    < local_internal_identifier:parent id_separator:sep  
+      internal_class_module_chain:child >
+      {
+         SymbolEntry.new(parent.type, text, [parent, child, sep])
+      }
+    | local_identifier
+
+
+# I think strict Ruby rules are that once one goes from :: to .
+# There is no going back. That is, A.B::C is invalid. 
+# 
+# Also I think method names can't be constants. But such 
+# subtleties we'll handle when we process the final structure.
+# Examples:
+#  Object, A::B, A.b @@foo.bar, $foo.bar.baz? 
+
+class_module_chain = 
+    < identifier:parent id_separator:sep  internal_class_module_chain:child >
+       {
+         SymbolEntry.new(parent.type, text, [parent, child, sep])
+      }
+    | identifier
+
+##############################################################
+# Location-specific things. This is used in conjunction with
+# method-like things above.
+          sp     = /[ \t]/
+           -     = sp+
+     dbl_escapes = "\\\"" { '"' }
+                 | "\\n"  { "\n" }
+                 | "\\t"  { "\t" }
+                 | "\\\\" { "\\" }
+     escapes    = "\\\"" { '"' }
+                 | "\\n"  { "\n" }
+                 | "\\t"  { "\t" }
+                 | "\\ "  { " " }
+                 | "\\:"  { ":" }
+                 | "\\\\" { "\\" }
+   dbl_seq       = < /[^\\"]+/ > { text }
+   dbl_not_quote = (dbl_escapes | dbl_seq)+:ary { ary }
+      dbl_string = "\"" dbl_not_quote:ary "\"" { ary.join }
+not_space_colon  = escapes 
+                 | < /[^ \t\n:]/ > { text }
+not_space_colons = ( not_space_colon )+:ary { ary.join }
+    filename    = dbl_string | not_space_colons
+file_pos_sep    = sp+ | ':'
+     integer    = </[0-9]+/> { text.to_i }
+ line_number    = integer
+
+vm_offset = '@' integer:int
+  {
+    Position.new(nil, nil, :offset, int)
+  }
+
+# Examples:
+#  @43
+#  5
+position = 
+  vm_offset 
+  | line_number:l { 
+  Position.new(nil, nil, :line, l) 
+}
+
+file_colon_line = file_no_colon:file &{ File.exist?(file) } ':' position:pos { 
+  Position.new(:file, file, pos.position_type, pos.position) 
+}
+
+# Examples:
+#   Myclass.fn @5  # bytecode offset 5 of fn
+#   Myclass.fn:@5  # same as above
+#   Myclass.fn 5   # line number 5 of fn
+# Note: Myclass.fn could be either a filename or a method name
+
+# The below ordering is important. 
+# 1. Numbers can't be method names they are first. If there's a 
+#    file with that name, later we'll allow quoting to indicate filename.
+# 2. filename:position can't also be a method so that's next
+# 3. It is possible a filename can be a method name, but we
+#    test using File.exist? so we want to put this first.
+#    Later "quoting" will skip the File.exist?
+# 4. Class module *with* a position is next and has to be before
+#    without a position, else we would stop early before handling
+#    the position.
+
+location = 
+   position 
+ | <filename>:file &{ @file_exists_proc.call(file) } file_pos_sep position:pos {
+      Position.new(:file, file, pos.position_type, pos.position)
+    }
+ | <filename>:file &{ @file_exists_proc.call(file) } {
+      Position.new(:file, file, nil, nil)
+    }
+ | class_module_chain?:fn file_pos_sep position:pos {
+      Position.new(:fn, fn, pos.position_type, pos.position)
+    }
+ | class_module_chain?:fn  {
+      Position.new(:fn, fn, nil, nil)
+    }
+
+if_unless = <"if" | "unless"> { text }
+condition = </.+/> { text}
+
+breakpoint_stmt_no_condition = location:loc  {
+  Breakpoint.new(loc, false, 'true')
+}
+
+# Note that the first word "break" is handled in the command.
+# Also, "break" with nothing else is handled there as well
+breakpoint_stmt = location:loc - if_unless:iu - condition:cond {
+     Breakpoint.new(loc, iu == 'unless', cond)
+}
+ | breakpoint_stmt_no_condition
+
+# Note that the first word "list", "list>" or handled in
+# the command.  Also, "list" with nothing else is
+# handled there as well
+list_special_targets = <'.' | '-'> { text }
+list_stmt = (list_special_targets | location):loc - (integer:int)? {
+  List.new(loc, int)
+}
+  | (list_special_targets | location):loc {
+  List.new(loc, nil)
+}