stub_shell 0.0.2 → 0.0.3

data/README.markdown

@@ -1,5 +1,10 @@
 # StubShell [![Build Status](https://secure.travis-ci.org/stackbuilders/stub_shell.png)](http://travis-ci.org/stackbuilders/stub_shell)
 
+StubShell helps you to test your libraries that interact with the system through the Kernel backquote and system methods.  
+It does this by providing a DSL to describe the messages that you expect the shell to receive in the order that you expect
+to receive them.  StubShell can be used to stub simple interactions, or ones that cause the system that you're working with
+to change state.
+
 ## Installation
 
     gem install stub_shell
@@ -14,14 +19,72 @@
 
 ## Usage
 
+StubShell can handle simple cases where you want to stub a system call in Ruby or more complex interactions 
+where commands may change the state and return values of subsequent commands.
+
+### Simple Usage
+
+You use StubShell simply by describing the commands that you want stubbed out, along with the value that they
+should return in STDOUT and STDERR, as well as their exit status.
+
     it ... do
       stub_shell do
         command "ls /tmp/foobar" do
           stdout "hey there"
+          stderr "some error"
+          exitstatus 2
+        end
+      end
+    end
+
+By default, StubShell assumes that STDOUT and STDERR are nil, and that the exit status is 0 (success), so you 
+can leave these options out if you want.
+
+### Stubbing Complex Shell Interactions
+
+You can stub more complex interactions with the shell, including cases where commands that you execute will
+change the output of subsequent commands.
+
+    stub_shell do
+      command 'ls /tmp/foobar' do
+        stdout 'yes, foobar exists'
+      end
+    
+      command "rm /tmp/foobar" do
+        stub_shell do
+          command 'ls /tmp/foobar' do
+            stderr 'the file no longer exists'
+            exitstatus 2
+          end
         end
       end
     end
 
+StubShell starts looking for defined commands at the current level of the execution hierarchy, so if you
+invoke the command to remove /tmp/foobar above, it will always look at the stub_shell context nested below
+that command for matches to subsequent commands.  If no matching commands are found at that level, StubShell
+searches recursively upwards in the tree for matches until it either finds one or it runs out of options and 
+raises an error indicating that no matches were found.
+
+### Regular Expression Matching of Commands
+
+You can use regular expressions to match commands in StubShell.
+
+    stub_shell do
+      command /ls \/tmp.*foo/' do
+        stdout 'yes, your directory exists'
+      end
+    end
+
+### Additional Documentation
+
+We suggest that you read the acceptance tests included with this library to help understand the 
+way that it works.
+
+## Authors
+
+Justin Leitgeb (@jsl) and @itsmeduncan.
+
 ## Contribute
 
 1. [Fork](http://help.github.com/forking/) stub_shell

data/lib/stub_shell/version.rb

@@ -1,3 +1,3 @@
 module StubShell
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stub_shell
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -10,11 +10,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-04 00:00:00.000000000 Z
+date: 2012-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70197553821800 !ruby/object:Gem::Requirement
+  requirement: &70219775244760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -22,10 +22,10 @@ dependencies:
         version: 0.9.2.2
   type: :development
   prerelease: false
-  version_requirements: *70197553821800
+  version_requirements: *70219775244760
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70197553821080 !ruby/object:Gem::Requirement
+  requirement: &70219775244020 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -33,10 +33,10 @@ dependencies:
         version: 2.8.0
   type: :development
   prerelease: false
-  version_requirements: *70197553821080
+  version_requirements: *70219775244020
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70197553820460 !ruby/object:Gem::Requirement
+  requirement: &70219775243460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -44,7 +44,7 @@ dependencies:
         version: 0.5.4
   type: :development
   prerelease: false
-  version_requirements: *70197553820460
+  version_requirements: *70219775243460
 description: Stubs a set of shell commands and their return values using the backquote
   operator.
 email: