rexpl 0.0.1

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+*.rbc
+doc/*
+.yardoc/*

data/.rvmrc

@@ -0,0 +1 @@
+rvm --create use rbx-2.0.0pre@rexpl

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in rexpl.gemspec
+gemspec

data/Rakefile

@@ -0,0 +1,24 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+desc "Run Rexpl tests"
+Rake::TestTask.new do |t|
+  t.libs << "test"
+  t.test_files = FileList['test/**/*_test.rb']
+  t.verbose = true
+end
+
+require 'yard'
+YARD::Rake::YardocTask.new(:docs) do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options = ['-m', 'markdown', '--no-private', '-r', 'Readme.md', '--title', 'Rexpl documentation']
+end
+task :doc => [:docs]
+
+desc "Generate and open class diagram (needs Graphviz installed)"
+task :graph do |t|
+ `bundle exec yard graph -d --full --no-private | dot -Tpng -o graph.png && open graph.png`
+end
+
+task :default => [:test]

data/Readme.md

@@ -0,0 +1,67 @@
+# rexpl
+
+**rexpl** is a sandbox to experiment and play with the [Rubinius](http:://rubini.us)
+Virtual Machine and its bytecode instructions. It comes wrapped in a REPL
+(Read-Eval-Print Loop) à la IRB, so that anytime you can open a terminal,
+fire up **rexpl**, and start playing with instant feedback.
+
+This intends to be a fun tool to use when learning how to use Rubinius
+bytecode instructions, for example when bootstraping a new language targeting
+the Rubinius VM for the first time.
+
+Its main feature is **stack introspection**, which means you can inspect
+what the stack looks like after each step of your instruction set.
+
+## How to use it?
+
+Needless to say, **rexpl** runs only on Rubinius. Thus, your first step is to
+install it. Go to the [Rubinius website](http://rubini.us) to find how, or if
+you are using RVM, just follow [this instructions](http://beginrescueend.com/interpreters/rbx/).
+
+    $ gem install rexpl
+    $ rexpl
+
+Now you should see a welcome banner and an IRB-like prompt, and you're good to
+go! Just start typing some [VM instructions](http://rubini.us/doc/en/virtual-machine/instructions/)
+and see what happens!
+
+There are three extra commands to take advantage of the stack introspection:
+
+* `list` lists the instruction set of the current program.
+* `reset` empties the instruction set and starts a new program.
+* `draw` prints a visual representation of the stack after each instruction of
+your program.
+
+## When to use it?
+
+Imagine you are bootstrapping a new language targeting the Rubinius VM and you
+just implemented a particular AST node, but when you try to run the tests, you
+keep getting nasty stack validation errors. Net stack underflow? What the heck
+does this even mean? Where the hell is that extra `pop`? Did this or that
+instruction consume stack? Or maybe produce it? Oh fuck it, let's go fishing.
+
+Don't panic. You always have your friends pen and paper ready to help you out,
+Read through the source code, and knowing what each instruction does, try to
+follow along and draw what the stack looks like at each step (does that sound
+familiar to you?). Or just fire up **rexpl**.
+
+## Resources
+
+Documentation is online here:
+
+* [Rexpl documentation](http://rdoc.info/github/txus/rexpl/master/frames)
+
+##Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  If you want to have your own version, that is fine but bump version
+  in a commit by itself I can ignore when I pull.
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 Josep M. Bach. See LICENSE for details.

data/bin/rexpl

@@ -0,0 +1,3 @@
+#!/usr/bin/env rbx
+require 'rexpl'
+Rexpl::Environment.run

data/lib/rexpl.rb

@@ -0,0 +1,15 @@
+# rexpl is an interactive bytecode console for the Rubinius VM.
+#
+# **rexpl** is a sandbox to experiment and play with the [Rubinius](http://rubini.us)
+# Virtual Machine and its bytecode instructions. It comes wrapped in a REPL
+# (Read-Eval-Print Loop) à la IRB, so that anytime you can open a terminal,
+# fire up **rexpl**, and start playing with instant feedback.
+#
+module Rexpl
+end
+
+require 'rexpl/version'
+require 'rexpl/generator_proxy'
+require 'rexpl/generator_methods'
+require 'rexpl/output'
+require 'rexpl/environment'

data/lib/rexpl/environment.rb

@@ -0,0 +1,31 @@
+module Rexpl
+  # This class represents the Environment holding a {GeneratorProxy} instance
+  # exposing the main entry point as a class method.
+  #
+  class Environment
+    @@generator = GeneratorProxy.new
+
+    class << self
+      # Fires up the REPL. This is the program's main entry point.
+      def run
+        Output.print_banner
+
+        while (Output.print_prompt; input = gets)
+          @@generator.instance_eval input.chomp
+
+          # After each new instruction, evaluate all of them.
+          dynamic_method(:run) do |g|
+            @@generator.visit(g)
+            if g.size == 0
+              g.push_nil
+            else
+              g.print_debug_info
+            end
+            g.ret
+          end
+          new.run
+        end
+      end
+    end
+  end
+end

data/lib/rexpl/generator_methods.rb

@@ -0,0 +1,43 @@
+module Rexpl
+  # Extends the Rubinius::Generator class with some utility methods used by
+  # Replx.
+  #
+  module GeneratorMethods
+    # Prints the topmost element on the stack and the stack's current size.
+    #
+    # Calling this method neither consumes nor produces stack, it's just used
+    # for debugging the current state.
+    def print_debug_info
+      initial_size = size
+      dup
+      push_const :Rexpl
+      find_const :Output
+      swap_stack
+      send :inspect, 0, true
+      push_literal initial_size
+      swap_stack
+      send :print_debug_info, 2, true 
+      pop
+    end
+
+    # Returns an array with all the elements currently in the stack.
+    #
+    # Calling #return_stack increases by 1 the stack size (being the topmost
+    # element an array containing a duplicate of every other element in the
+    # stack).
+    def return_stack
+      initial_size = size
+      dup_many initial_size
+      make_array initial_size
+    end
+
+    # Returns the current size of the stack.
+    #
+    # @return [Fixnum] the current size of the stack.
+    def size
+      @current_block.instance_eval { @stack }
+    end
+  end
+end
+
+Rubinius::Generator.__send__ :include, Rexpl::GeneratorMethods

data/lib/rexpl/generator_proxy.rb

@@ -0,0 +1,116 @@
+module Rexpl
+  # This class acts as a Proxy between the user and an actual Generator.
+  #
+  class GeneratorProxy
+    protected_methods = %w(class to_s inspect instance_eval tainted?)
+    # Undefine every method so that this class acts as an actual proxy.
+    instance_methods.each do |method|
+      unless method.to_s =~ /^_/ || protected_methods.include?(method.to_s)
+        undef_method method
+      end
+    end
+
+    attr_accessor :instructions
+
+    # Initializes a new {GeneratorProxy} instance with an empty instruction
+    # set.
+    def initialize
+      @instructions = []
+    end
+
+    # Swallows every message passed onto the instance and stores it in the
+    # instruction set.
+    def method_missing(method, *args)
+      @instructions << [method, *args]
+      nil
+    end
+
+    # Applies the set of instructions to an actual generator.
+    #
+    # It captures errors in case an instruction is unknown or called with wrong
+    # arguments.
+    #
+    # @param [Rubinius::Generator] generator the generator onto which apply the
+    #   instructions.
+    #
+    # @example
+    #
+    #   proxy = Rexpl::GeneratorProxy.new
+    #   proxy.push 83
+    #   proxy.push_literal 'bar'
+    #
+    #   dynamic_method(:foo) do |g|
+    #     proxy.visit(g)
+    #     g.ret
+    #   end
+    #     
+    def visit(generator)
+      last_instruction = nil
+      begin
+        @instructions.each do |instruction|
+          last_instruction = instruction
+          generator.__send__ *instruction
+        end
+      rescue NameError, ArgumentError=>e
+        puts "[ERROR]: #{e}"
+        @instructions.delete(last_instruction)
+      end
+    end
+
+    # Empties the instruction set.
+    def reset
+      Output.print_reset
+      initialize
+    end
+
+    # Prints a list of the current instruction set.
+    def list
+      puts
+      @instructions.each_with_index do |instruction, idx|
+        Output.print_instruction instruction, idx
+      end
+      puts
+    end
+
+    # Visually represents the state of the stack after each instruction is ran.
+    def draw
+      instructions = @instructions.dup
+      klass = Class.new do
+        dynamic_method(:draw) do |g|
+
+          instructions.each_with_index do |instruction, idx|
+            # Execute the instruction
+            before = g.size
+            g.__send__ *instruction
+            after = g.size
+
+            # Print the instruction header
+            produced = after - before
+            verb = 'produced'
+            if produced < 0
+              verb = 'consumed'
+              produced = produced.abs
+            end
+            g.push_self
+            g.push_literal "[#{idx}] [#{instruction.first} #{instruction[1..-1].map(&:inspect).join(', ')}] #{verb} #{produced} stack, size is now #{after}"
+            g.send :puts, 1, true
+            g.pop
+
+            # Visually print the entire stack
+            g.return_stack
+            g.push_const :Rexpl
+            g.find_const :Output
+            g.swap_stack
+            g.send :print_stack, 1, true
+            g.pop
+          end
+
+          g.push_nil
+          g.ret
+        end
+      end
+
+      klass.new.draw
+    end
+  end
+end

data/lib/rexpl/output.rb

@@ -0,0 +1,72 @@
+require 'ansi'
+
+module Rexpl
+  # Utility module to abstract output-related stuff, like printing banners or
+  # graphically representing stacks.
+  class Output
+    extend ANSI::Code
+
+    class << self
+      # Prints the welcome banner and a bit of instructions on how to use the
+      # interactive console.
+      def print_banner
+        puts
+        puts bold { red { "rexpl" } } + bold { " v#{Rexpl::VERSION}" } + " - interactive bytecode console for Rubinius"
+        puts bold { "--------------------------------------------------------" }
+        puts
+        print_rationale
+      end
+
+      # Prints the console prompt.
+      def print_prompt
+        print bold { '> ' }
+      end
+
+      # Prints a message indicating that the instruction set has been resetted.
+      def print_reset
+        puts "Reseted!"
+      end
+
+      # Prints the current size of the stack and the topmost value.
+      def print_debug_info(size, value)
+        puts "=> [" + bold { "Stack size: #{size}"} + "] " + "[" + bold { "Topmost value: #{value}" } + "]"
+      end
+
+      # Prints an instruction in a single row.
+      def print_instruction(instruction, idx)
+        puts bold { "[" } + blue { idx.to_s } + bold { "]" } + ": " + green { instruction.first } + " " + bold { instruction[1..-1].map(&:inspect) }
+      end
+
+      # Prints a stack out of an array of stack cells.
+      #
+      # @param [Array] cells the cells of the stack containing its values.
+      def print_stack(cells)
+        puts
+        puts "\t#{bold { 'Current stack' }.center(33, ' ')}"
+        puts "\t" + blue { "-------------------------" }
+        cells.reverse.each do |element|
+          puts "\t#{blue {"|"} }#{bold { element.inspect.center(23, ' ') }}#{blue {"|"}}"
+          puts "\t" + blue { "-------------------------" }
+        end
+        puts
+      end
+
+      # Prints a little readme to get people started when firing up the
+      # interactive console.
+      def print_rationale
+        puts "To start playing, just start typing some Rubinius VM instructions."
+        puts "You can find a complete list with documentation here:"
+        puts
+        puts "\thttp://rubini.us/doc/en/virtual-machine/instructions/"
+        puts
+        puts "To introspect the program you are writing, use the following commands,"
+        puts "or type " + bold { "exit" } + " to exit:"
+        puts
+        puts "  " + bold { "list" } + " lists the instruction set of the current program."
+        puts "  " + bold { "reset" } + " empties the instruction set and starts a new program."
+        puts "  " + bold { "draw" } + " prints a visual representation of the stack after each instruction."
+        puts
+      end
+    end
+  end
+end

data/lib/rexpl/version.rb

@@ -0,0 +1,4 @@
+module Rexpl
+  # The current rexpl version.
+  VERSION = "0.0.1"
+end

data/rexpl.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "rexpl/version"
+
+Gem::Specification.new do |s|
+  s.name        = "rexpl"
+  s.version     = Rexpl::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Josep M. Bach"]
+  s.email       = ["josep.m.bach@gmail.com"]
+  s.homepage    = "http://github.com/txus/rexpl"
+  s.summary     = %q{Rexpl is an interactive bytecode console for Rubinius}
+  s.description = %q{Rexpl is an interactive bytecode console for Rubinius}
+
+  s.rubyforge_project = "rexpl"
+
+  s.add_runtime_dependency "ansi"
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "mocha"
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'bluecloth'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/test/rexpl/environment_test.rb

@@ -0,0 +1,23 @@
+require 'test_helper'
+
+class EnvironmentTest < MiniTest::Unit::TestCase
+
+  def test_run
+    Rexpl::Output.stubs(:print_banner)
+    Rexpl::Output.stubs(:print_prompt)
+
+    Rexpl::Environment.expects(:gets).times(3).returns('noop', 'push 3', nil)
+
+    proxy = mock
+    Rexpl::Environment.class_variable_set(:@@generator, proxy)
+
+    proxy.expects(:instance_eval).with('noop')
+    proxy.expects(:instance_eval).with('push 3')
+    proxy.expects(:visit).with do |g|
+      assert_kind_of Rubinius::Generator, g
+    end.twice
+
+    Rexpl::Environment.run
+  end
+
+end

data/test/rexpl/generator_methods_test.rb

@@ -0,0 +1,38 @@
+require 'test_helper'
+
+class GeneratorMethodsTest < MiniTest::Unit::TestCase
+
+  def test_print_debug_info
+    klass = Class.new do
+      dynamic_method :foo do |g|
+        g.push 5
+        g.push 6
+        g.print_debug_info
+        g.ret
+      end
+    end
+    Rexpl::Output.expects(:print_debug_info).with(2, '6')
+    result = klass.new.foo
+    assert_equal result, 6
+  end
+
+  def test_return_stack_returns_an_array_with_stack_cells
+    klass = Class.new do
+      dynamic_method :foo do |g|
+        g.push 3
+        g.push 6
+        g.return_stack
+        g.ret
+      end
+    end
+    assert_equal klass.new.foo, [3, 6]
+  end
+
+  def test_size_returns_size_of_the_stack
+    g = Rubinius::Generator.new
+    g.push 3
+    g.push 5
+    assert_equal 2, g.size
+  end
+
+end

data/test/rexpl/generator_proxy_test.rb

@@ -0,0 +1,64 @@
+require 'test_helper'
+
+class GeneratorProxyTest < MiniTest::Unit::TestCase
+
+  def setup
+    @proxy = Rexpl::GeneratorProxy.new
+  end
+
+  def test_swallows_everything_with_its_args
+    @proxy.push 3
+    @proxy.foo
+    @proxy.bar
+    @proxy.whatever
+    @proxy.biwinning
+
+    assert_equal 5, @proxy.instructions.size
+    assert_equal [:push, 3], @proxy.instructions.first
+  end
+
+  def test_visit_executes_the_instructions
+    @proxy.push 3
+    @proxy.push_literal 'hey'
+
+    g = Rubinius::Generator.new
+    g.expects(:push).with(3)
+    g.expects(:push_literal).with('hey')
+
+    @proxy.visit(g) 
+  end
+
+  def test_reset
+    @proxy.push 3
+    @proxy.push 5
+
+    Rexpl::Output.expects(:print_reset)
+
+    @proxy.reset
+
+    assert_equal 0, @proxy.instructions.size
+  end
+
+  def test_list
+    @proxy.push 3
+    @proxy.push 5
+
+    Rexpl::Output.expects(:print_instruction).with([:push, 3], 0)
+    Rexpl::Output.expects(:print_instruction).with([:push, 5], 1)
+
+    @proxy.list
+  end
+
+  def test_draw
+    @proxy.push 3
+    @proxy.push 5
+    @proxy.meta_send_op_plus 2
+
+    Rexpl::Output.expects(:print_stack).with([3])
+    Rexpl::Output.expects(:print_stack).with([3, 5])
+    Rexpl::Output.expects(:print_stack).with([8])
+
+    @proxy.draw
+  end
+
+end

data/test/rexpl/output_test.rb

@@ -0,0 +1,63 @@
+require 'test_helper'
+require 'stringio'
+
+class OutputTest < MiniTest::Unit::TestCase
+  def setup
+    $stdout = StringIO.new
+  end
+
+  def test_print_banner
+    Rexpl::Output.print_banner
+    assert_match /rexpl/, $stdout.string
+  end
+  
+  def test_print_prompt
+    Rexpl::Output.print_prompt
+    assert_match />/, $stdout.string
+  end
+
+  def test_print_reset
+    Rexpl::Output.print_reset
+    assert_match /Reseted!/, $stdout.string
+  end
+
+  def test_print_debug_info
+    Rexpl::Output.print_debug_info("3", '"some_value"')
+    assert_match /Stack size: 3/, $stdout.string
+    assert_match /Topmost value: "some_value"/, $stdout.string
+  end
+
+  def test_print_instruction
+    instruction = ['send', ':puts', '1', 'true']
+
+    Rexpl::Output.print_instruction(instruction, 3)
+    assert_match /send/, $stdout.string
+    assert_match /:puts/, $stdout.string
+    assert_match /1/, $stdout.string
+    assert_match /true/, $stdout.string
+    assert_match /3/, $stdout.string
+  end
+
+  def test_print_stack
+    cells = %w(Rubinius 23)
+    Rexpl::Output.print_stack(cells)
+    assert_match /Current stack/, $stdout.string
+    assert_match /23/, $stdout.string
+    assert_match /Rubinius/, $stdout.string
+
+    # Rubinius should appear after 23, since cells are reversed
+    refute_match /Rubinius/, $stdout.string.split('23').first
+    assert_match /Rubinius/, $stdout.string.split('23').last
+  end
+
+  def test_print_rationale
+    Rexpl::Output.print_rationale
+    assert_match /list/, $stdout.string
+    assert_match /reset/, $stdout.string
+    assert_match /draw/, $stdout.string
+  end
+
+  def teardown
+    $stdout = STDOUT
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+
+gem 'minitest'
+require 'minitest/autorun'
+require 'mocha'
+
+require 'rexpl'

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification 
+name: rexpl
+version: !ruby/object:Gem::Version 
+  hash: 29
+  prerelease: 
+  segments: 
+  - 0
+  - 0
+  - 1
+  version: 0.0.1
+platform: ruby
+authors: 
+- Josep M. Bach
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-06-17 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: ansi
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: bluecloth
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: Rexpl is an interactive bytecode console for Rubinius
+email: 
+- josep.m.bach@gmail.com
+executables: 
+- rexpl
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- .rvmrc
+- Gemfile
+- Rakefile
+- Readme.md
+- bin/rexpl
+- lib/rexpl.rb
+- lib/rexpl/environment.rb
+- lib/rexpl/generator_methods.rb
+- lib/rexpl/generator_proxy.rb
+- lib/rexpl/output.rb
+- lib/rexpl/version.rb
+- rexpl.gemspec
+- test/rexpl/environment_test.rb
+- test/rexpl/generator_methods_test.rb
+- test/rexpl/generator_proxy_test.rb
+- test/rexpl/output_test.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/txus/rexpl
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rexpl
+rubygems_version: 1.5.2
+signing_key: 
+specification_version: 3
+summary: Rexpl is an interactive bytecode console for Rubinius
+test_files: 
+- test/rexpl/environment_test.rb
+- test/rexpl/generator_methods_test.rb
+- test/rexpl/generator_proxy_test.rb
+- test/rexpl/output_test.rb
+- test/test_helper.rb