blueprints 0.9.0 → 1.0.0

data/lib/blueprints/blueprint_name_proxy.rb

@@ -0,0 +1,34 @@
+# Acts as a proxy to buildables with regexp names. Used for caching purposes. Remembers name used and always uses it later.
+# Allows building and demolishing it's buildable.
+class Blueprints::BlueprintNameProxy
+  # Initializes new instance of proxy.
+  # @param [Symbol] name Name of buildable that this proxy uses.
+  # @param [Blueprints::Buildable] buildable Buildable itself, that can later be built of demolished.
+  def initialize(name, buildable)
+    @buildable = buildable
+    @name = name
+
+    match_data = buildable.name.match(name.to_s)
+    names = match_data.names.collect(&:to_sym) if match_data.respond_to?(:names)
+    names = (0...match_data.captures.size).collect { |ind| :"arg#{ind}" } if names.blank?
+    @options = Hash[names.zip(match_data.captures)]
+  end
+
+  # Allows building buildable. Merges regexp match data into options. If named regexp captures are used (Ruby 1.9 only),
+  # it will merge those names with appropriate values into options, otherwise options will be named arg0..n.
+  # @param environment (see Buildable#build)
+  # @param options (see Buildable#build)
+  # @return (see Buildable#build)
+  def build(environment, options = {})
+    options[:options] ||= {}
+    options[:options].merge!(@options)
+    options.merge!(:name => @name)
+    @buildable.build(environment, options)
+  end
+
+  # Allows demolishing buildable. Uses remembered name to determine name of variable to call destroy on.
+  # @param [Object] environment Eval context that this buildable was built in.
+  def demolish(environment)
+    @buildable.demolish(environment, @name)
+  end
+end

data/lib/blueprints/buildable.rb

@@ -1,5 +1,7 @@
 module Blueprints
   class Buildable
+    BUILDING_MESSAGE = 'While building blueprint'
+    
     delegate :namespace, :dependencies, :to => :@context
     attr_reader :name
 
@@ -11,10 +13,7 @@ module Blueprints
     def initialize(name, context)
       @context = context
 
-      if name.nil?
-        default_attribute = Blueprints.config.default_attributes.detect { |attribute| attributes.has_key?(attribute) }
-        name = attributes[default_attribute].parameterize('_') if default_attribute
-      end
+      name = self.class.infer_name(attributes) if name.nil?
       @name, parents = parse_name(name)
       depends_on(*parents)
 
@@ -47,22 +46,28 @@ module Blueprints
       end
     end
 
-    # Builds dependencies of blueprint and then blueprint itself.
-    # @param [Blueprints::EvalContext] eval_context Context to build buildable object in.
-    # @param [true, false] build_once Used if buildable is already built. If true then old one is updated else buildable is built again.
-    # @param [Hash] options List of options to be accessible in the body of a blueprint.
-    def build(eval_context, build_once = true, options = {})
-      return result(eval_context) if @building or (built? and build_once and options.blank?)
+    # Builds dependencies of buildable and then buildable itself.
+    # @param [Object] environment Context to build buildable object in.
+    # @param [Hash] options List of options to build this buildable with.
+    # @option options [Hash] :options ({}) List of options to be accessible in the body of a blueprint.
+    # @option options [true, false] :rebuild (false) If true this buildable is treated as not built yet and is rebuilt even if it was built before.
+    # @option options [Symbol] :strategy (:default) Strategy to use when building.
+    # @option options [Symbol] :name Name of blueprint to use when building. Is usually passed for blueprints with regexp names.
+    def build(environment, options = {})
+      return result(environment) if @building or (built? and not options[:rebuild] and options[:options].blank?)
       @building = true
 
-      each_namespace { |namespace| namespace.build_parents(eval_context) }
-      build_parents(eval_context)
-
-      result = build_self(eval_context, build_once, options)
+      result = nil
+      surface_errors do
+        each_namespace { |namespace| namespace.build_parents(environment) }
+        build_parents(environment)
+        result = build_self(environment, options)
+      end
       Namespace.root.executed_blueprints << self
 
-      @building = false
       result
+    ensure
+      @building = false
     end
 
     # Returns if blueprint has been built
@@ -78,9 +83,12 @@ module Blueprints
 
     # Returns full path to this buildable
     # @param [String] join_with Separator used to join names of parent namespaces and buildable itself.
+    # @param [#to_s] current_name Current name of this buildable. Used for regexp named buildables. Defaults to @name.
     # @return [String] full path to this buildable joined with separator
-    def path(join_with = '_')
-      (namespace.path(join_with) + join_with unless namespace.nil? or namespace.path.empty?).to_s + @name.to_s
+    def path(join_with = '_', current_name = nil)
+      current_name ||= @name
+      namespace_path = namespace.path(join_with) if namespace
+      [namespace_path.presence, current_name].compact.join(join_with)
     end
 
     # Returns full name for this buildable
@@ -90,9 +98,9 @@ module Blueprints
     end
 
     # Builds all dependencies. Should be called before building itself. Searches dependencies first in parent then in root namespace.
-    # @param [Blueprints::EvalContext] eval_context Context to build parents against.
+    # @param [Object] environment Context to build parents against.
     # @raise [Blueprints::BlueprintNotFoundError] If one of dependencies can't be found.
-    def build_parents(eval_context)
+    def build_parents(environment)
       @context.dependencies.each do |name|
         parent = begin
           namespace[name]
@@ -100,10 +108,18 @@ module Blueprints
           Namespace.root[name]
         end
 
-        parent.build(eval_context)
+        parent.build(environment)
       end
     end
 
+    # Infers name of buildable using default attributes from Blueprints.config
+    # @param [Hash] attributes Attributes of buildable object to infer the name from.
+    # @return [String] Inferred name
+    def self.infer_name(attributes)
+      default_attribute = Blueprints.config.default_attributes.detect { |attribute| attributes.has_key?(attribute) }
+      attributes[default_attribute].parameterize('_') if default_attribute
+    end
+
     protected
 
     def each_namespace
@@ -111,8 +127,8 @@ module Blueprints
       yield(namespace) while namespace = namespace.namespace
     end
 
-    def variable_name
-      :"@#{path}"
+    def variable_name(current_name = nil)
+      :"@#{path('_', current_name || @name)}"
     end
 
     def parse_name(name)
@@ -121,6 +137,8 @@ module Blueprints
       elsif name.respond_to?(:to_sym)
         name = name.to_sym unless name == ''
         return name, []
+      elsif name.is_a? Regexp
+        return name, []
       else
         raise TypeError, "Pass blueprint names as strings or symbols only, cannot define blueprint #{name.inspect}"
       end
@@ -133,17 +151,26 @@ module Blueprints
 
     private
 
-    def result(eval_context)
+    def result(environment, current_name = nil)
+      variable_name = self.variable_name(current_name)
       if block_given?
         yield.tap do |result|
-          if @auto_variable or not eval_context.instance_variable_defined?(variable_name)
-            eval_context.instance_variable_set(variable_name, result)
+          if @auto_variable or not environment.instance_variable_defined?(variable_name)
+            environment.instance_variable_set(variable_name, result)
             @auto_variable = true
           end
         end
       else
-        eval_context.instance_variable_get(variable_name)
+        environment.instance_variable_get(variable_name)
       end
     end
+
+    def surface_errors
+      yield
+    rescue StandardError => error
+      insert_at = error.backtrace.index { |line| line !~ /^#{BUILDING_MESSAGE}/ }
+      error.backtrace.insert(insert_at, "#{BUILDING_MESSAGE} '#{path}'")
+      raise
+    end
   end
 end

data/lib/blueprints/context.rb

@@ -133,6 +133,14 @@ module Blueprints
       Dependency.new(*args)
     end
 
+    # Finds blueprint/namespace by it's path
+    # @param path (see Namespace#[])
+    # @return (see Namespace#[])
+    def find(path)
+      @namespace[path]
+    end
+    alias [] find
+
     # Return current context.
     # @return [Blueprints::Context] Current context.
     def self.current

data/lib/blueprints/extensions.rb

@@ -33,7 +33,7 @@ module Blueprints::Extensions
       def blueprint(*args)
         if Blueprints::Context.current
           attrs = args.extract_options!
-          define_blueprint(args.first, attrs)
+          define_blueprint(args.first || Blueprints::Buildable.infer_name(attrs) || name.underscore, attrs)
         else
           objects = args.collect { |attrs| blueprint_object(attrs) }
           args.size == 1 ? objects.first : objects
@@ -44,7 +44,11 @@ module Blueprints::Extensions
 
       def define_blueprint(name, attrs)
         klass = self
-        Blueprints::Context.current.attributes(attrs).blueprint(name) { klass.blueprint attributes }
+        Blueprints::Context.current.attributes(attrs).blueprint(name) do
+          klass.blueprint attributes
+        end.blueprint(:new) do
+          klass.new.tap { |object| object.blueprint_without_save(attributes) }
+        end
       end
 
       def blueprint_object(attrs)
@@ -59,6 +63,7 @@ module Blueprints::Extensions
         blueprint_attribute attribute, value
       end
     end
+    alias blueprint_without_save blueprint
 
     private
 
@@ -109,7 +114,20 @@ module Blueprints::Extensions
   end
 end
 
-ActiveRecord::Base.send(:include, Blueprints::Extensions::Saveable) if defined?(ActiveRecord)
+if defined?(ActiveRecord)
+  ActiveRecord::Base.send(:include, Blueprints::Extensions::Saveable)
+  # AssociationCollection for ActiveRecord 3.0, Collection::Association for ActiveRecord 3.1
+  collection_class = defined?(ActiveRecord::Associations::CollectionProxy) ? ActiveRecord::Associations::CollectionProxy : ActiveRecord::Associations::AssociationCollection
+  collection_class.class_eval do
+    include Blueprints::Extensions::Blueprintable::ClassMethods
+
+    def blueprint_object(attrs)
+      create! do |object|
+        object.blueprint_without_save(attrs)
+      end
+    end
+  end
+end
 Mongoid::Document.send(:include, Blueprints::Extensions::DynamicSaveable) if defined?(Mongoid)
-MongoMapper::Document.send(:append_inclusions, Blueprints::Extensions::DynamicSaveable) if defined?(MongoMapper)
+MongoMapper::Document.send(:plugin, Blueprints::Extensions::DynamicSaveable) if defined?(MongoMapper)
 DataMapper::Model.send(:append_inclusions, Blueprints::Extensions::SoftSaveable) if defined?(DataMapper)

data/lib/blueprints/extensions/rspec.rb

@@ -1,24 +1,38 @@
-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
+module Blueprints
+  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 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
+    # 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
 
-  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
+
+    alias :build :build_blueprint
+    alias :blueprint_dependency :d
+    alias :build! :build_blueprint!
+  end
 end
 
 config_class = defined?(RSpec) ? RSpec : Spec::Runner
 config_class.configure do |config|
   config.include(Blueprints::Helper)
-  config.extend(DescribeHelper)
+  config.extend(Blueprints::DescribeHelper)
   config.before do
     Blueprints.setup(self)
   end

data/lib/blueprints/helper.rb

@@ -12,25 +12,33 @@ module Blueprints
     # @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)
+      Namespace.root.build(names, self)
     end
 
-    # Same as #build except that you can use it to build same blueprint several times.
+    # Same as Blueprints::Helper#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
+    #   @param names (see Helper#build)
+    #   @return (see Helper#build)
     # @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.
+    #   @param names (see Helper#build)
     #   @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)
+        Namespace.root.build(names, self, :rebuild => true)
       end
     end
 
+    # Same as Blueprints::Helper#build except it also allows you to pass strategy to use (#build always uses default strategy).
+    # @param [Symbol] strategy Strategy to use when building blueprint/namespace.
+    # @param names (see Helper#build)
+    # @return (see Helper#build)
+    def build_with(strategy, *names)
+      Namespace.root.build(names, self, :strategy => strategy)
+    end
+
     # Returns attributes that are used to build blueprint.
     # @example Setting and retrieving attributes.
     #   # In blueprint.rb file
@@ -44,8 +52,8 @@ module Blueprints
     # @return [Hash] Normalized attributes of blueprint/namespace
     def build_attributes(name)
       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) }
+      blueprint.build_parents(self)
+      blueprint.normalized_attributes(self)
     end
 
     # Returns Blueprint::Dependency object that can be used to define dependencies on other blueprints.
@@ -64,7 +72,7 @@ module 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(Namespace.root.eval_context) }
+      names.each { |name| Namespace.root[name].demolish(self) }
     end
 
     alias :build_blueprint :build

data/lib/blueprints/namespace.rb

@@ -3,14 +3,18 @@ module Blueprints
   # all it's children.
   class Namespace < Buildable
     cattr_accessor :root
-    attr_reader :children
     delegate :empty?, :size, :to => :@children
 
     # Creates namespace by name. See Buildable#new.
     # @param name (see Buildable#initialize)
     # @param context (see Buildable#initialize)
     def initialize(name, context)
-      @children = {}
+      @children = Hash.new do |hash, search_key|
+        pair = hash.detect do |name,|
+          name.is_a?(Regexp) and search_key.to_s =~ name
+        end
+        hash[search_key] = BlueprintNameProxy.new(search_key, pair[1]) if pair
+      end
       super(name, context)
     end
 
@@ -21,6 +25,12 @@ module Blueprints
       @children[child.name] = child
     end
 
+    # Returns all direct children blueprints and namespaces of this namespace.
+    # @return [Array<Blueprints::Buildable>] Array of direct children
+    def children
+      @children.values
+    end
+
     # 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.
@@ -36,23 +46,19 @@ module Blueprints
       end
     end
 
-    # 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) }
+    # @param [Object] environment Eval context that this namespace was built in.
+    def demolish(environment)
+      @children.each_value { |blueprint| blueprint.demolish(environment) }
     end
 
     protected
 
+    def build_self(environment, options)
+      children = Array(@children[:default] || @children.values)
+      result(environment) { children.collect { |child| child.build(environment, options) } }
+    end
+
     def update_context(options)
       @children.each_value { |child| child.update_context(options) }
       super

data/lib/blueprints/railtie.rb

@@ -0,0 +1,3 @@
+class Blueprints::Railtie < Rails::Railtie
+  config.app_generators.fixture_replacement :blueprints
+end

data/lib/blueprints/root_namespace.rb

@@ -6,8 +6,6 @@ module Blueprints
   class RootNamespace < Namespace
     # 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
@@ -17,53 +15,48 @@ module Blueprints
       super '', Context.new
     end
 
-    # Loads all instance variables from global context to current one. Creates new eval context.
-    def setup
-      @eval_context = EvalContext.new
+    # Loads all instance variables from global context to current one.
+    def setup(environment)
       (@executed_blueprints - @global_executed_blueprints).each(&:undo!)
       @executed_blueprints = @global_executed_blueprints.clone
 
       if Blueprints.config.transactions
-        Marshal.load(@global_variables).each { |name, value| eval_context.instance_variable_set(name, value) }
+        Marshal.load(@global_variables).each { |name, value| environment.instance_variable_set(name, value) }
       else
-        build(Blueprints.config.prebuild)
+        build(Blueprints.config.prebuild, environment)
       end
     end
 
-    # Sets up global context and executes prebuilt blueprints against it.
+    # Sets up a context and executes prebuilt blueprints against it.
     # @param [Array<Symbol, String>] blueprints Names of blueprints that are prebuilt.
     def prebuild(blueprints)
-      build(blueprints) if blueprints
+      environment = Object.new
+      environment.extend Blueprints::Helper
+      build(blueprints, environment) if blueprints
 
       @global_executed_blueprints = @executed_blueprints
-      @global_variables = Marshal.dump(eval_context.instance_variables.each_with_object({}) { |iv, hash| hash[iv] = eval_context.instance_variable_get(iv) })
+      @global_variables = Marshal.dump(environment.instance_variables.each_with_object({}) { |iv, hash| hash[iv] = environment.instance_variable_get(iv) })
     end
 
-    # Builds blueprints that are passed against current context. Copies instance variables to context given if one is given.
+    # Builds blueprints that are passed against current context.
     # @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)
+    # @param environment Object to build blueprints against.
+    # @param options (see Buildable#build)
+    # @option options (see Buildable#build)
     # @return Result of last blueprint/namespace.
-    def build(names, current_context = nil, build_once = true)
+    def build(names, environment, options = {})
       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(eval_context, build_once, options) }.last
+          member.map { |name, opts| self[name].build(environment, options.merge(:options => opts)) }.last
         else
-          self[member].build(eval_context, build_once)
+          self[member].build(environment, options)
         end
       end
 
-      eval_context.copy_instance_variables(current_context) if current_context
       result
     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
   end
 end