orb 0.0.4 → 0.0.5

data/README.md

@@ -12,6 +12,11 @@ the file and replacing the `ORB{}` call.
 
 [Watch the video](#) (Coming Soon).
 
+# I just want to use it with Rspec. How?
+
+Add `ORB{}` to a pending example, then run your spec suite with 
+`-r orb`, for example, `spec -rorb spec/**/*_spec.rb`, or add it to `spec_opts`.
+
 # Can I use this with \#{framework}?
 
 Probably. Have a look at `lib/orb/adapters/rspec.rb`. It's a pretty simple

data/lib/orb.rb

@@ -1,30 +1,83 @@
+# ORB is a tool to write tests interactively. 
+
+# Most ruby programmers, even the ones with extensive test suites, frequently 
+# find themselves in IRB, trying snippets of code here and there.
+# It's not uncommon to run some code in IRB, then copy parts of it almost
+# verbatim into a test file for use as a test. ORB makes this a much more smooth
+# process. 
+
+# The basic workflow with ORB is: 
+
+# 1. Add `ORB{}` to each new test, at the point where you'd like to insert code.
+# 2. Run your test suite with `orb` loaded. See `adapters/rspec.rb`.
+# 3. Use the REPL provided for each call to ORB to create a new test.
+
+# When a call to `ORB` is encountered, you'll be dropped to to a REPL with full
+# access to the test's context (much like a debugger). You can run code, and 
+# interact with the context however you like. When you're ready to write your 
+# test, you simply run the commands, then add them to a buffer. Once your 
+# buffer contains the code you'd like to save as a test, you can write
+# it back to the file in place of the call to `ORB` with just two keystrokes.
+
+# The REPL uses readline for line editing.
 require 'readline'
+
+# Adapters are near-trivial to write, and provide test-framework integration.
 require 'orb/adapters/rspec'
 
-module ORB
-  
-  def self.capture(bind)
-    buf, line, last = [], "", ""
+class ORB
+  @@index=0
+  def initialize(bind)
+    @@index += 1
+    @buf, @hist = [], []
+    @line, @file = bind.eval("[__LINE__, __FILE__]")
 
-    puts ORB::Adapter.header(bind)
+    puts "\n\n[[ #{ORB::Adapter.header(bind)} ]]"
     
-    while line = Readline.readline("ORB >> ", true)
-      
+    while line = Readline.readline(prompt, true)
       case line
-      when "a"
-        buf << last
+        
+        # The `a` command appends one or more recent lines to the test buffer.
+      when /^a\s?(\d*)$/
+        append_to_buffer($1.to_i)
         next
+
+        # The `h` command shows this session's history. Each line starts with 
+        # a coloured space. A red space indicates that this line is not in
+        # the buffer, and a green space indicates that this line is in the 
+        # buffer, and will be written back to the file when the test is saved.
+      when "h"
+        red   = "\x1B[41m \x1B[m"
+        green = "\x1B[42m \x1B[m"
+        @hist.each do |line, in_buf|
+          print in_buf ? green : red
+          print ' '
+          puts line
+        end 
+        next 
+
+        # The `p` command prints the current contents of the buffer. If the test
+        # is written back to the file right now, this is what will be inserted.
       when "p"
-        puts buf
+        puts @buf
         next 
+        
+        # The `q` command exits this session without writing a test. Next time
+        # the suite is run, you'll get a REPL here again.
       when "q"
-        __orb_original_pending(message)
         break
+        
+        # The `s` command writes the contents of the buffer out to the file.
       when "s"
-        line, file = bind.eval("[__LINE__, __FILE__]")
-        ORB.write_buf_to_file(buf, line, file)
+        write_buf_to_file
         break
+        
+        # If this line wasn't a command, evaluate it in the context of the code 
+        # that called `ORB{}`. We're stealing that context from the block.
+        # There are other, trickier tricks to get it without requiring a block,
+        # but they haven't been reliable since ruby 1.8.5.
       else 
+        @hist << [line,false]
         begin
           this = bind.eval("self")
           ret = this.send(:eval, line, this.send(:binding))
@@ -35,26 +88,49 @@ module ORB
         end 
       end 
       
-      last = line
     end 
   end 
 
-  def self.write_buf_to_file(buf, line_num, file)
-    lines = File.read(file).lines.to_a
+  private
+
+  # Append some number of recent lines to the test buffer. This is triggered
+  # by the command `a` or `a <n>`, eg. `a 3`. If called with no number, just
+  # appends the last command run, otherwise, appends n lines.
+  def append_to_buffer(n=1)
+    @hist.last[1] = true
+    @buf << @hist.last[0]
+  end 
+  
+  # When this command is run, ORB will save the contents of the test buffer
+  # back into the file where `ORB{}` was called from. It does this by reading
+  # in the entire file, then rewriting it with ORB{} replaced by the buffer.
+  def write_buf_to_file
+    lines = File.read(@file).lines.to_a
      
-    File.open(file,"w") do |f|
-      f.puts lines[0...line_num-1]
+    File.open(@file,"w") do |f|
+      f.puts lines[0...@line-1]
      
-      orbline = lines[line_num-1]
+      orbline = lines[@line-1]
       indentation = orbline.index(/[^\s]/)
-     
-      buf.each do |bufline|
+
+      # Here we're indenting the inserted code to the same level as `ORB{}` 
+      # was indented.
+      @buf.each do |bufline|
         f.print " "*indentation
         f.puts bufline
       end 
       
-      f.puts lines[line_num..-1]
+      f.puts lines[@line..-1]
     end   
   end 
   
+  # ORB's prompt looks like `1:0 >>`. The first number is the index of this 
+  # test, starting at one, and incrementing with each test during an 
+  # ORB-enhanced run of your test suite. The second number is the current size 
+  # of the test buffer; that is, the number of lines that will be written to 
+  # the file if the test is saved right now.
+  def prompt
+    "#{@@index}:#{@buf.size} >> "
+  end 
+
 end 

data/lib/orb/adapters/rspec.rb

@@ -1,6 +1,15 @@
-require 'spec/example/pending'
+### ORB RSpec Adapter
+# This integrates ORB with RSpec. To run your test suite with ORB enabled,
+# run `spec` with `-rorb`, or add `-rorb` to `spec_opts`, or simply 
+# `require 'orb'` in your `spec_helper.rb`.
 
-module ORB
+# ORB's requirements of an adapter are minimal:
+
+# - (optional) Some convenient way to start an ORB session. 
+# - (optional) A header describing this specific instance.
+# Each RSpec example has a description that's printed when it fails.
+# We re-create that here to provide context when an ORB session is started.
+class ORB
   module Adapters
     module RSpec
       def self.header(bind)
@@ -12,14 +21,20 @@ module ORB
   end 
 end 
 
+# Initially, I wanted to override `pending` as the method to start ORB,
+# but as it turns out, the Object hackery I need to do to make ORB work
+# requires a block. Requiring that pending be called with a block seems like
+# an odd design choice, so instead I've made the method ORB, 
+# called like `ORB{}`.
 module Spec
   module Example
     module Pending
       def ORB(&block)
-        ORB.capture(block.binding)
+        ORB.new(block.binding)
       end 
     end 
   end 
 end 
 
+# Finally, now that the RSpec Adapter is defined, set ORB's default Adapter.
 ORB::Adapter = ORB::Adapters::RSpec

data/orb.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name    = 'orb'
-  gem.version = "0.0.4"
+  gem.version = "0.0.5"
 
   gem.author, gem.email = 'Burke Libbey', "burke@burkelibbey.org"
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 4
-  version: 0.0.4
+  - 5
+  version: 0.0.5
 platform: ruby
 authors: 
 - Burke Libbey
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-05-01 00:00:00 -05:00
+date: 2010-05-02 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -31,7 +31,6 @@ files:
 - README.md
 - orb.gemspec
 - lib/orb/adapters/rspec.rb
-- lib/orb/binding.rb
 - lib/orb.rb
 has_rdoc: true
 homepage: 

data/lib/orb/binding.rb

@@ -1,32 +0,0 @@
-def Binding.of_caller(&block)
-  old_critical, Thread.critical = Thread.critical, true
-  count = 0
-  cc = nil
-  result, error = callcc{|c|cc=c;nil}
-  error.call if error
-
-  tracer = lambda do |*args|
-    type, _, _, _, context = args
-    if ["return", "c-return"].include?(type)
-      count += 1
-      # First this method and then calling one will return -- the trace event of the second event gets the context
-      # of the method which called the method that called method.
-      if count == 2
-        set_trace_func(nil)
-        cc.call(eval("binding", context), nil)
-      end
-    elsif type != "line"
-      set_trace_func(nil)
-      cc.call(nil, lambda { raise(Exception, "Binding.of_caller used in non-method context or trailing statements of method using it aren't in the block." ) })
-    end
-  end
-  
-  if result
-    Thread.critical = old_critical
-    yield result
-  else
-    set_trace_func(tracer)
-    return nil
-  end
-end
-