blueprints 0.8.2 → 0.9.0

data/lib/blueprints/extensions/rspec.rb

@@ -1,10 +1,12 @@
 module DescribeHelper
   # Creates new before filter that builds blueprints before each spec.
+  # @param names (see Helper#build)
   def build_blueprint(*names)
     before { build_blueprint *names }
   end
 
-  # Same as #build_blueprint except that you can use it to build same blueprint several times.
+  # Same as DescribeHelper#build_blueprint except that you can use it to build same blueprint several times.
+  # @param names (see Helper#build)
   def build_blueprint!(*names)
     before { build_blueprint! *names }
   end

data/lib/blueprints/helper.rb

@@ -2,42 +2,74 @@ module Blueprints
   # A helper module that should be included in test framework. Adds methods <tt>build</tt> and <tt>demolish</tt>
   module Helper
     # Builds one or more blueprints by their names. You can pass names as symbols or strings. You can also pass additional
-    # options hash which will be available by calling <tt>options</tt> in blueprint block. Returns result of blueprint block.
-    #   # build :apple and orange blueprints
+    # options hash which will be available by calling <tt>options</tt> in blueprint block. Returns result of last blueprint block.
+    # @example build :apple and :orange blueprints.
     #   build :apple, :orange
-    #
-    #   # build :apple scenario with additional options
+    # @example build :apple blueprint with additional options.
     #   build :apple => {:color => 'red'}
-    #
-    #   # options can also be passed for several blueprints
+    # @example passing options to several blueprints.
     #   build :pear, :apple => {:color => 'red'}, :orange => {:color => 'orange'}
-    def build_blueprint(*names)
+    # @param [Array<Symbol, String, Hash>] names Names of blueprints/namespaces to build. Pass Hash if you want to pass additional options.
+    # @return Return value of last blueprint
+    def build(*names)
       Namespace.root.build(names, self, true)
     end
 
-    # Same as #build_blueprint except that you can use it to build same blueprint several times.
-    def build_blueprint!(*names)
-      Namespace.root.build(names, self, false)
+    # Same as #build except that you can use it to build same blueprint several times.
+    # @overload build!(*names)
+    #   @param [Array<Symbol, String, Hash>] names Names of blueprints/namespaces to build. Pass Hash if you want to pass additional options.
+    #   @return Return value of last blueprint
+    # @overload build!(count, *names)
+    #   @param [Integer] count Times to build passed blueprint
+    #   @param [Array<Symbol, String, Hash>] names Names of blueprints/namespaces to build. Pass Hash if you want to pass additional options.
+    #   @return [Array] Array of return values of last blueprint, which is same size as count that you pass
+    def build!(*names)
+      if names.first.is_a?(Integer)
+        (0...names.shift).collect { build! *names }
+      else
+        Namespace.root.build(names, self, false)
+      end
     end
 
-    # Returns attributes that are used to build blueprint. To set what attributes are used you need to call attributes
-    # method when defining blueprint like this:
-    #   blueprint :apple do
+    # Returns attributes that are used to build blueprint.
+    # @example Setting and retrieving attributes.
+    #   # In blueprint.rb file
+    #   attributes(:name => 'apple').blueprint :apple do
     #     Fruit.build attributes
-    #   end.attributes(:name => 'apple')
+    #   end
+    #
+    #   # In spec/test file
+    #   build_attributes :apple #=> {:name => 'apple'}
+    # @param [Symbol, String] name Name of blueprint/namespace.
+    # @return [Hash] Normalized attributes of blueprint/namespace
     def build_attributes(name)
-      Namespace.root[name].build_parents
-      Namespace.root[name].normalized_attributes.tap { Blueprints::Namespace.root.copy_ivars(self) }
+      blueprint = Namespace.root[name]
+      blueprint.build_parents(Namespace.root.eval_context)
+      Namespace.root.eval_context.normalize_hash(blueprint.attributes).tap { Namespace.root.eval_context.copy_instance_variables(self) }
     end
 
-    alias :build :build_blueprint
-    alias :build! :build_blueprint!
+    # Returns Blueprint::Dependency object that can be used to define dependencies on other blueprints.
+    # @example Building :post blueprint with different user.
+    #   build :post => {:user => d(:admin)}
+    # @example Building :post blueprint by first building :user_profile with :name => 'John', then taking value of @profile and calling +user+ on it.
+    #   build :post => {:user => d(:user_profile, :profile, :name => 'John').user}
+    # @see Blueprints::Dependency#initialize Blueprints::Dependency for accepted arguments.
+    # @return [Blueprints::Dependency] Dependency object that can be passed as option when building blueprint/namespace.
+    def d(*args)
+      Dependency.new(*args)
+    end
 
     # Demolishes built blueprints (by default simply calls destroy method on result of blueprint, but can be customized).
-    #
+    # @example Demolish :apple and :pear blueprints
     #   demolish :apple, :pear
+    # @param [Array<Symbol, String>] names Names of blueprints/namespaces to demolish.
     def demolish(*names)
-      names.each { |name| Namespace.root[name].demolish }
+      names.each { |name| Namespace.root[name].demolish(Namespace.root.eval_context) }
     end
+
+    alias :build_blueprint :build
+    alias :build_blueprint! :build!
+    alias :blueprint_dependency :d
+    alias :blueprint_demolish :demolish
   end
 end

data/lib/blueprints/namespace.rb

@@ -1,5 +1,5 @@
 module Blueprints
-  # Namespace class, inherits from <tt>Buildable</tt>. Allows adding and finding child blueprints/namespaces and building
+  # Namespace class, inherits from Buildable. Allows adding and finding child blueprints/namespaces and building
   # all it's children.
   class Namespace < Buildable
     cattr_accessor :root
@@ -7,20 +7,27 @@ module Blueprints
     delegate :empty?, :size, :to => :@children
 
     # Creates namespace by name. See Buildable#new.
-    def initialize(name)
-      super(name)
+    # @param name (see Buildable#initialize)
+    # @param context (see Buildable#initialize)
+    def initialize(name, context)
       @children = {}
+      super(name, context)
     end
 
-    # Adds child to namespaces children. Child should be instance of Buildable.
+    # Adds child to namespaces children. Warns if this will overwrite existing child.
+    # @param [Blueprints::Buildable] child Namespace or blueprint to add as a child.
     def add_child(child)
+      Blueprints.warn("Overwriting existing blueprint", child) if @children[child.name]
       @children[child.name] = child
-      child.namespace = self
     end
 
-    # Finds child by relative name. Raises BlueprintNotFoundError if child can't be found.
+    # Finds child by relative name.
+    # @param [String] path Path to child. Path parts should be joined with '.' symbol.
+    # @return [Blueprints::Buildable] Blueprint or namespace that matches path.
+    # @raise [BlueprintNotFoundError] If child can't be found.
     def [](path)
       child_name, path = path.to_s.split('.', 2)
+
       child = @children[child_name.to_sym] or raise BlueprintNotFoundError, child_name
       if path
         child[path]
@@ -29,14 +36,26 @@ module Blueprints
       end
     end
 
-    # Builds all children and sets instance variable named by name of namespace with the results.
-    def build_self(build_once = true)
-      self.result = @children.collect {|p| p.last.build }.uniq
+    # Builds all children and sets an instance variable named by name of namespace with the results.
+    # @param eval_context (see Buildable#build)
+    # @param build_once (see Buildable#build)
+    # @param options (see Buildable#build)
+    # @return [Array] Results of all blueprints.
+    def build_self(eval_context, build_once, options)
+      result(eval_context) { @children.values.collect { |child| child.build(eval_context, build_once, options) }.uniq }
+    end
+
+    # Demolishes all child blueprints and namespaces.
+    # @param [Blueprints::EvalContext] eval_context Eval context that this namespace was built in.
+    def demolish(eval_context)
+      @children.each_value { |blueprint| blueprint.demolish(eval_context) }
     end
 
-    # Demolished all child blueprints and namespaces
-    def demolish
-      @children.each_value(&:demolish)
+    protected
+
+    def update_context(options)
+      @children.each_value { |child| child.update_context(options) }
+      super
     end
   end
 end

data/lib/blueprints/root_namespace.rb

@@ -1,68 +1,67 @@
+
 module Blueprints
   # Defines a root namespace that is used when no other namespace is. Apart from functionality in namespace it also allows
   # building blueprints/namespaces by name. Is also used for copying instance variables between blueprints/contexts/global
   # context.
   class RootNamespace < Namespace
-    attr_reader :context, :executed_blueprints
+    # Lists of executed blueprints (to prevent executing twice). Cleared before each test.
+    attr_reader :executed_blueprints
+    # Context that blueprints/namespaces are built against. Reset before each test.
+    attr_writer :eval_context
 
+    # Initialized new root context.
     def initialize
       @executed_blueprints = @global_executed_blueprints = []
       @auto_iv_list = Set.new
 
-      super ''
+      super '', Context.new
     end
 
-    # Loads all instance variables from global context to current one.
+    # Loads all instance variables from global context to current one. Creates new eval context.
     def setup
+      @eval_context = EvalContext.new
       (@executed_blueprints - @global_executed_blueprints).each(&:undo!)
       @executed_blueprints = @global_executed_blueprints.clone
-      @context = Blueprints::Context.new
 
       if Blueprints.config.transactions
-        Marshal.load(@global_variables).each { |name, value| @context.instance_variable_set(name, value) }
+        Marshal.load(@global_variables).each { |name, value| eval_context.instance_variable_set(name, value) }
       else
         build(Blueprints.config.prebuild)
       end
     end
 
-    # Copies all instance variables from current context to another one.
-    def copy_ivars(to)
-      @context.instance_variables.each do |iv|
-        to.instance_variable_set(iv, @context.instance_variable_get(iv))
-      end
-    end
-
     # Sets up global context and executes prebuilt blueprints against it.
+    # @param [Array<Symbol, String>] blueprints Names of blueprints that are prebuilt.
     def prebuild(blueprints)
-      @context = Blueprints::Context.new
       build(blueprints) if blueprints
 
       @global_executed_blueprints = @executed_blueprints
-      @global_variables = Marshal.dump(@context.instance_variables.each_with_object({}) { |iv, hash| hash[iv] = @context.instance_variable_get(iv) })
+      @global_variables = Marshal.dump(eval_context.instance_variables.each_with_object({}) { |iv, hash| hash[iv] = eval_context.instance_variable_get(iv) })
     end
 
     # Builds blueprints that are passed against current context. Copies instance variables to context given if one is given.
-    def build(names, context = nil, build_once = true)
+    # @param [Array<Symbol, String>] names List of blueprints/namespaces to build.
+    # @param current_context Object to copy instance variables from eval context after building to.
+    # @param build_once (see Buildable.build)
+    # @return Result of last blueprint/namespace.
+    def build(names, current_context = nil, build_once = true)
       names = [names] unless names.is_a?(Array)
       result = names.inject(nil) do |result, member|
         if member.is_a?(Hash)
-          member.map { |name, options| self[name].build(build_once, options) }.last
+          member.map { |name, options| self[name].build(eval_context, build_once, options) }.last
         else
-          self[member].build(build_once)
+          self[member].build(eval_context, build_once)
         end
       end
 
-      copy_ivars(context) if context
+      eval_context.copy_instance_variables(current_context) if current_context
       result
     end
 
-    # Sets instance variable in current context to passed value. If instance variable with same name already exists, it
-    # is set only if it was set using this same method
-    def add_variable(name, value)
-      if not @context.instance_variable_defined?(name) or @auto_iv_list.include?(name)
-        @auto_iv_list << name
-        @context.instance_variable_set(name, value)
-      end
+    # Return current eval context or creates a new one.
+    # @return [Blueprints::EvalContext] Eval context to be used to build blueprints.
+    def eval_context
+      @eval_context ||= EvalContext.new
     end
 
     @@root = RootNamespace.new

data/lib/blueprints/version.rb

@@ -0,0 +1,3 @@
+module Blueprints
+  VERSION = '0.9.0'
+end

data/spec/{active_record/blueprint.rb → blueprint.rb}

@@ -1,19 +1,15 @@
-blueprint :error do
-  raise 'error'
-end
-
 blueprint :apple do
-  Fruit.create! :species => 'apple'
+  Fruit.blueprint :species => 'apple'
 end
 
 blueprint :many_apples => [:apple, :apple, :apple]
 
 blueprint :bananas_and_apples => :apple do
-  @banana = Fruit.create! :species => 'banana'
+  @banana = Fruit.blueprint :species => 'banana'
 end
 
 blueprint :orange do
-  Fruit.create! :species => 'orange'
+  Fruit.blueprint :species => 'orange'
 end
 
 blueprint :fruit => [:apple, :orange] do
@@ -25,11 +21,11 @@ blueprint :bananas_and_apples_and_oranges => [:bananas_and_apples, :orange] do
 end
 
 blueprint :cherry do
-  Fruit.create! :species => 'cherry', :average_diameter => 3
+  Fruit.blueprint :species => 'cherry', :average_diameter => 3
 end
 
 blueprint :big_cherry => :cherry do
-  Fruit.create! options.reverse_merge(:species => @cherry.species, :average_diameter => 7)
+  Fruit.blueprint options.reverse_merge(:species => @cherry.species, :average_diameter => 7)
 end
 
 blueprint :cherry_basket => [:big_cherry, :cherry] do
@@ -49,15 +45,15 @@ end
 
 Fruit.blueprint(:acorn, :species => 'Acorn', :tree => d(:oak))
 blueprint :small_acorn do
-  @small_acorn = build :acorn => {:average_diameter => 1}
   @small_acorn_options = options
+  build :acorn => {:average_diameter => 1}
 end
 blueprint(:huge_acorn => :huge_oak).extends(:acorn, :average_diameter => 100)
 
 namespace :pitted => :pine do
   Tree.blueprint :peach_tree, :name => 'pitted peach tree'
-  Fruit.blueprint(:peach, :species => 'pitted peach', :tree => :@peach_tree).depends_on(:peach_tree)
-  Fruit.blueprint(:acorn, :species => 'pitted acorn', :tree => :@oak).depends_on(:oak)
+  Fruit.blueprint :peach, :species => 'pitted peach', :tree => d(:'pitted.peach_tree')
+  Fruit.blueprint :acorn, :species => 'pitted acorn', :tree => d(:oak)
 
   namespace :red => :orange do
     Fruit.blueprint(:apple, :species => 'pitted red apple')
@@ -65,18 +61,19 @@ namespace :pitted => :pine do
 end
 
 blueprint :apple_with_params do
-  Fruit.create! options.reverse_merge(:species => 'apple')
+  Fruit.blueprint options.reverse_merge(:species => 'apple')
 end
 
-namespace :attributes do
+attributes(:average_diameter => 10, :species => 'fruit with attributes').namespace :attributes do
   blueprint :cherry do
     Fruit.blueprint attributes
   end.attributes(:species => 'cherry')
 
   Fruit.blueprint :shortened_cherry, :species => 'cherry'
 
-  Fruit.blueprint :dependent_cherry1, :tree => d(:pine, :the_pine)
-  Fruit.blueprint(:dependent_cherry2, :tree => :@the_pine).depends_on(:pine)
-end.attributes(:average_diameter => 10, :species => 'fruit with attributes')
+  Fruit.blueprint :dependent_cherry, :tree => d(:pine, :the_pine)
+end
 
 blueprint :circular_reference => :circular_reference
+
+Tree.blueprint :name => 'infered'

data/spec/{active_record/blueprints_spec.rb → blueprints_spec.rb}

@@ -67,16 +67,30 @@ describe Blueprints do
     end
   end
 
+  describe "build per describe" do
+    unless File.dirname(__FILE__) =~ /test$/
+      build_blueprint :apple
+
+      it "should have cherry" do
+        @apple.should_not be_nil
+      end
+
+      it "should have correct cherry species" do
+        @apple.species.should == 'apple'
+      end
+    end
+  end
+
   describe 'with preloaded cherry scenario' do
     it "should have correct size after changed by second test" do
       @cherry.average_diameter.should == 3
-      @cherry.update_attribute(:average_diameter, 1)
+      @cherry.blueprint(:average_diameter => 1)
       @cherry.average_diameter.should == 1
     end
 
     it "should have correct size" do
       @cherry.average_diameter.should == 3
-      @cherry.update_attribute(:average_diameter, 5)
+      @cherry.blueprint(:average_diameter => 5)
       @cherry.average_diameter.should == 5
     end
 
@@ -94,7 +108,7 @@ describe Blueprints do
       demolish :apple
       Fruit.all.should_not include(@apple)
       build :apple
-      Fruit.last.should == @apple
+      Fruit.all.should include(@apple)
     end
 
     it "should overwrite auto created instance variable with another auto created one" do
@@ -120,11 +134,11 @@ describe Blueprints do
     end
 
     it "should create only one apple" do
-      Fruit.all(:conditions => 'species = "apple"').size.should == 1
+      Fruit.all(:conditions => {:species => "apple"}).size.should == 1
     end
 
     it "should create only two cherries even if they were preloaded" do
-      Fruit.all(:conditions => 'species = "cherry"').size.should == 2
+      Fruit.all(:conditions => {:species => "cherry"}).size.should == 2
     end
 
     it "should contain cherries in basket if basket is loaded in test and cherries preloaded" do
@@ -132,26 +146,6 @@ describe Blueprints do
     end
   end
 
-  describe 'transactions' do
-    before do
-      build :apple
-    end
-
-    it "should drop only inner transaction" do
-      @apple.reload.should_not be_nil
-      begin
-        ActiveRecord::Base.transaction do
-          f = Fruit.create(:species => 'orange')
-          f.reload.should_not be_nil
-          raise 'some error'
-        end
-      rescue
-      end
-      @apple.reload.should_not be_nil
-      Fruit.find_by_species('orange').should be_nil
-    end
-  end
-
   describe 'errors' do
     it 'should raise ScenarioNotFoundError when scenario could not be found' do
       lambda {
@@ -164,12 +158,6 @@ describe Blueprints do
         build :parent_not_existing
       }.should raise_error(Blueprints::BlueprintNotFoundError)
     end
-
-    it 'should raise TypeError when scenario name is not symbol or string' do
-      lambda {
-        Blueprints::Blueprint.new(1, __FILE__)
-      }.should raise_error(TypeError, "Pass blueprint names as strings or symbols only, cannot define blueprint 1")
-    end
   end
 
   describe 'with active record blueprints extensions' do
@@ -202,7 +190,7 @@ describe Blueprints do
 
     it "should normalize attributes when updating with blueprint method" do
       build :cherry, :oak
-      @cherry.blueprint(:tree => :@oak)
+      build :cherry => {:tree => d(:oak)}
       @cherry.tree.should == @oak
     end
 
@@ -213,8 +201,7 @@ describe Blueprints do
     end
 
     it "should allow to pass array of hashes to blueprint method" do
-      Fruit.create
-      fruits = Fruit.blueprint([{:species => 'fruit1'}, {:species => 'fruit2'}])
+      fruits = Fruit.blueprint({:species => 'fruit1'}, {:species => 'fruit2'})
       fruits.collect(&:species).should == %w{fruit1 fruit2}
     end
 
@@ -331,23 +318,27 @@ describe Blueprints do
     end
   end
 
-  it "should allow to build! without checking if it was already built" do
-    build! :big_cherry, :big_cherry => {:species => 'not so big cherry'}
-    Fruit.count.should == 4
-    Fruit.find_by_species('not so big cherry').should_not be_nil
-  end
+  describe "build!" do
+    it "should allow to building same blueprint again" do
+      build! :big_cherry, :big_cherry => {:species => 'not so big cherry'}
+      Fruit.count.should == 4
+      Fruit.first(:conditions => {:species => 'not so big cherry'}).should_not be_nil
+    end
 
-  it "should warn when blueprint with same name exists" do
-    STDERR.expects(:puts).with("**WARNING** Overwriting existing blueprint: 'overwritten'")
-    STDERR.expects(:puts).with(regexp_matches(/blueprints_(spec|test)\.rb:\d+:in `new'/))
-    Blueprints::Blueprint.new(:overwritten, __FILE__)
-    Blueprints::Blueprint.new(:overwritten, __FILE__)
+    it "should allow building same blueprint n times" do
+      oaks = build! 5, :oak
+      oaks.should have(5).items
+      oaks.each do |oak|
+        oak.should be_instance_of(Tree)
+        oak.name.should == 'Oak'
+      end
+    end
   end
 
   describe 'attributes' do
     it "should allow to extract attributes from blueprint" do
-      build_attributes('attributes.cherry').should == {:species => 'cherry'}
-      build_attributes('attributes.shortened_cherry').should == {:species => 'cherry'}
+      build_attributes('attributes.cherry').should == {:species => 'cherry', :average_diameter => 10}
+      build_attributes('attributes.shortened_cherry').should == {:species => 'cherry', :average_diameter => 10}
       build_attributes(:big_cherry).should == {}
     end
 
@@ -367,13 +358,7 @@ describe Blueprints do
     end
 
     it "should return build attributes for dependencies" do
-      attrs = build_attributes('attributes.dependent_cherry1')
-      @the_pine.should_not be_nil
-      attrs[:tree].should == @the_pine
-    end
-
-    it "should return build attributes for :@var" do
-      attrs = build_attributes('attributes.dependent_cherry2')
+      attrs = build_attributes('attributes.dependent_cherry')
       @the_pine.should_not be_nil
       attrs[:tree].should == @the_pine
     end
@@ -383,11 +368,7 @@ describe Blueprints do
     build :circular_reference
   end
 
-  it "should rewrite trace" do
-    begin
-      build :error
-    rescue RuntimeError => e
-      e.backtrace[0].should == "spec/active_record/blueprint.rb:2:in blueprint 'error'"
-    end
+  it "should allow inferring blueprint name" do
+    build(:infered).name.should == 'infered'
   end
 end