blueprints 0.8.2 → 0.9.0

data/features/support/env.rb

@@ -1,19 +1,16 @@
 require 'cucumber'
 require 'active_record'
-Root = File.expand_path(File.dirname(__FILE__) + '/../..')
-require File.expand_path(Root + '/lib/blueprints')
+require 'pathname'
+Root = Pathname.new(__FILE__).dirname.join('..', '..')
+$: << Root.join('lib').to_s
+
+require 'blueprints'
+require File.dirname(__FILE__) + "/../../spec/support/active_record/initializer"
 
-ActiveRecord::Base.logger = Logger.new("debug.log")
-databases = YAML::load_file(Root + "/spec/active_record/fixtures/database.yml")
-db_info = databases[ENV["DB"] || "test"]
-ActiveRecord::Base.establish_connection(db_info)
 # Comment out the next two lines if you're not using RSpec's matchers (should / should_not) in your steps.
 #require 'cucumber/rspec'
 
-require Root + '/spec/active_record/fixtures/fruit'
-require Root + '/spec/active_record/fixtures/tree'
-
 Blueprints.enable do |config|
-  config.root = Root + '/spec/active_record'
+  config.root = Root.join('spec')
   config.prebuild = :big_cherry
 end

data/lib/blueprints.rb

@@ -1,23 +1,33 @@
 require 'active_support'
-require 'active_support/core_ext'
+require 'active_support/core_ext/kernel/singleton_class'
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/class/attribute_accessors'
+require 'active_support/core_ext/hash/reverse_merge'
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/string/inflections'
+require 'active_support/core_ext/enumerable'
 require 'database_cleaner'
 require 'set'
 
 files = %w{
-configuration context buildable namespace root_namespace blueprint file_context helper errors dependency core_ext
+configuration context eval_context buildable namespace root_namespace blueprint helper errors dependency extensions database_cleaner_fix
 }
-files.each { |f| require File.join(File.dirname(__FILE__), 'blueprints', f) }
+files.each { |f| require "blueprints/#{f}" }
 
+# Main namespace of blueprints. Contains methods for Blueprints setup.
 module Blueprints
   # Contains current configuration of blueprints
+  # @return [Blueprints::Configuration] Current configuration.
   def self.config
     @@config ||= Blueprints::Configuration.new
   end
 
   # Setups variables from global context and starts transaction. Should be called before every test case.
+  # @param current_context Object to copy instance variables for prebuilt blueprints/namespaces.
   def self.setup(current_context)
     Namespace.root.setup
-    Namespace.root.copy_ivars(current_context)
+    Namespace.root.eval_context.copy_instance_variables(current_context)
     if_orm { DatabaseCleaner.start }
   end
 
@@ -28,6 +38,8 @@ module Blueprints
 
   # Enables blueprints support for RSpec or Test::Unit depending on whether (R)Spec is defined or not. Yields
   # Blueprints::Configuration object that you can use to configure blueprints.
+  # @yield [config] Used to configure blueprints.
+  # @yieldparam [Blueprints::Configuration] config Current blueprints configuration.
   def self.enable
     yield config if block_given?
     load
@@ -54,18 +66,39 @@ module Blueprints
     Namespace.root.prebuild(config.prebuild) if config.transactions
   end
 
+  # Returns backtrace cleaner that is used to extract lines from user application.
+  # @return [ActiveSupport::BacktraceCleaner] Backtrace cleaner
   def self.backtrace_cleaner
     @backtrace_cleaner ||= ActiveSupport::BacktraceCleaner.new.tap do |bc|
-      root_sub = /^#{config.root}[\\\/]/
-      blueprints_path = File.dirname(__FILE__).sub(root_sub, '')
+      root_sub        = /^#{config.root}[\\\/]/
+      blueprints_path = File.expand_path(File.dirname(__FILE__))
 
       bc.add_filter { |line| line.sub(root_sub, '') }
-
-      bc.add_silencer { |line| File.dirname(line).starts_with?(blueprints_path) }
-      bc.add_silencer { |line| Gem.path.any? { |path| File.dirname(line).starts_with?(path) } }
+      bc.add_silencer { |line| [blueprints_path, *Gem.path].any? { |path| File.expand_path(File.dirname(line)).starts_with?(path) } }
     end
   end
 
+  # Returns array of blueprints that have not been used until now.
+  # @return [Array<String>] List of unused blueprints.
+  def self.unused
+    each_blueprint.select { |blueprint| blueprint.uses.zero? }.collect(&:full_name)
+  end
+
+  # Returns array of most used blueprints.
+  # @param [Hash] options Options on what blueprints to return.
+  # @option options [Integer] :count Max amount of most used blueprints to return.
+  # @option options [Integer] :at_least Only blueprints that have at least specified number of uses will be returned.
+  # @return [Array<Array<String, Integer>>] List of most used blueprints together with their use counts.
+  def self.most_used(options = {})
+    blueprints = each_blueprint.collect { |blueprint| [blueprint.full_name, blueprint.uses] }.sort { |a, b| b[1] <=> a[1] }
+    blueprints = blueprints.take(options[:count]) if options[:count]
+    blueprints.reject! { |blueprint| blueprint[1] < options[:at_least] } if options[:at_least]
+    blueprints
+  end
+
+  # Warns a user (often about deprecated feature).
+  # @param [String] message Message to output.
+  # @param [Blueprints::Blueprint] blueprint Name of blueprint that this occurred in.
   def self.warn(message, blueprint)
     $stderr.puts("**WARNING** #{message}: '#{blueprint.name}'")
     $stderr.puts(backtrace_cleaner.clean(blueprint.backtrace(caller)).first)
@@ -73,12 +106,14 @@ module Blueprints
 
   protected
 
-  # Loads blueprints file and creates blueprints from data it contains. Is run by setup method
+  # Loads blueprints file and creates blueprints from data it contains. Is run by setup method.
+  # @param [Array<String>] patterns List of filesystem patterns to search blueprint files in.
+  # @raise [RuntimeError] If no blueprints file can be found.
   def self.load_scenarios_files(patterns)
     patterns.each do |pattern|
       pattern = config.root.join(pattern)
-      files = Dir[pattern.to_s]
-      files.each { |f| FileContext.new f }
+      files   = Dir[pattern.to_s]
+      files.each { |file| Context.eval_within_context(:file => file, :namespace => Namespace.root) }
       return if files.size > 0
     end
 
@@ -87,6 +122,27 @@ module Blueprints
 
   private
 
+  def self.each_blueprint(from = Namespace.root)
+    enumerator_class.new do |enum|
+      from.children.values.collect do |child|
+        if child.is_a?(Blueprints::Blueprint)
+          enum.yield child
+        else
+          each_blueprint(child).each { |blueprint| enum.yield blueprint }
+        end
+      end
+    end
+  end
+
+  def self.enumerator_class
+    @enumerator_class ||= if defined?(Enumerator)
+                            Enumerator
+                          else
+                            require 'generator'
+                            Generator
+                          end
+  end
+
   def self.if_orm
     yield
   rescue DatabaseCleaner::NoORMDetected, DatabaseCleaner::NoStrategySetError

data/lib/blueprints/blueprint.rb

@@ -1,48 +1,68 @@
 module Blueprints
   # Class for actual blueprints. Allows building itself by executing block passed against current context.
   class Blueprint < Buildable
-    attr_reader :file
-    # Initializes blueprint by name and block
-    def initialize(name, file, &block)
-      @file = file
-      super(name)
+    # Holds how many times this particular blueprint was built
+    attr_reader :uses
+
+    # Initializes blueprint by name, context and block. Also sets default demolish and update blocks.
+    # @param name (see Buildable#initialize)
+    # @param context (see Buildable#initialize)
+    def initialize(name, context, &block)
+      super(name, context)
 
       ivname = variable_name
       @block = block
-      @demolish_block = lambda { instance_variable_get(ivname).destroy }
-      @update_block = lambda { instance_variable_get(ivname).blueprint(options) }
+      @demolish_block = Proc.new { instance_variable_get(ivname).destroy }
+      @update_block = Proc.new { instance_variable_get(ivname).blueprint(options) }
+      @uses = 0
     end
 
-    # Builds blueprint and adds it to executed blueprint hash. Setups instance variable with same name as blueprint if it is not defined yet.
-    def build_self(build_once = true)
+    # Builds blueprint and adds it to executed blueprint array. Setups instance variable with same name as blueprint if it is not defined yet.
+    # Marks blueprint as used.
+    # @param eval_context (see Buildable#build)
+    # @param build_once (see Buildable#build)
+    # @param options (see Buildable#build)
+    def build_self(eval_context, build_once, options)
+      @uses += 1 unless built?
       surface_errors do
         if built? and build_once
-          Namespace.root.context.instance_eval(&@update_block) if RootNamespace.root.context.options.present?
+          eval_context.instance_eval(@context, options, &@update_block) if options.present?
         elsif @block
-          self.result = Namespace.root.context.instance_eval(&@block)
+          result(eval_context) { eval_context.instance_eval(@context, options, &@block) }
         end
       end
     end
 
     # Changes blueprint block to build another blueprint by passing additional options to it. Usually used to dry up
     # blueprints that are often built with some options.
+    # @example Extending blueprints
+    #   Post.blueprint :post, :title => 'hello blueprints'
+    #   blueprint(:published_post).extends(:post, :published_at => Time.now)
+    # @param [Symbol, String] parent Name of parent blueprint.
+    # @param [Hash] options Options to be passed when building parent.
     def extends(parent, options)
       attributes(options)
       @block = Proc.new { build parent => attributes }
     end
 
+    # Changes backtrace to include what blueprint was being built.
+    # @param [Array<String>] trace Current trace
+    # @return [Array<String>] Changed trace with included currently built blueprint name.
     def backtrace(trace)
-      trace.collect { |line| line.sub(/^\(eval\):(\d+).*/, "#{@file}:\\1:in blueprint '#{@name}'") }
+      trace.collect! { |line| line.sub(/^#{@context.file}:(\d+).*/, "#{@context.file}:\\1:in blueprint '#{@name}'") }
     end
 
-    # If block is passed then sets custom demolish block for this blueprint.
-    # If no block is passed then calls demolish block and marks blueprint as not built.
-    # Raises DemolishError if blueprints has not been built.
-    def demolish(&block)
+    # @overload demolish(&block)
+    #   Sets custom block for demolishing this blueprint.
+    # @overload demolish(eval_context)
+    #   Demolishes blueprint by calling demolish block.
+    #   @param [Blueprints::EvalContext] eval_context Context where blueprint was built in.
+    #   @raise [Blueprints::DemolishError] If blueprint has not been built yet.
+    def demolish(eval_context = nil, &block)
       if block
         @demolish_block = block
-      elsif built?
-        Namespace.root.context.instance_eval(&@demolish_block)
+      elsif eval_context and built?
+        eval_context.instance_eval(@context, {}, &@demolish_block)
         undo!
       else
         raise DemolishError, @name
@@ -59,7 +79,7 @@ module Blueprints
     def surface_errors
       yield
     rescue StandardError => error
-      error.set_backtrace(backtrace(error.backtrace))
+      backtrace(error.backtrace)
       raise error
     end
   end

data/lib/blueprints/buildable.rb

@@ -1,60 +1,72 @@
 module Blueprints
   class Buildable
+    delegate :namespace, :dependencies, :to => :@context
     attr_reader :name
-    attr_accessor :namespace
 
-    # Initializes new Buildable object by name.
-    # Name can be Symbol, String or Hash. If Hash is passed, then first key is assumed name, and value(s) of that key
-    # are assumed as dependencies. Raises error class of name parameter is not what is expected.
-    # Warns if name has already been taken.
-    def initialize(name)
+    # Initializes new Buildable object by name and context which it belongs to.
+    # @param [#to_sym, Hash] name Name of buildable. If hash is passed then first key is assumed name, and
+    #   value(s) of that key are assumed as dependencies.
+    # @param [Blueprints::Context] context Context of buildable that later might get updated.
+    # @raise [TypeError] If name is invalid.
+    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, parents = parse_name(name)
       depends_on(*parents)
 
-      Blueprints.warn("Overwriting existing blueprint", self) if Namespace.root and Namespace.root.children[@name]
-      Namespace.root.add_child(self) if Namespace.root
+      namespace.add_child(self) if namespace
     end
 
-    # Defines blueprint dependencies. Used internally, but can be used externally too.
-    def depends_on(*scenarios)
-      @parents = (@parents || []) + scenarios.map { |s| s.to_sym }
-      self
+    # Returns class, name, attributes and dependencies of buildable in nice formatted string.
+    # @return [String] Inspected properties of buildable.
+    def inspect
+      "<##{self.class} name: #{full_name.inspect}, attributes: #{attributes.inspect}, dependencies: #{dependencies.inspect}>"
+    end
+
+    # Defines dependencies of buildable by updating it's context.
+    # @param [Array<String, Symbol>] dependencies List of dependencies.
+    def depends_on(*dependencies)
+      update_context(:dependencies => dependencies)
+    end
+
+    # @overload attributes
+    #   Returns attributes of buildable
+    #   @return [Hash] Attributes of buildable
+    # @overload attributes(value)
+    #   Merges attributes of buildable with new attributes by updating context
+    #   @param [Hash] Updated attributes
+    def attributes(value = nil)
+      if value
+        update_context(:attributes => value)
+      else
+        @context.attributes
+      end
     end
 
     # Builds dependencies of blueprint and then blueprint itself.
-    #
-    # +build_once+ - pass false if you want to build blueprint again instead of updating old one.
-    #
-    # +options+ - list of options to be accessible in the body of a blueprint. Defaults to empty Hash.
-    def build(build_once = true, options = {})
-      return result if @building or (built? and build_once and options.blank?)
+    # @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?)
       @building = true
 
-      each_namespace {|namespace| namespace.build_parents }
-      build_parents
+      each_namespace { |namespace| namespace.build_parents(eval_context) }
+      build_parents(eval_context)
 
-      old_options, old_attributes = Namespace.root.context.options, Namespace.root.context.attributes
-      Namespace.root.context.options, Namespace.root.context.attributes = options, normalized_attributes.merge(options)
-      each_namespace {|namespace| Namespace.root.context.attributes.reverse_merge! namespace.normalized_attributes }
-
-      build_self(build_once)
-      Namespace.root.context.options, Namespace.root.context.attributes = old_options, old_attributes
+      result = build_self(eval_context, build_once, options)
       Namespace.root.executed_blueprints << self
+
       @building = false
       result
     end
 
-    # Returns the result of blueprint
-    def result
-      Namespace.root.context.instance_variable_get(variable_name)
-    end
-
-    # Sets the result of blueprint
-    def result=(value)
-      Namespace.root.add_variable(variable_name, value)
-    end
-
     # Returns if blueprint has been built
+    # @return [true, false] true if was built, false otherwise
     def built?
       Namespace.root.executed_blueprints.include?(self)
     end
@@ -64,40 +76,31 @@ module Blueprints
       Namespace.root.executed_blueprints.delete self
     end
 
-    # If value is passed then it sets attributes for this buildable object.
-    # Otherwise returns attributes (defaulting to empty Hash)
-    def attributes(value)
-      @attributes = value
-      self
-    end
-
-    # Returns normalized attributes for that particular blueprint.
-    def normalized_attributes
-      Buildable.normalize_attributes(@attributes ||= {})
+    # Returns full path to this buildable
+    # @param [String] join_with Separator used to join names of parent namespaces and buildable itself.
+    # @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
     end
 
-    # Normalizes attributes by changing all :@var to values of @var, and all dependencies to the result of that blueprint.
-    def self.normalize_attributes(attributes)
-      attributes = attributes.dup
-      attributes.each do |attr, value|
-        attributes[attr] = value.blueprint_value if value.respond_to?(:blueprint_value)
-        if value.is_a? Symbol and value.to_s =~ /^@.+$/
-          STDERR.puts "DEPRECATION WARNING: :@variables are deprecated in favor of `d` method"
-          attributes[attr] = Blueprints::Namespace.root.context.instance_variable_get(value)
-        end
-      end
-      attributes
+    # Returns full name for this buildable
+    # @return [String] full buildable name
+    def full_name
+      path('.')
     end
 
-    def build_parents
-      @parents.each do |p|
+    # 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.
+    # @raise [Blueprints::BlueprintNotFoundError] If one of dependencies can't be found.
+    def build_parents(eval_context)
+      @context.dependencies.each do |name|
         parent = begin
-          namespace[p]
+          namespace[name]
         rescue BlueprintNotFoundError
-          Namespace.root[p]
+          Namespace.root[name]
         end
 
-        parent.build
+        parent.build(eval_context)
       end
     end
 
@@ -108,23 +111,38 @@ module Blueprints
       yield(namespace) while namespace = namespace.namespace
     end
 
-    def path
-      @path = (namespace.path + "_" unless namespace.nil? or namespace.path.empty?).to_s + @name.to_s
-    end
-
     def variable_name
       :"@#{path}"
     end
 
     def parse_name(name)
-      case name
-        when Hash
-          return name.keys.first.to_sym, [name.values.first].flatten.map { |sc| parse_name(sc).first }
-        when Symbol, String
-          name = name.to_sym unless name == ''
-          return name, []
-        else
-          raise TypeError, "Pass blueprint names as strings or symbols only, cannot define blueprint #{name.inspect}"
+      if name.is_a?(Hash)
+        return name.keys.first.to_sym, [name.values.first].flatten.map { |sc| parse_name(sc).first }
+      elsif name.respond_to?(:to_sym)
+        name = name.to_sym unless name == ''
+        return name, []
+      else
+        raise TypeError, "Pass blueprint names as strings or symbols only, cannot define blueprint #{name.inspect}"
+      end
+    end
+
+    def update_context(options)
+      @context = @context.with_context(options)
+      self
+    end
+
+    private
+
+    def result(eval_context)
+      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)
+            @auto_variable = true
+          end
+        end
+      else
+        eval_context.instance_variable_get(variable_name)
       end
     end
   end