blueprints 0.8.2 → 0.9.0

data/lib/blueprints/configuration.rb

@@ -1,16 +1,26 @@
 module Blueprints
+  # Contains configuration of blueprints. Instance of this is yielded in Blueprints.enable block.
+  # @example Configuring through Blueprints.enable block
+  #   Blueprints.enable do |config|
+  #     config.prebuild = :user, :profile
+  #   end
+  # @example Configuring directly
+  #   Blueprints.config.transactions = false
   class Configuration
-    SUPPORTED_ORMS = [nil, :active_record]
     # Allows passing custom filename pattern in case blueprints are held in place other than spec/blueprint, test/blueprint, blueprint.
     attr_reader :filename
     # Allows passing scenarios that should be prebuilt and available in all tests. Works similarly to fixtures.
     attr_accessor :prebuild
-    # Allows passing custom root folder to use in case of non rails project. Defaults to RAILS_ROOT or current folder if RAILS_ROOT is not defined.
+    # Allows passing custom root folder to use in case of non rails project. Defaults to Rails.root or current folder if Rails is not defined.
     attr_reader :root
     # By default blueprints runs each test in it's own transaction. This may sometimes be not desirable so this options allows to turn this off.
     attr_accessor :transactions
+    # Default attributes are used when blueprints has no name specified.
+    attr_reader :default_attributes
 
-    # Sets default attributes for all attributes
+    # Initializes new Configuration object with default attributes.
+    # By defaults filename patterns are: blueprint.rb and blueprint/*.rb in spec, test and root directories.
+    # Also by default prebuildable blueprints list is empty, transactions are enabled and root is set to Rails.root or current directory.
     def initialize
       self.filename = [nil, "spec", "test"].map do |dir|
         ["blueprint"].map do |file|
@@ -18,10 +28,10 @@ module Blueprints
           ["#{path}.rb", File.join(path, "*.rb")]
         end
       end.flatten
-      @orm = :active_record
       @prebuild = []
       @transactions = true
       @root = defined?(Rails) ? Rails.root : Pathname.pwd
+      @default_attributes = [:name]
     end
 
     def filename=(value)
@@ -31,5 +41,9 @@ module Blueprints
     def root=(value)
       @root = Pathname.new(value)
     end
+
+    def default_attributes=(value)
+      @default_attributes = Array(value)
+    end
   end
 end

data/lib/blueprints/context.rb

@@ -1,11 +1,154 @@
 module Blueprints
-  # Class that blueprint blocks are evaluated against. Allows you to access options that were passed to build method.
+  # Class that blueprint files are evaluated against. Has methods for setting and retrieving attributes and dependencies.
+  # Allows defining new blueprints and namespaces.
   class Context
-    attr_accessor :options, :attributes
+    @@chain = []
 
-    # Method that allows building one blueprint inside of another. Simply delegates to root namespace.
-    def build(*names)
-      Namespace.root.build(*names)
+    attr_reader :dependencies, :file
+
+    # Initializes new context with passed parent, attributes, dependencies, file and namespace.
+    # Attributes and dependencies are automatically merged with parents' attributes and dependencies.
+    # File and namespace are automatically set to parent counterparts unless they are explicitly changed.
+    # @param [Hash] options Options for new context.
+    # @option options [Hash] :attributes ({}) List of attributes, merged with parent attributes.
+    # @option options [Array<String, Symbol>] :dependencies ([]) List of dependencies, merged with parent dependencies.
+    # @option options [Pathname] :file File this context is evaluated in. Should be passed for top level contexts only.
+    # @option options [Blueprints::Namespace] :namespace Namespace that new blueprints and namespaces should be children of.
+    # @option options [Blueprints::Context] :parent Parent context that is used to retrieve unchanged values.
+    def initialize(options = {})
+      options.assert_valid_keys(:dependencies, :attributes, :file, :parent, :namespace)
+      @dependencies = (options[:dependencies] || []).collect(&:to_sym)
+      @attributes   = options[:attributes] || {}
+      @file         = options[:file]
+      @namespace    = options[:namespace]
+
+      if parent = options[:parent]
+        @attributes.reverse_merge!(parent.attributes)
+        @dependencies = (parent.dependencies + @dependencies).uniq
+        @file         ||= parent.file
+        @namespace    ||= parent.namespace
+      end
+    end
+
+    # Checks if two contexts are equal by comparing attributes, dependencies, namespace and file
+    # @param [Blueprints::Context] context Context to compare this one to.
+    # @return [true, false] Whether contexts are equal or not.
+    def ==(context)
+      @dependencies == context.dependencies and @attributes == context.attributes and @file == context.file and @namespace == context.namespace
+    end
+
+    # Defines a new blueprint by name and block passed.
+    # @example Define blueprint.
+    #   blueprint :user do
+    #     User.blueprint :name => 'User'
+    #   end
+    # @param name (see Buildable#initialize)
+    # @return [Blueprints::Blueprint] Newly defined blueprint.
+    def blueprint(name = nil, &block)
+      Blueprint.new(name, self, &block)
+    end
+
+    # @overload namespace(name, &block)
+    #   Defines new namespace by name, and evaluates block against it.
+    #   @example Define namespace and blueprint in it.
+    #     namespace :banned do
+    #       blueprint :user do
+    #         User.blueprint :name => 'User'
+    #       end
+    #     end
+    #   @param [String, Symbol] name Name of namespace.
+    #   @return [Blueprints::Namespace] Newly defined namespace.
+    # @overload namespace
+    #   Returns namespace for this context.
+    #   @return [Blueprints::Namespace] Namespace for this context.
+    def namespace(name = nil, &block)
+      if name
+        Namespace.new(name, self).tap do |namespace|
+          with_context(:namespace => namespace, &block)
+        end
+      else
+        @namespace
+      end
+    end
+
+    # @overload attributes(new_attributes, &block)
+    #   Yields and returns child context that has new attributes set.
+    #   @example Define blueprint with attributes
+    #     attributes(:name => 'User').blueprint(:user) do
+    #       User.blueprint attributes
+    #     end
+    #   @example Define multiple blueprints with same attributes
+    #     attributes(:name => 'User') do
+    #       blueprint(:user1) do
+    #         User.blueprint attributes
+    #       end
+    #
+    #       blueprint(:user2) do
+    #         User.blueprint attributes
+    #       end
+    #     end
+    #   @param [Hash] new_attributes Attributes for child context.
+    #   @return [Blueprints::Context] Child context
+    # @overload attributes
+    #   Returns attributes of context.
+    #   @return [Hash] Attributes of context.
+    def attributes(new_attributes = nil, &block)
+      if new_attributes
+        with_context(:attributes => new_attributes, &block)
+      else
+        @attributes
+      end
+    end
+
+    # Yields and returns child context that has dependencies set.
+    # @example Define blueprint with dependencies
+    #   depends_on(:user, :admin).blueprint(:user_and_admin)
+    # @example Define multiple blueprints with same dependencies.
+    #   depends_on :user, :admin do
+    #     blueprint :user_and_admin
+    #     blueprint :admin_and_user
+    #   end
+    # @param [Array<Symbol, String>] new_dependencies Dependencies for child context.
+    # @return [Blueprints::Context] Child context
+    def depends_on(*new_dependencies, &block)
+      with_context(:dependencies => new_dependencies, &block)
+    end
+
+    # Yields and returns child context that has new options set.
+    # @param options (see Context#initialize)
+    # @return [Blueprints::Context] Child context
+    def with_context(options, &block)
+      Context.eval_within_context(options.merge(:parent => self), &block)
+    end
+
+    # Initializes new Blueprints::Dependency object.
+    # @overload d(name, options = {})
+    #   @param name (see Dependency#initialize)
+    #   @param options (see Dependency#initialize)
+    # @overload d(name, instance_variable_name, options = {})
+    #   @param name (see Dependency#initialize)
+    #   @param instance_variable_name (see Dependency#initialize)
+    #   @param options (see Dependency#initialize)
+    def d(*args)
+      Dependency.new(*args)
+    end
+
+    # Return current context.
+    # @return [Blueprints::Context] Current context.
+    def self.current
+      @@chain.last
+    end
+
+    # Creates child context and sets it as current. Evaluates block and file within child context if any are passed.
+    # @param [Hash] new_options Options for child context.
+    def self.eval_within_context(new_options, &block)
+      @@chain << context = new(new_options)
+
+      file = new_options[:file]
+      context.instance_eval(File.read(file), file) if file
+      context.instance_eval(&block) if block
+
+      @@chain.pop
     end
   end
 end

data/lib/blueprints/database_cleaner_fix.rb

@@ -0,0 +1,9 @@
+module ActiveRecord
+  module ConnectionAdapters
+    class Mysql2Adapter < AbstractAdapter
+      def truncate_table(table_name)
+        execute("TRUNCATE TABLE #{quote_table_name(table_name)};")
+      end
+    end
+  end
+end if defined?(ActiveRecord)

data/lib/blueprints/dependency.rb

@@ -1,35 +1,46 @@
-# Class for defining blueprint dependencies. Accepts up to 3 params:
-# * name - pass the name of blueprint to build when trying to access value of this dependency.
-# * iv_name (optional) - pass the name of instance variable to use for value. Defaults to same name as blueprint name.
-# * options (optional) - pass options that are then passed to blueprint when building.
-# Examples:
-#   Blueprints::Dependency.new(:blueprint).value # Builds blueprint 'blueprint' and returns value of @blueprint instance variable
-#   Blueprints::Dependency.new(:blueprint, value).value # Builds blueprint 'blueprint' and returns value of @value instance variable
-#   Blueprints::Dependency.new(:blueprint, :option => true).value # Builds blueprint 'blueprint' with options and returns value of @value instance variable
-#
-# Blueprints::Dependency objects also catch all missing methods. They are later replayed on instance variable when getting value. Example:
-#   d = Blueprints::Dependency.new(:blueprint).name.size
-#   d.value # => 4 when @blueprint.name == 'John'
+# Class for defining blueprint dependencies.
 class Blueprints::Dependency
   instance_methods.each { |m| undef_method m if m =~ /^(to_|id$)/ }
 
-  # Initializes new copy of Blueprints::Dependency with name, iv_name and options.
+  # Initializes new Blueprints::Dependency object.
+  # @example Build blueprint 'blueprint' and returns value of @blueprint instance variable.
+  #   Blueprints::Dependency.new(:blueprint)
+  # @example Build blueprint 'blueprint' and returns value of @value instance variable.
+  #   Blueprints::Dependency.new(:blueprint, value)
+  # @example Build blueprint 'blueprint' with options and returns value of @value instance variable.
+  #   Blueprints::Dependency.new(:blueprint, :option => true)
+  # @example Register called methods
+  #   d = Blueprints::Dependency.new(:blueprint).name.size
+  # @overload d(name, options = {})
+  #   Use result of blueprint/namespace +name+ and pass options when building.
+  #   @param [Symbol, String] name Name of blueprint/namespace.
+  #   @param [Hash] options Options to pass when building blueprint/namespace.
+  # @overload d(name, instance_variable_name, options = {})
+  #   Build blueprint/namespace with options and use differently names instance variable as result.
+  #   @param [Symbol, String] name Name of blueprint/namespace.
+  #   @param [Symbol, String] instance_variable_name Name of instance variable to use as a result.
+  #   @param [Hash] options Options to pass when building blueprint/namespace.
   def initialize(name, *args)
-    @name = name
-    @options = args.extract_options!
-    @iv_name = args.first || @name
+    @name     = name
+    @options  = args.extract_options!
+    @iv_name  = (args.first || @name).to_s.gsub('.', '_')
     @registry = []
   end
 
-  # Builds blueprint (if necessary) and returns the value of instance variable.
-  def blueprint_value
-    Blueprints::RootNamespace.root.build @name => @options
-    @registry.inject(Blueprints::RootNamespace.root.context.instance_variable_get(:"@#{@iv_name}")) do |value, (method, args, block)|
-      value.send(method, *args, &block)
+  # Returns block that builds blueprint (if necessary) takes instance variable for this dependency and calls all methods from method registry.
+  # @return [Proc] Proc that can be called to return value for this dependency.
+  def to_proc
+    name, options, registry, variable_name = @name, @options, @registry, @iv_name
+    Proc.new do
+      build name => options
+      registry.inject(instance_variable_get(:"@#{variable_name}")) do |value, (method, args, block)|
+        value.send(method, *args, &block)
+      end
     end
   end
 
   # Catches all missing methods to later replay when asking for value.
+  # @return [Blueprints::Dependency] self
   def method_missing(method, *args, &block)
     @registry << [method, args, block]
     self

data/lib/blueprints/eval_context.rb

@@ -0,0 +1,51 @@
+module Blueprints
+  class EvalContext
+    # Copy instance variables to another object.
+    # @param target Object to copy instance variables to.
+    def copy_instance_variables(target)
+      instance_variables.each do |iv_name|
+        target.instance_variable_set(iv_name, instance_variable_get(iv_name))
+      end
+    end
+
+    # Sets options and attributes and evaluates block against self.
+    # @param [Blueprints::Context] context Context of buildable object. Used to extract attributes.
+    # @param [Hash] options Options hash, merged into attributes.
+    def instance_eval(context, options, &block)
+      options = normalize_hash(options)
+      define_singleton_method(:options) { options }
+      attributes = normalize_hash(context.attributes).merge(options)
+      define_singleton_method(:attributes) { attributes }
+
+      super(&block)
+    end
+
+    # Builds blueprints by delegating to root namespace.
+    # @param [Array<String, Symbol>] blueprints Names of buildables.
+    # @return Result of last buildable.
+    def build(*blueprints)
+      Namespace.root.build(blueprints)
+    end
+
+    # Normalizes attributes hash by evaluating all Proc and Blueprints::Dependency objects against itself.
+    # @param [Hash] hash Attributes hash.
+    # @return [Hash] Normalized hash.
+    def normalize_hash(hash)
+      hash.each_with_object({}) do |(attr, value), normalized|
+        normalized[attr] = if value.respond_to?(:to_proc) and not Symbol === value
+                             instance_exec(&value)
+                           else
+                             value
+                           end
+      end
+    end
+
+    private
+
+    def define_singleton_method(name, &block)
+      singleton_class.class_eval do
+        define_method(name, &block)
+      end
+    end
+  end
+end

data/lib/blueprints/extensions.rb

@@ -0,0 +1,115 @@
+module Blueprints::Extensions
+  # Here to support ActiveSupport 2.x. Will be removed once support for ActiveRecord 2.3 is terminated.
+  module Extendable
+    def self.included(mod)
+      if defined?(ActiveSupport::Concern)
+        mod.extend ActiveSupport::Concern
+      else
+        def mod.included(mod)
+          mod.extend Blueprints::Extensions::Blueprintable::ClassMethods
+        end
+      end
+    end
+  end
+
+# Include this module into your class if you need klass.blueprint and object.blueprint methods.
+  module Blueprintable
+    include Extendable
+
+    module ClassMethods
+      # @overload blueprint(attributes)
+      #   Does same as +create!+ method except that it also bypasses attr_protected and attr_accessible. Typically used in blueprint block.
+      #   @example Create post for user
+      #     @user.posts.blueprint(:title => 'first post', :text => 'My first post')
+      #   @param [Hash, Array<Hash>] attributes Attributes used to create objects.
+      #   @return Created object(s).
+      # @overload blueprint(name, attributes = {})
+      #   Defines new blueprint that creates an object with attributes passed.
+      #   @example Create blueprint named :post.
+      #     Post.blueprint(:post, :title => 'first post', :text => 'My first post', :user => d(:user)).depends_on(:board)
+      #   @param [String, Symbol, Hash] name Name of blueprint.
+      #   @param [Hash] attributes Attributes hash.
+      #   @return [Blueprints::Blueprint] Defined blueprint.
+      def blueprint(*args)
+        if Blueprints::Context.current
+          attrs = args.extract_options!
+          define_blueprint(args.first, attrs)
+        else
+          objects = args.collect { |attrs| blueprint_object(attrs) }
+          args.size == 1 ? objects.first : objects
+        end
+      end
+
+      private
+
+      def define_blueprint(name, attrs)
+        klass = self
+        Blueprints::Context.current.attributes(attrs).blueprint(name) { klass.blueprint attributes }
+      end
+
+      def blueprint_object(attrs)
+        new.tap { |object| object.blueprint(attrs) }
+      end
+    end
+
+    # Updates attributes of object by calling setter methods. Does same as +update_attributes!+ except it also bypasses attr_protected and attr_accessible.
+    # @param [Hash] attributes Attributes that are used to update object.
+    def blueprint(attributes)
+      attributes.each do |attribute, value|
+        blueprint_attribute attribute, value
+      end
+    end
+
+    private
+
+    def blueprint_attribute(attribute, value)
+      send(:"#{attribute}=", value)
+    end
+  end
+
+  # Include this instead of Blueprints::Extensions::Blueprintable if record needs to persist, includes Blueprints::Extensions::Blueprintable
+  module Saveable
+    include Extendable
+    include Blueprintable
+
+    # Overrides object.blueprint to also call save!
+    def blueprint(attributes)
+      super(attributes)
+      save!
+    end
+  end
+
+  # Include this instead of Blueprints::Extensions::Saveable if you want non bang save method (eg.using datamapper)
+  module SoftSaveable
+    include Extendable
+    include Blueprintable
+
+    # Overrides object.blueprint to also call save
+    def blueprint(attributes)
+      super(attributes)
+      save
+    end
+  end
+
+  # Include this instead of Blueprints::Extensions::Saveable if you need support for dynamic attributes (eg. using mongodb)
+  module DynamicSaveable
+    include Extendable
+    include Saveable
+
+    private
+
+    def blueprint_attribute(attribute, value)
+      setter = :"#{attribute}="
+      if respond_to?(setter)
+        send(setter, value)
+      else
+        write_attribute(attribute, value)
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send(:include, Blueprints::Extensions::Saveable) if defined?(ActiveRecord)
+Mongoid::Document.send(:include, Blueprints::Extensions::DynamicSaveable) if defined?(Mongoid)
+MongoMapper::Document.send(:append_inclusions, Blueprints::Extensions::DynamicSaveable) if defined?(MongoMapper)
+DataMapper::Model.send(:append_inclusions, Blueprints::Extensions::SoftSaveable) if defined?(DataMapper)