olfactory 0.2.0 → 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 2aa21e7c9e5db497a09aae366070f380c53fd06d
+  data.tar.gz: 8cc46a8a5c7651ee48a2ab9aa63c85670409f2e7
+SHA512:
+  metadata.gz: 86b174607b353e2daf29dfbee9f19d7594b95433c629f925e4feecb58b50e205f2f58a43014d2dc107c987530518154c8612930e9b8cba3859a81a6dd57a66ef
+  data.tar.gz: ae15150ca718660d8de6b7a8252ef61e8e7e633337eb28b44fcd57df76864915e8f882d7831f12ef3d582d568ac5a2fa5c09dc4b3eef9c624c447677f4cd9a55

data/README.md

@@ -8,7 +8,7 @@ Olfactory
 
 Olfactory is a factory extension for creating complex object sets, as a supplement to `factory_girl`, `fabrication`, or other factories.
 
-It introduces the concept of **templates**: an abstract group of objects. You define what objects (or other templates) your template can contain (not unlike a factory), then you can create instances of it by invoking the build or create functions. These templates can be used to make test setup much quicker and easier. Templates are not intended to replace factories, but bridge the gap where `factory_girl` and `fabrication` factories fall short.
+It introduces the concept of **templates**: a group of named values/objects (as a `Hash`.) You define what objects (or other templates) your template can contain (similar to a factory), then you can create instances of that template using the `#build` or `#create` functions. These templates can be used to make test setup much quicker and easier. Templates are not intended to replace factories, but bridge the gap where `factory_girl` and `fabrication` factories fall short.
 
 They are most useful when:
  - Your models are weakly related or non-relational (e.g. not joined by ActiveRecord associations)
@@ -54,8 +54,14 @@ context "networkable people" do
 end
 ```
 
+In this sample, the `let(:user_group)` block returns a `Hash` object, that contains structured, pre-fabricated data of our choosing that we can use for our `it` example.
+
 ### Usage
 
+##### What is a template?
+
+Templates are effectively `Hash` schemas. By defining a template, you are specifying which named-values can appear in a `Hash` instance of that template. When defining a template, you can also define custom presets, sequences, and other named options. You can leverage these features to simplify how you create complex objects & test data.
+
 ##### Defining templates
 
 Templates are defined in `spec/templates/**/*.rb` files. Define a template using the `Olfactory#template` method.
@@ -67,7 +73,17 @@ Templates are defined in `spec/templates/**/*.rb` files. Define a template using
 Once defined, these templates can be instantiated using `build` and `create`, which are analogous to the same `factory_girl`/`fabrication` methods
 
     Olfactory.build :computer # Creates objects, but does not implictly save them
-    Olfactory.create :computer # Creates objects, and attempts to save all items that respond to #save!
+    Olfactory.create :computer # Creates objects, and attempts to save all items in the Hash that respond to #save!
+
+Invoking these two methods will return a `Hash` matching the template schema, populated with either custom or preset values.
+
+##### Defining template relationships using `has` & `embeds`
+
+Every template is composed of two kinds of named values: *fields* or other *templates*.
+
+Fields hold actual values: integers, strings, objects, etc. The `has` relation is used define a field. `#has_one` holds one object, and '#has_many' holds a collection of objects (`Array` or `Hash`.)
+
+You can also embed a template within another template. This is useful if you have a template composed of other smaller sub-templates (e.g. a Computer template composed of Processor and Memory templates.) Use the `embeds` relation to nest a template. `#embeds_one` will embed a single instance of a template. `#embeds_many` will embed a collection of template instances (in the form of an `Array` or `Hash`.)
 
 ##### #has_one
 
@@ -513,12 +529,14 @@ Sample:
 
 ##### #transient
  
-Similar to `factory_girl`'s transients, `transient` defines a temporary variable. You can store values in here to compose conditional logic or more sophisticated templates. When a template contains an embedded template, it will pass down all of its transients to the embedded template. Invoking `transients` on an instance of a template will return a hash of its transient variables.
+Similar to `factory_girl`'s transients, `transient` defines a temporary variable. You can store values in here to compose conditional logic or more sophisticated templates. When a template contains an embedded template, it will pass down all of its transients to the embedded template. Invoking `transients` on an instance of a template will return a `Hash` of its transient variables.
 
 Usage:
-> **transient** name, Object
+> **transient** name, Object # Sets value
+> 
+> **transient** name { Object } # Sets value (lazily)
 > 
-> **transients**[name]
+> **transients**[name] # Gets value
 
 Sample:
 
@@ -557,10 +575,15 @@ Sample:
 Defines default values, which are used to fill in any empty `has`, `embeds` or `transient` fields, before and after respectively. They will *not* overwrite any non-nil value.
 
 Definition:
-> **before** { |instance| &block }
+> **before**(*:context, :run => Symbol*) { |instance| &block }
 > 
 > **after** { |instance| &block }
 
+- `:context` defines when this before should run. Specifying `:embedded` means it runs just before embedded objects are added to the instance. Default (by providing no value) is to run immediately as instance is created.
+- `:run` defines how many times this before can be invoked for an instance. Specifying `:once` means it can only be invoked once (singleton-style.) Default is to always execute. Can only be specified if `:context` is also specified.
+
+The latter two options can be useful if you are embedding a template that reads the parent's fields or transients.
+
 Sample:
 
     # Template defintion
@@ -597,6 +620,85 @@ Sample:
     end
     # Result 
     {
-      :cpu => "ARM",
-      :memory_size => "1GB"
+      :memory_size => "1GB",
+      :cpu => "ARM"
+    }
+
+Another `before` sample using `:context` and `:run` options:
+
+    # Template defintions
+    Olfactory.template :widget do |t|
+      t.embeds_many :doodads, :singular => :doodad
+      t.has_one :thingamabob
+      t.macro :quality do |m, type|
+        m.transient :attribute, type.to_s
+      end
+      t.before(:embedded) do |d|
+        d.quality :dull
+        d.thingamabob "thingamabob" if d[:doodads] && d[:doodads].count > 0
+      end
+    end
+    Olfactory.template :doodad do |t|
+      t.has_one :gizmo
+      t.after do |d|
+        d.gizmo "#{d.transients[:attribute]} doodad"
+      end
+    end
+    # Build instance of template
+    Olfactory.build :widget do |w|
+      w.doodad
+      w.quality :shiny
+      w.doodad
+    end
+    # Result
+    {
+      :doodads => [{ :gizmo => "dull doodad" },
+                   { :gizmo => "shiny doodad" }]
+      # NOTE: A 'thingamabob' wasn't added. This is because the #before only ran once.
     }
+
+##### #instantiate
+
+Defines an 'instantiator': a function you can call to build custom objects from an instance of a template. The block can accept arguments or use the template instance as input, and should return an object or collection. Invoke the block using the `#build` or `#create` method to get the return value from the instantiator. When `#create` is used, any object that responds to `#save!` will be saved.
+
+Definition:
+> **instantiate** :name { |instance, *args..| &block }
+
+When using:
+> **build**(name*[, arg1, arg2...]*)
+> 
+> **create**(name*[, arg1, arg2...]*)
+
+Sample:
+
+    # Template defintion
+    Olfactory.template :widget do |t|
+      t.has_one :doodad
+      t.instantiate :doodad do |i, j|
+        String.new("#{i[:doodad]}-instance-#{j}")
+      end
+    end
+    # Build instance of template
+    instance = Olfactory.build :widget do |w| w.doodad "doodad" end
+    instance.build(:doodad, 1)
+    # Result
+    "doodad-instance-1"
+
+### Changelog
+
+#### Version 0.2.1
+
+ - Added: `context` and `run` options to `before` blocks.
+ - Added: `dimension` option to sequences, to allow scoping.
+ - Fixed: Default values not being overridden in special cases.
+ - Fixed: Defaults adding to item and subtemplate collections.
+
+#### Version 0.2.0
+
+ - Added: Sequences (like factory_girl's)
+ - Added: Dictionaries (generic hash storage)
+ - Changed: `#build_template` and `#create_template` have been renamed to `#build` and `#create` respectively.
+
+#### Version 0.1.0
+
+ - Initial version of Olfactory (templates, transients, macros, presets, has/embeds relations)

data/lib/olfactory.rb

@@ -35,16 +35,16 @@ module Olfactory
 
   # Invocations
   def self.build(name, options = {}, &block)
-    self.templates[name].build(block, options)
+    self.templates[name].construct(block, options)
   end
   def self.create(name, options = {}, &block)
-    template = self.templates[name].build(block, options)
+    template = self.templates[name].construct(block, options)
     template.save!
     template
   end
   def self.generate(name, options = {}, &block)
     if sequence = self.sequences[name]
-      sequence.generate(name, options, block)
+      sequence.generate(options, block)
     else
       raise "Unknown sequence '#{name}'!"
     end
@@ -67,8 +67,9 @@ module Olfactory
       self.sequences[name].reset
     end
   end
-  def self.reset_template_sequences(template, *names)
-    if template = self.templates[template]
+  def self.reset_template_sequences(template = nil, *names)
+    templates = template.nil? ? self.templates.values : [self.templates[template]].compact
+    templates.each do |template|
       template.reset_sequences(*names)
     end
   end
@@ -78,8 +79,9 @@ module Olfactory
       self.dictionaries[name].reset
     end
   end
-  def self.reset_template_dictionaries(template, *names)
-    if template = self.templates[template]
+  def self.reset_template_dictionaries(template = nil, *names)
+    templates = template.nil? ? self.templates.values : [self.templates[template]].compact
+    templates.each do |template|
       template.reset_dictionaries(*names)
     end
   end

data/lib/olfactory/sequence.rb

@@ -6,19 +6,20 @@ module Olfactory
       self[:evaluator] = block
       self[:scope] = (options[:scope] || :global)
       self[:seed] = (options[:seed] || 0)
-      self[:current_seed] = (options[:seed] || 0)
+      self[:dimensions] = { nil => { :current_seed => (options[:seed] || 0) } }
     end
 
-    def generate(name, options, block)
-      seed = options[:seed] || self[:current_seed]
+    def generate(options = {}, block)
+      seed = options[:seed] || (self[:dimensions][options[:dimension]] ||= { :current_seed => self[:seed] })[:current_seed]
       target = block || self[:evaluator]
-      value = target.call(seed, options.reject { |k,v| k == :seed })
-      self[:current_seed] += 1 if !options.has_key?(:seed)
+      value = target.call(seed, options.reject { |k,v| [:seed, :dimension].include?(k) })
+      self[:dimensions][options[:dimension]][:current_seed] += 1 if !options.has_key?(:seed)
 
       value
     end
     def reset
-      self[:current_seed] = self[:seed]
+      self[:dimensions].values.each { |v| v[:current_seed] = self[:seed] }
+      self
     end
   end
 end

data/lib/olfactory/template.rb

@@ -1,16 +1,26 @@
 # -*- encoding : utf-8 -*-
 module Olfactory
   class Template < Hash
-    attr_accessor :definition, :transients, :sequences, :dictionaries, :default_mode
+    attr_accessor :definition,
+                  :transients,
+                  :sequences,
+                  :dictionaries,
+                  :default_mode,
+                  :default_populated,
+                  :default_populated_transients,
+                  :block_invocations
 
     def initialize(definition, options = {})
       self.definition = definition
       self.transients = options[:transients] ? options[:transients].clone : {}
       self.sequences = options[:sequences] ? options[:sequences].clone : {}
       self.dictionaries = options[:dictionaries] ? options[:dictionaries].clone : {}
+      self.default_populated = {}
+      self.default_populated_transients = {}
+      self.block_invocations = []
     end
 
-    def build(block, options = {})
+    def construct(block, options = {})
       self.add_defaults(:before) if options[:defaults].nil? || options[:defaults]
       if block # Block can be nil (when we want only defaults)
         if options[:value]
@@ -20,10 +30,8 @@ module Olfactory
         end
       end
       self.add_defaults(:after) if options[:defaults].nil? || options[:defaults]
-
       self
     end
-
     def save!
       # Items, then subtemplates
       [self.definition.t_items, self.definition.t_subtemplates].each do |field_group_definitions|
@@ -49,8 +57,8 @@ module Olfactory
         super # Unknown method
       end
     end
-    def can_set_field?(meth)
-      !(self.default_mode && self.has_key?(meth))
+    def can_set_field?(name)
+      !(self.default_mode && self.has_key?(name)) || (self.default_mode && (self.default_populated[name] == true))
     end
     def extract_variable_name(args)
       variable_name = args.first
@@ -59,13 +67,20 @@ module Olfactory
     end
     def populate_field(field_definition, meth, args, block)
       if field_definition[:type] == :macro
-        field_value = build_macro(field_definition, args, block)
+        field_value = construct_macro(field_definition, args, block)
         do_not_set_value = true
-      elsif field_definition[:type] == :subtemplate && can_set_field?(meth)
+      elsif field_definition[:type] == :subtemplate && can_set_field?(field_definition[:name])
         subtemplate_name = field_definition.has_key?(:template) ? field_definition[:template] : field_definition[:name]
         subtemplate_definition = Olfactory.templates[subtemplate_name]
         subtemplate_definition ||= Olfactory.templates[field_definition[:singular]]
         if subtemplate_definition
+          # Invoke before clauses
+          self.add_defaults(:before_embedded)
+          # self.default_mode = true
+          # before_block = field_definition[:evaluator]
+          # before_block.call(self) if before_block
+          # self.default_mode = false
+
           if field_definition[:collection] && field_definition[:collection] <= Array
             # Embeds many
             if meth == field_definition[:singular]
@@ -73,14 +88,14 @@ module Olfactory
               grammar = :singular
               preset_name = args.first
 
-              field_value = build_one_subtemplate(subtemplate_definition, preset_name, block)
+              field_value = construct_one_subtemplate(subtemplate_definition, preset_name, block)
             else
               # Plural
               grammar = :plural
               quantity = args.detect { |value| value.class <= Integer }
               preset_name = args.detect { |value| value != quantity }
 
-              field_value = build_many_subtemplates(subtemplate_definition, quantity, preset_name, block)
+              field_value = construct_many_subtemplates(subtemplate_definition, quantity, preset_name, block)
               do_not_set_value if field_value.nil?
             end
           elsif field_definition[:collection] && field_definition[:collection] <= Hash
@@ -92,7 +107,7 @@ module Olfactory
               args = args[1..(args.size-1)]
               preset_name = args.first
               
-              field_value = build_one_subtemplate(subtemplate_definition, preset_name, block)
+              field_value = construct_one_subtemplate(subtemplate_definition, preset_name, block)
               do_not_set_value if field_value.nil? # || field_value.empty?
             else
               # Plural
@@ -104,13 +119,16 @@ module Olfactory
             # Embeds one
             preset_name = args.first
 
-            field_value = build_one_subtemplate(subtemplate_definition, preset_name, block)
+            field_value = construct_one_subtemplate(subtemplate_definition, preset_name, block)
             do_not_set_value if field_value.nil?
           end
+
+          # Invoke after clauses
+          self.add_defaults(:after_embedded)
         else
           raise "Could not find a template matching '#{subtemplate_name}'!"
         end
-      elsif field_definition[:type] == :item && can_set_field?(meth)
+      elsif field_definition[:type] == :item && can_set_field?(field_definition[:name])
         if field_definition[:collection] && field_definition[:collection] <= Array
           # Has many
           if meth == field_definition[:singular]
@@ -118,7 +136,7 @@ module Olfactory
             grammar = :singular
             obj = args.count == 1 ? args.first : args
             
-            field_value = build_one_item(field_definition, obj, block)
+            field_value = construct_one_item(field_definition, obj, block)
             do_not_set_value = true if field_value.nil?
           else
             # Plural
@@ -126,7 +144,7 @@ module Olfactory
             quantity = args.first if block && args.first.class <= Integer
             arr = args.first if args.count == 1 && args.first.class <= Array
 
-            field_value = build_many_items(field_definition, quantity, arr, args, block)
+            field_value = construct_many_items(field_definition, quantity, arr, args, block)
             do_not_set_value = true if field_value.empty?
           end
         elsif field_definition[:collection] && field_definition[:collection] <= Hash
@@ -138,7 +156,7 @@ module Olfactory
             args = args[1..(args.size-1)]
             obj = args.first
 
-            field_value = build_one_item(field_definition, obj, block)
+            field_value = construct_one_item(field_definition, obj, block)
             do_not_set_value = true if field_value.nil?
           else
             # Plural
@@ -155,7 +173,7 @@ module Olfactory
           # Has one
           obj = args.first
             
-          field_value = build_one_item(field_definition, obj, block)
+          field_value = construct_one_item(field_definition, obj, block)
         end
       elsif field_definition.class == Olfactory::Dictionary
         if field_definition.scope == :template
@@ -188,79 +206,116 @@ module Olfactory
         else
           return_value = self[field_definition[:name]] = field_value
         end
+        if self.default_mode && (self.default_populated[field_definition[:name]] != false)
+          self.default_populated[field_definition[:name]] = true
+        else
+          self.default_populated[field_definition[:name]] = false
+        end
       end
       return_value
     end
-    def transient(name, value)
-      self.transients[name] = value if !(self.default_mode && self.transients.has_key?(name))
+    def transient(name, value = nil, &block)
+      if !(self.default_mode && self.transients.has_key?(name)) || (self.default_mode && (self.default_populated_transients[name] == true))
+        self.transients[name] = (block ? block.call : value)
+        if self.default_mode && (self.default_populated_transients[name] != false)
+          self.default_populated_transients[name] = true
+        else
+          self.default_populated_transients[name] = false
+        end
+      end
     end
     def generate(name, options = {}, &block)
       sequence = self.definition.t_sequences[name]
       # Template scope
       if sequence && sequence[:scope] == :template
-        value = sequence.generate(name, options, block)
+        value = sequence.generate(options, block)
       # Instance scope
       elsif sequence && sequence[:scope] == :instance
-        self.sequences[name] ||= { :current_seed => (options[:seed] || sequence[:seed]) }
-        value = sequence.generate(name, options.merge(:seed =>  self.sequences[name][:current_seed]), block)
-        self.sequences[name][:current_seed] += 1 if !options.has_key?(:seed)
+        self.sequences[name] ||= sequence.dup.reset
+        value = self.sequences[name].generate(options, block)
+        # self.sequences[name][:current_seed] += 1 if !options.has_key?(:seed)
       else
         raise "Unknown sequence '#{name}'!"
       end
       value
     end
+    def build(name, *args)
+      if instantiator_definition = self.definition.t_instantiators[name]
+        instantiator_definition[:evaluator].call(self, *args)
+      end
+    end
+    def create(name, *args)
+      obj = self.build(name, *args)
+      if obj.class <= Array
+        obj.each { |o| o.save! if o.respond_to?(:save!) }
+      elsif obj.class <= Hash
+        obj.values.each { |o| o.save! if o.respond_to?(:save!) }
+      elsif obj.respond_to?(:save!)
+        obj.save!
+      end
+      obj
+    end
     def add_defaults(mode)
       # Prevents overwrites of custom values by defaults
       self.default_mode = true # Hackish for sure, but its efficient...
 
       case mode
       when :before
-        default_definition = definition.t_before
+        default_definitions = definition.t_befores[:all]
       when :after
-        default_definition = definition.t_after
+        default_definitions = definition.t_afters[:all]
+      when :before_embedded
+        default_definitions = definition.t_befores[:embedded]
+      when :after_embedded
+        default_definitions = definition.t_afters[:embedded]
       end
-          
-      if default_definition[:evaluator]
-        default_definition[:evaluator].call(self)
-      elsif default_definition[:preset]
-        preset_definition = definition.find_preset_definition(default_definition[:preset])
-        preset_definition[:evaluator].call(self)
+      default_definitions ||= []
+      default_definitions.reject! { |dfn| dfn[:run] == :once && self.block_invocations.include?(dfn.object_id) }
+      
+      default_definitions.each do |default_definition|
+        if default_definition[:evaluator]
+          default_definition[:evaluator].call(self)
+        elsif default_definition[:preset]
+          preset_definition = definition.find_preset_definition(default_definition[:preset])
+          preset_definition[:evaluator].call(self)
+        end
+        self.block_invocations << default_definition.object_id if default_definition[:run] # Mark block as invoked
       end
 
       self.default_mode = false
     end
-    def build_macro(macro_definition, args, block)
+    def construct_macro(macro_definition, args, block)
       if macro_definition[:evaluator]
         macro_definition[:evaluator].call(self, *args)
       end
     end
-    def build_one_subtemplate(subtemplate_definition, preset_name, block)
+    def construct_one_subtemplate(subtemplate_definition, preset_name, block)
       # Block
       if block
-        subtemplate_definition.build(block, :transients => self.transients)
+        subtemplate_definition.construct(block, :transients => self.transients)
       # Preset Name
       elsif preset_name
-        subtemplate_definition.build_preset(preset_name, 1, :transients => self.transients)
+        subtemplate_definition.construct_preset(preset_name, 1, :transients => self.transients)
       # Default (nothing)
       else
-        subtemplate_definition.build(nil, :transients => self.transients)
+        subtemplate_definition.construct(nil, :transients => self.transients)
       end
     end
-    def build_many_subtemplates(subtemplate_definition, quantity, preset_name, block)
+    def construct_many_subtemplates(subtemplate_definition, quantity, preset_name, block)
       # Integer, Block
       if quantity && block
-        Array.new(quantity) { subtemplate_definition.build(block, :transients => self.transients) }
+        Array.new(quantity) { subtemplate_definition.construct(block, :transients => self.transients) }
       # Integer, Preset Name
       elsif quantity && preset_name
-        subtemplate_definition.build_preset(preset_name, quantity, :transients => self.transients)
+        subtemplate_definition.construct_preset(preset_name, quantity, :transients => self.transients)
       # Integer
       elsif quantity
-        Array.new(quantity) { subtemplate_definition.build(nil, :transients => self.transients) }
+        Array.new(quantity) { subtemplate_definition.construct(nil, :transients => self.transients) }
       else
         nil
       end
     end
-    def build_one_item(item_definition, obj, block)
+    def construct_one_item(item_definition, obj, block)
       if block
         block.call
       elsif obj
@@ -269,7 +324,7 @@ module Olfactory
         nil
       end
     end
-    def build_many_items(item_definition, quantity, arr, args, block)
+    def construct_many_items(item_definition, quantity, arr, args, block)
       # Integer, Block
       if quantity && block
         Array.new(quantity) { block.call }