README.rdoc in visionmedia-jspec-2.3.1 vs README.rdoc in visionmedia-jspec-2.4.0

@@ -8,10 +8,11 @@
 
 == Features
 
 * Highly readable
 * Framework / DOM independent
+* Modular via JSpec Module's and hooks
 * Rhino support
 * Async support
 * Ruby JavaScript testing server
 * Nested describes
 * Does not pollute core object prototypes
@@ -224,11 +225,17 @@
   
 If you would like to whipe an object clear of stubs simply pass it
 to destub() without an additional method argument:
 
   destub(person)
+  
+Alternatively both these utility functions may be called as methods
+on any object when using the JSpec grammar:
 
+  someObject.stub('method').and_return('whatever')
+  // Converted to stub(someObject, 'method').and_return('whatever')
+
 == Helpers
 
   * Core
 
   - an_instance_of   used in conjunction with the 'receive' matcher
@@ -415,10 +422,84 @@
       message : function(actual, expected, negate) {
         return 'a message here'
       }
     }
   })
+  
+When defining matchers that are extremely similar in functionality, however
+require different names, you may use a prefixed list of words like below which
+defines be_disabled, be_selected, be_checked, and have_type, have_id, etc. Each
+function must return the matcher body which will be used.
 
+  JSpec.addMatchers({
+    'be disabled selected checked' : function(attr) {
+      return 'jQuery(actual).attr("' + attr + '")'
+    },
+
+    'have type id title alt href src sel rev name target' : function(attr) {
+      return function(actual, value) {
+        return value ? jQuery(actual).attr(attr) == value:
+                       jQuery(actual).attr(attr)
+      }
+    }
+  })
+
+== Extending Or Hooking Into JSpec
+
+JSpec provides a hook architecture for extending or analyzing various
+points in its execution, through the use of 'Modules'. For a Module
+example view lib/jspec.jquery.js. 
+
+The following methods or properties are utilized by JSpec:
+
+  - init      : called to initialize a module
+  - utilities : hash of utility functions merged with JSpec.defaultContext
+  - matchers  : hash of matchers merged with JSpec's core matchers via JSpec.addMatchers()
+
+Below is a list of hooks, descriptions, and valid return values which
+may simply be implemented as module methods.
+
+  - running(options)                 : started running JSpec with the options passed    : returning 'stop' will halt running
+  - loading(file)                    : loading a file                                   : returning 'stop' will prevent loading
+  - executing(file)                  : executing a file                                 : returning 'stop' will prevent execution 
+  - posting(data, url)               : posting data to a url                            : returning 'stop' will prevent request
+  - reportingToServer(url)           : reporting to server url                          : returning 'stop' will prevent reporting to server
+  - preprocessing(input)             : before input string is preprocessed              : return input string for next hook to preprocess
+  - stubbing(object, method, result) : called when stubbing an object's method, and return value (result). : (no return value)
+  - requiring(dependency, message)   : requiring a dependency                           : (no return value) 
+  - beforeAssertion(assertion)       : before an assertion has been made                : (no return value)
+  - afterAssertion(assertion)        : after an assertion has been made                 : (no return value)
+  - addingMatcher(name, body)        : unprocessed matcher name and body                : (no return value)
+  - addingSuite(suite)               : adding Suite instance to JSpec                   : (no return value)
+  - beforeSuite(suite)               : before running of suite                          : (no return value)
+  - afterSuite(suite)                : after running of suite                           : (no return value)
+  - beforeSpec(spec)                 : before running of spec                           : (no return value)
+  - afterSpec(spec)                  : after running of spec                            : (no return value)
+  - reporting(options)               : called before reporting                          : (no return value)
+  - evaluatingBody(dsl, matchers, context, contents) : evaluating body contents, with the given context, matchers and dsl. : (no return value)
+  
+For example you may wish to proxy files which are being executed, simply implement the 
+executing method like below. This example will stop execution of any file matching /matchers/.
+
+  MyModule = {
+    executing : function(file) {
+      if (file.match(/matchers/))
+        return 'stop'
+    }
+  }
+  JSpec.include(MyModule)
+  
+Immutable values may also be passed to hooks using hookImmutable() internally. This allows
+for simple numbers, strings, etc to be utilized or altered within a hook implementation. Below
+is an example module which adds functionality to the JSpec grammar by converting SomeObject.stub('method')
+to stub(SomeObject, 'method'):
+
+  JSpec.include({
+    preprocessing : function(input) {
+      return input.replace(/(\w+)\.(stub|destub)\((.*?)\)$/gm, '$2($1, $3)')
+    }
+  })
+  
 == JSpec Command-line Utility
 
 When installed as a Ruby Gem, the `jspec` executable will become available,
 allowing you to initialize project templates quickly, as well as auto-testing
 specifications when a file is altered.