0
@@ -91,6 +91,99 @@ All of these should be applied to a block created with `lambda` or `proc`:
0
   is associated with. The exception class can be given for finer-grained
0
   control (inheritance works normally so Exception would catch everything.)
0
 
0
+== Nested 'describe' blocks
0
+
0
+MSpec supports nesting one 'describe' block inside another. The examples in
0
+the nested block are evaluated with all the before/after blocks of all the
0
+containing 'describe' blocks. The following example illustrates this:
0
+
0
+describe "Some#method" do
0
+  before :each do
0
+    @obj = 1
0
+  end
0
+
0
+  describe "when passed String" do
0
+    before :each do
0
+      @meth = :to_s
0
+    end
0
+
0
+    it "returns false" do
0
+      # when this example is evaluated, @obj = 1 and @meth = :to_s
0
+    end
0
+  end
0
+end
0
+
0
+The output when using the SpecdocFormatter (selected with -fs to the runners)
0
+will be as follows:
0
+
0
+Some#method when passed String
0
+- returns false
0
+
0
+
0
+== Shared 'describe' blocks
0
+
0
+MSpec supports RSpec-style shared 'describe' blocks. MSpec also provides a
0
+convenience method to assist in writing specs for the numerous aliased methods
0
+that Ruby provides. The following example illustrates shared blocks:
0
+
0
+describe :someclass_some_method, :shared => true do
0
+  it "does something" do
0
+  end
0
+end
0
+
0
+describe "SomeClass#some_method" do
0
+  it_should_behave_like "someclass_some_method"
0
+end
0
+
0
+The first argument to 'describe' for a shared block is an object that
0
+duck-types as a String. The representation of the object must be unique. This
0
+example uses a symbol. This was the convention for the previous facility that
0
+MSpec provided for aliased method (#it_behaves_like). However, this convention
0
+is not set in stone (but the uniqueness requirement is). Note that the
0
+argument to the #it_should_behave_like is a String because at this time RSpec
0
+will not find the shared block by the symbol.
0
+
0
+MSpec continues to support the #it_behaves_like convenience method for
0
+specifying aliased methods. The syntax is as follows:
0
+
0
+it_behaves_like :symbol_matching_shared_describe, :method [, :object]
0
+
0
+describe :someclass_some_method, :shared => true do
0
+  it "returns true" do
0
+    obj.send(@method).should be_true
0
+  end
0
+
0
+  it "returns something else" do
0
+    @object.send(@method).should be_something_else
0
+  end
0
+end
0
+
0
+# example #1
0
+describe "SomeClass#some_method" do
0
+  it_behaves_like :someclass_some_method, :other_method
0
+end
0
+
0
+# example #2
0
+describe "SomeOtherClass#some_method" do
0
+  it_behaves_like :someclass_some_method, :some_method, OtherClass
0
+end
0
+
0
+The first form above (#1) is used for typical aliases. That is, methods with
0
+different names on the same class that behave identically. The
0
+#it_behaves_like helper creates a before(:all) block that sets @method to
0
+:other_method. The form of the first example block in the shared block
0
+illustrates the typical form of a spec for an aliased method.
0
+
0
+The second form above (#2) is used for methods on different classes that are
0
+essentially aliases, even though Ruby does not provide a syntax for specifying
0
+such methods as aliases. Examples are the methods on File, FileTest, and
0
+File::Stat. In this case, the #it_behaves_like helper sets both @method and
0
+@object in the before(:all) block (@method = :some_method, @object =
0
+OtherClass in this example).
0
+
0
+For shared specs that fall outside of either of these two narrow categories,
0
+use nested or shared 'describe' blocks as appropriate and use the
0
+#it_should_behave_like method directly.
0
 
0
 == Guards
0
 

0
@@ -61,8 +61,10 @@ class MSpecCI < MSpecScript
0
     MSpec.register_tags_patterns config[:tags_patterns]
0
     MSpec.register_files files
0
     TagFilter.new(:exclude, "fails").register
0
+    TagFilter.new(:exclude, "critical").register
0
     TagFilter.new(:exclude, "unstable").register
0
     TagFilter.new(:exclude, "incomplete").register
0
+    TagFilter.new(:exclude, "unsupported").register
0
 
0
     MSpec.process
0
     exit MSpec.exit_code

0
@@ -6,12 +6,13 @@ require 'mspec/matchers/be_false'
0
 require 'mspec/matchers/be_kind_of'
0
 require 'mspec/matchers/be_nil'
0
 require 'mspec/matchers/be_true'
0
-require 'mspec/matchers/equal'
0
+require 'mspec/matchers/complain'
0
 require 'mspec/matchers/eql'
0
+require 'mspec/matchers/equal'
0
+require 'mspec/matchers/equal_element'
0
+require 'mspec/matchers/equal_utf16'
0
 require 'mspec/matchers/include'
0
 require 'mspec/matchers/match_yaml'
0
 require 'mspec/matchers/raise_error'
0
 require 'mspec/matchers/output'
0
 require 'mspec/matchers/output_to_fd'
0
-require 'mspec/matchers/complain'
0
-require 'mspec/matchers/equal_utf16'

0
@@ -13,84 +13,170 @@ require 'mspec/runner/example'
0
 # is evaluated, just as +it+ refers to the example itself.
0
 #++
0
 class ContextState
0
-  attr_reader :state
0
-
0
-  def initialize
0
-    @start  = []
0
-    @before = []
0
-    @after  = []
0
-    @finish = []
0
-    @spec   = []
0
+  attr_reader :state, :parent, :parents, :children, :examples, :to_s
0
+
0
+  def initialize(mod, options=nil)
0
+    @to_s = mod.to_s
0
+    if options.is_a? Hash
0
+      @options = options
0
+    else
0
+      @to_s += "#{".:#".include?(options[0,1]) ? "" : " "}#{options}" if options
0
+      @options = { }
0
+    end
0
+    @options[:shared] ||= false
0
+
0
+    @parsed   = false
0
+    @before   = { :all => [], :each => [] }
0
+    @after    = { :all => [], :each => [] }
0
+    @pre      = {}
0
+    @post     = {}
0
+    @examples = []
0
+    @parent   = nil
0
+    @parents  = [self]
0
+    @children = []
0
+
0
     @mock_verify         = lambda { Mock.verify_count }
0
     @mock_cleanup        = lambda { Mock.cleanup }
0
     @expectation_missing = lambda { raise ExpectationNotFoundError }
0
   end
0
 
0
-  def before(at=:each, &block)
0
-    case at
0
-    when :each
0
-      @before << block
0
-    when :all
0
-      @start << block
0
-    end
0
+  # Returns true if this is a shared +ContextState+. Essentially, when
0
+  # created with: describe "Something", :shared => true { ... }
0
+  def shared?
0
+    return @options[:shared]
0
   end
0
 
0
-  def after(at=:each, &block)
0
-    case at
0
-    when :each
0
-      @after << block
0
-    when :all
0
-      @finish << block
0
+  # Set the parent (enclosing) +ContextState+ for this state. Creates
0
+  # the +parents+ list.
0
+  def parent=(parent)
0
+    @description = nil
0
+    @parent = parent
0
+    parent.child self if parent and not shared?
0
+
0
+    state = parent
0
+    while state
0
+      parents.unshift state
0
+      state = state.parent
0
     end
0
   end
0
 
0
+  # Add the ContextState instance +child+ to the list of nested
0
+  # describe blocks.
0
+  def child(child)
0
+    @children << child
0
+  end
0
+
0
+  # Returns a list of all before(+what+) blocks from self and any parents.
0
+  def pre(what)
0
+    @pre[what] ||= parents.inject([]) { |l, s| l.push(*s.before(what)) }
0
+  end
0
+
0
+  # Returns a list of all after(+what+) blocks from self and any parents.
0
+  # The list is in reverse order. In other words, the blocks defined in
0
+  # inner describes are in the list before those defined in outer describes,
0
+  # and in a particular describe block those defined later are in the list
0
+  # before those defined earlier.
0
+  def post(what)
0
+    @post[what] ||= parents.inject([]) { |l, s| l.unshift(*s.after(what)) }
0
+  end
0
+
0
+  # Records before(:each) and before(:all) blocks.
0
+  def before(what, &block)
0
+    block ? @before[what].push(block) : @before[what]
0
+  end
0
+
0
+  # Records after(:each) and after(:all) blocks.
0
+  def after(what, &block)
0
+    block ? @after[what].unshift(block) : @after[what]
0
+  end
0
+
0
+  # Creates an ExampleState instance for the block and stores it
0
+  # in a list of examples to evaluate unless the example is filtered.
0
   def it(desc, &block)
0
-    state = ExampleState.new @describe, desc
0
-    @spec << [desc, block, state] unless state.filtered?
0
+    @examples << ExampleState.new(self, desc, block)
0
+  end
0
+
0
+  # Evaluates the block and resets the toplevel +ContextState+ to #parent.
0
+  def describe(&block)
0
+    @parsed = protect @to_s, block, false
0
+    MSpec.register_current parent
0
+    MSpec.register_shared self if shared?
0
+  end
0
+
0
+  # Returns a description string generated from self and all parents
0
+  def description
0
+    @description ||= parents.inject([]) { |l,s| l << s.to_s }.join(" ")
0
   end
0
 
0
-  def describe(mod, desc=nil, &block)
0
-    @describe = desc ? "#{mod} #{desc}" : mod.to_s
0
-    @block = block
0
+  # Injects the before/after blocks and examples from the shared
0
+  # describe block into this +ContextState+ instance.
0
+  def it_should_behave_like(desc)
0
+    unless state = MSpec.retrieve_shared(desc)
0
+      raise Exception, "Unable to find shared 'describe' for #{desc}"
0
+    end
0
+
0
+    state.examples.each { |ex| ex.context = self; @examples << ex }
0
+    state.before(:all).each { |b| before :all, &b }
0
+    state.before(:each).each { |b| before :each, &b }
0
+    state.after(:each).each { |b| after :each, &b }
0
+    state.after(:all).each { |b| after :all, &b }
0
   end
0
 
0
+  # Evaluates each block in +blocks+ using the +MSpec.protect+ method
0
+  # so that exceptions are handled and tallied. Returns true and does
0
+  # NOT evaluate any blocks if +check+ is true and +MSpec.pretend_mode?+
0
+  # is true.
0
   def protect(what, blocks, check=true)
0
     return true if check and MSpec.pretend_mode?
0
     Array(blocks).all? { |block| MSpec.protect what, &block }
0
   end
0
 
0
+  # Removes filtered examples. Returns true if there are examples
0
+  # left to evaluate.
0
+  def filter_examples
0
+    @examples.reject! { |ex| ex.filtered? }
0
+    not @examples.empty?
0
+  end
0
+
0
+  # Evaluates the examples in a +ContextState+. Invokes the MSpec events
0
+  # for :enter, :before, :after, :leave.
0
   def process
0
-    protect @describe, @block, false
0
-    return unless @spec.any? { |desc, spec, state| state.unfiltered? }
0
-
0
-    MSpec.shuffle @spec if MSpec.randomize?
0
-    MSpec.actions :enter, @describe
0
-
0
-    if protect "before :all", @start
0
-      @spec.each do |desc, spec, state|
0
-        @state = state
0
-        MSpec.actions :before, state
0
-
0
-        if protect("before :each", @before)
0
-          MSpec.clear_expectations
0
-          passed = protect nil, spec
0
-          if spec
0
-            MSpec.actions :example, state, spec
0
-            protect nil, @expectation_missing unless MSpec.expectation? or not passed
0
+    MSpec.register_current self
0
+
0
+    if @parsed and filter_examples
0
+      MSpec.shuffle @examples if MSpec.randomize?
0
+      MSpec.actions :enter, description
0
+
0
+      if protect "before :all", pre(:all)
0
+        @examples.each do |state|
0
+          @state  = state
0
+          example = state.example
0
+          MSpec.actions :before, state
0
+
0
+          if protect "before :each", pre(:each)
0
+            MSpec.clear_expectations
0
+            if example
0
+              passed = protect nil, example
0
+              MSpec.actions :example, state, example
0
+              protect nil, @expectation_missing unless MSpec.expectation? or not passed
0
+            end
0
+            protect "after :each", post(:each)
0
+            protect "Mock.verify_count", @mock_verify
0
           end
0
-          protect "after :each", @after
0
-          protect "Mock.verify_count", @mock_verify
0
-        end
0
 
0
+          protect "Mock.cleanup", @mock_cleanup
0
+          MSpec.actions :after, state
0
+          @state = nil
0
+        end
0
+        protect "after :all", post(:all)
0
+      else
0
         protect "Mock.cleanup", @mock_cleanup
0
-        MSpec.actions :after, state
0
-        @state = nil
0
       end
0
-      protect "after :all", @finish
0
-    else
0
-      protect "Mock.cleanup", @mock_cleanup
0
+
0
+      MSpec.actions :leave
0
     end
0
 
0
-    MSpec.actions :leave
0
+    MSpec.register_current nil
0
+    children.each { |child| child.process }
0
   end
0
 end

0
@@ -3,35 +3,32 @@ require 'mspec/runner/mspec'
0
 # Holds some of the state of the example (i.e. +it+ block) that is
0
 # being evaluated. See also +ContextState+.
0
 class ExampleState
0
-  def initialize(describe, it)
0
-    @describe = describe
0
-    @it = it
0
-    @unfiltered = nil
0
-  end
0
+  attr_reader   :context, :it, :example
0
 
0
-  def describe
0
-    @describe
0
+  def initialize(context, it, example=nil)
0
+    @context  = context
0
+    @it       = it
0
+    @example  = example
0
   end
0
 
0
-  def it
0
-    @it
0
+  def context=(context)
0
+    @description = nil
0
+    @context = context
0
   end
0
 
0
-  def description
0
-    @description ||= "#{@describe} #{@it}"
0
+  def describe
0
+    @context.description
0
   end
0
 
0
-  def unfiltered?
0
-    unless @unfiltered
0
-      incl = MSpec.retrieve(:include) || []
0
-      excl = MSpec.retrieve(:exclude) || []
0
-      @unfiltered   = incl.empty? || incl.any? { |f| f === description }
0
-      @unfiltered &&= excl.empty? || !excl.any? { |f| f === description }
0
-    end
0
-    @unfiltered
0
+  def description
0
+    @description ||= "#{describe} #{@it}"
0
   end
0
 
0
   def filtered?
0
-    not unfiltered?
0
+    incl = MSpec.retrieve(:include) || []
0
+    excl = MSpec.retrieve(:exclude) || []
0
+    included   = incl.empty? || incl.any? { |f| f === description }
0
+    included &&= excl.empty? || !excl.any? { |f| f === description }
0
+    not included
0
   end
0
 end

0
@@ -18,18 +18,21 @@ module MSpec
0
   @mode    = nil
0
   @load    = nil
0
   @unload  = nil
0
+  @current = nil
0
+  @shared  = {}
0
   @exception    = nil
0
   @randomize    = nil
0
   @expectation  = nil
0
   @expectations = false
0
 
0
-  def self.describe(mod, msg=nil, &block)
0
-    stack.push ContextState.new
0
+  def self.describe(mod, options=nil, &block)
0
+    state = ContextState.new mod, options
0
+    state.parent = current
0
 
0
-    current.describe(mod, msg, &block)
0
-    current.process
0
+    MSpec.register_current state
0
+    state.describe(&block)
0
 
0
-    stack.pop
0
+    state.process unless state.shared? or current
0
   end
0
 
0
   def self.process
0
@@ -62,6 +65,8 @@ module MSpec
0
     begin
0
       @env.instance_eval(&block)
0
       return true
0
+    rescue SystemExit
0
+      raise
0
     rescue Exception => exc
0
       register_exit 1
0
       actions :exception, ExceptionState.new(current && current.state, location, exc)
0
@@ -69,14 +74,42 @@ module MSpec
0
     end
0
   end
0
 
0
+  # Sets the toplevel ContextState to +state+.
0
+  def self.register_current(state)
0
+    store :current, state
0
+  end
0
+
0
+  # Sets the toplevel ContextState to +nil+.
0
+  def self.clear_current
0
+    store :current, nil
0
+  end
0
+
0
+  # Returns the toplevel ContextState.
0
+  def self.current
0
+    retrieve :current
0
+  end
0
+
0
+  # Stores the shared ContextState keyed by description.
0
+  def self.register_shared(state)
0
+    @shared[state.to_s] = state
0
+  end
0
+
0
+  # Returns the shared ContextState matching description.
0
+  def self.retrieve_shared(desc)
0
+    @shared[desc.to_s]
0
+  end
0
+
0
+  # Stores the exit code used by the runner scripts.
0
   def self.register_exit(code)
0
     store :exit, code
0
   end
0
 
0
+  # Retrieves the stored exit code.
0
   def self.exit_code
0
     retrieve(:exit).to_i
0
   end
0
 
0
+  # Stores the list of files to be evaluated.
0
   def self.register_files(files)
0
     store :files, files
0
   end
0
@@ -141,14 +174,6 @@ module MSpec
0
     end
0
   end
0
 
0
-  def self.stack
0
-    @stack ||= []
0
-  end
0
-
0
-  def self.current
0
-    stack.last
0
-  end
0
-
0
   def self.verify_mode?
0
     @mode == :verify
0
   end

0
@@ -7,7 +7,7 @@ class Object
0
     MSpec.current.after at, &block
0
   end
0
 
0
-  def describe(mod, msg=nil, &block)
0
+  def describe(mod, msg=nil, options=nil, &block)
0
     MSpec.describe mod, msg, &block
0
   end
0
 
0
@@ -15,6 +15,10 @@ class Object
0
     MSpec.current.it msg, &block
0
   end
0
 
0
+  def it_should_behave_like(desc)
0
+    MSpec.current.it_should_behave_like desc
0
+  end
0
+
0
   alias_method :context, :describe
0
   alias_method :specify, :it
0
 end

0
@@ -1,12 +1,12 @@
0
 require 'mspec/runner/mspec'
0
 
0
 class Object
0
-  def shared(msg, &block)
0
-    MSpec.store msg.to_sym, block
0
-  end
0
+  def it_behaves_like(desc, meth, obj=nil)
0
+    send :before, :all do
0
+      @method = meth
0
+      @object = obj if obj
0
+    end
0
 
0
-  def it_behaves_like(behavior, *args)
0
-    p = MSpec.retrieve behavior.to_sym
0
-    p[*args]
0
+    send :it_should_behave_like, desc.to_s
0
   end
0
 end

0
@@ -1,3 +1,3 @@
0
 module MSpec
0
-  VERSION = '1.3.1'
0
+  VERSION = '1.4.0'
0
 end

0
@@ -121,6 +121,20 @@ describe MSpecCI, "#run" do
0
     @script.run
0
   end
0
 
0
+  it "registers a tag filter for 'critical'" do
0
+    filter = mock("critical filter")
0
+    TagFilter.should_receive(:new).with(:exclude, 'critical').and_return(filter)
0
+    filter.should_receive(:register)
0
+    @script.run
0
+  end
0
+
0
+  it "registers a tag filter for 'unsupported'" do
0
+    filter = mock("unsupported filter")
0
+    TagFilter.should_receive(:new).with(:exclude, 'unsupported').and_return(filter)
0
+    filter.should_receive(:register)
0
+    @script.run
0
+  end
0
+
0
   it "processes the files" do
0
     MSpec.should_receive(:process)
0
     @script.run

0
@@ -1,6 +1,7 @@
0
 require File.dirname(__FILE__) + '/../../spec_helper'
0
 require 'mspec/runner/actions/debug'
0
 require 'mspec/runner/mspec'
0
+require 'mspec/runner/context'
0
 require 'mspec/runner/example'
0
 
0
 describe DebugAction do
0
@@ -18,7 +19,7 @@ end
0
 describe DebugAction, "#before" do
0
   before :each do
0
     MSpec.stub!(:read_tags).and_return([])
0
-    @state = ExampleState.new "Catch#me", "if you can"
0
+    @state = ExampleState.new ContextState.new("Catch#me"), "if you can"
0
   end
0
 
0
   it "does not invoke the debugger if the description does not match" do

0
@@ -18,7 +18,7 @@ end
0
 describe GdbAction, "#before" do
0
   before :each do
0
     MSpec.stub!(:read_tags).and_return([])
0
-    @state = ExampleState.new "Catch#me", "if you can"
0
+    @state = ExampleState.new ContextState.new("Catch#me"), "if you can"
0
   end
0
 
0
   it "does not invoke the debugger if the description does not match" do

0
@@ -94,7 +94,7 @@ describe TagAction, "#before" do
0
     action.exception?.should be_false
0
     action.exception ExceptionState.new(nil, nil, Exception.new("Fail!"))
0
     action.exception?.should be_true
0
-    action.before(ExampleState.new("describe", "it"))
0
+    action.before(ExampleState.new(ContextState.new("describe"), "it"))
0
     action.exception?.should be_false
0
   end
0
 end
0
@@ -111,7 +111,8 @@ end
0
 describe TagAction, "#after when action is :add" do
0
   before :each do
0
     MSpec.stub!(:read_tags).and_return([])
0
-    @state = ExampleState.new "Catch#me", "if you can"
0
+    context = ContextState.new "Catch#me"
0
+    @state = ExampleState.new context, "if you can"
0
     @tag = SpecTag.new "tag(comment):Catch#me if you can"
0
     SpecTag.stub!(:new).and_return(@tag)
0
     @exception = ExceptionState.new nil, nil, Exception.new("failed")
0
@@ -159,7 +160,8 @@ end
0
 describe TagAction, "#after when action is :del" do
0
   before :each do
0
     MSpec.stub!(:read_tags).and_return([])
0
-    @state = ExampleState.new "Catch#me", "if you can"
0
+    context = ContextState.new "Catch#me"
0
+    @state = ExampleState.new context, "if you can"
0
     @tag = SpecTag.new "tag(comment):Catch#me if you can"
0
     SpecTag.stub!(:new).and_return(@tag)
0
     @exception = ExceptionState.new nil, nil, Exception.new("failed")
0
@@ -207,7 +209,8 @@ end
0
 describe TagAction, "#finish" do
0
   before :each do
0
     $stdout = @out = IOStub.new
0<