olfactory 0.1.0 → 0.2.0

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.0
+  - ruby-head

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 StreetEasy
+Copyright (c) 2014 David Elner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,6 +1,9 @@
 Olfactory
 ==========
 
+[![Build Status](https://travis-ci.org/delner/olfactory.svg?branch=master)](https://travis-ci.org/delner/olfactory) ![Gem Version](https://badge.fury.io/rb/olfactory.svg)
+###### *For Ruby 1.9.3, 2.0.0, 2.1.0*
+
 ### Introduction
 
 Olfactory is a factory extension for creating complex object sets, as a supplement to `factory_girl`, `fabrication`, or other factories.
@@ -40,7 +43,7 @@ Instead, we can use templates to define shorthand notation:
 ```ruby
 context "networkable people" do
   let(:user_group) do
-    Olfactory.create_template :user_group do |group|
+    Olfactory.create :user_group do |group|
       group.user :desktop_user { |user| user.phone { |phone| phone.apps :facebook, :twitter } }
       group.user :tablet_user { |user| user.tablet { |tablet| tablet.app :facebook } }
       group.user :phone_user { |user| user.desktop { |desktop| desktop.app :twitter } }
@@ -61,10 +64,10 @@ Templates are defined in `spec/templates/**/*.rb` files. Define a template using
       ...
     end
 
-Once defined, these templates can be instantiated using `build_template` and `create_template`, which are analogous to the same `factory_girl`/`fabrication` methods
+Once defined, these templates can be instantiated using `build` and `create`, which are analogous to the same `factory_girl`/`fabrication` methods
 
-    Olfactory.build_template :computer # Creates objects, but does not implictly save them
-    Olfactory.create_template :computer # Creates objects, and attempts to save all items that respond to #save!
+    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!
 
 ##### #has_one
 
@@ -87,7 +90,7 @@ Sample:
       t.has_one :cpu, :alias => :processor
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       c.keyboard "X4 Sidewinder"
       c.mouse { FactoryGirl::build(:mouse) }
       c.processor "Intel Xeon"
@@ -152,7 +155,7 @@ Sample:
       t.has_many :drives, :singular => :drive, :named => true
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       # Generic
       c.cpus "Intel i7", "Onboard graphics"
       c.memory_stick "2GB"
@@ -206,7 +209,7 @@ Sample:
       end
     end
     # Build instance of template
-    Olfactory.build_template :computer do |computer|
+    Olfactory.build :computer do |computer|
       computer.cpu do |cpu|
         cpu.cores "Intel Core", "Intel Core"
       end
@@ -294,7 +297,7 @@ Sample:
       end
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       # Generic
       computer.cpu :amd
       computer.cpu do |cpu|
@@ -315,6 +318,133 @@ Sample:
       end
     end
 
+##### #sequence
+
+Defines a sequence, similar to `factory_girl`'s sequences. Can be combined with `Faker` to provide auto-generated test data. They can be defined at the global level, or nested within a template.
+
+###### When defining at the global level
+
+Definition:
+> **Olfactory.sequence** :name*[, :seed => Integer]* { |iterator[,options]| &block }
+
+- `seed` defines the starting value, which increments by 1 after each invocation. Default 0.
+- `options` in the form of hash args can be passed to the block.
+- `iterator` is the current seed, which starts at 0 by default.
+- `block` generates and returns the value.
+
+Usage:
+> **Olfactory.generate** :name
+> 
+> **Olfactory.generate** :name, :option1 => Object, :option2 => Object...
+> 
+> **Olfactory.generate** :name, :seed => Integer
+> 
+> **Olfactory.generate** :name, :seed => Integer, :option1 => Object, :option2 => Object...
+> 
+> **Olfactory.generate** :name { |iterator, options| &block }
+
+ - `seed` can be provided to override whatever the current seed is. When you provide an overriding seed, the sequence will *not* increment its internal seed. (Will act like it was never called.)
+ - `options` in the form of hash args can be passed to the block.
+ - `block` can be provided to override the block used for the call. When you provide an overriding block, the sequence will still increment its internal seed.
+
+Sample:
+
+    Olfactory.sequence :ip_address, :seed => 1 do |n, options|
+      options[:ipv6] ? "fe80::2a18:78ff:feba:#{n}" : "192.168.1.#{n % 255}"
+    end
+    Olfactory.generate(:ip_address) # => "192.168.1.1"
+    Olfactory.generate(:ip_address, :seed => 255) # => "192.168.1.255"
+    Olfactory.generate(:ip_address) # => "192.168.1.2"
+    Olfactory.generate(:ip_address, :ipv6 => true) # => "fe80::2a18:78ff:feba:3"
+    Olfactory.generate(:ip_address) do |n|
+      "172.168.1.#{n % 255}"
+    end # => "172.168.1.4"
+    
+###### When defining at the template level
+
+`Olfactory` sequences don't provide much benefit over other gems at the global level, but they really shine when used within templates. Sequences work exactly the same within templates, except they can be bound by `scope`, allowing the author a great deal of control over when sequences reset.
+
+`scope` can either be `:instance`, which resets the seed for each instance of the template, or `:template`, which shares the seed across all instances of the template.
+
+Sample:
+
+    # Template definition
+    Olfactory.template :computer do |t|
+      t.has_one :serial_number
+      t.sequence :serial_number, :scope => :template do |n|
+        (10000 + n)
+      end
+      t.has_many :registers, :singular => :register
+      t.sequence :register, :scope => :instance do |n|
+        "Register #{n+1}"
+      end
+    end
+    
+    Olfactory.build :computer do |c|
+      c.serial_number { c.generate(:serial_number) }
+      c.registers 2 { c.generate(:register) }
+    end
+    # => { :serial_number => 10000, :registers => ["Register 1", "Register 2"] }
+    
+    Olfactory.build :computer do |c|
+      c.serial_number { c.generate(:serial_number) }
+      c.registers 2 { c.generate(:register) }
+    end
+    # => { :serial_number => 10001, :registers => ["Register 1", "Register 2"] }
+
+##### #dictionary
+
+Defines a dictionary, which is just a simple data store (Hash.) They can be defined at the global level, or nested within a template.
+
+###### When defining at the global level
+
+Definition:
+> **Olfactory.dictionary** :name
+
+Usage:
+> **Olfactory.dictionaries**[name] # Returns Hash to read/write from
+
+Sample:
+
+    Olfactory.dictionary :manfacturer_codes
+    Olfactory.dictionaries[:manfacturer_codes]["DELL"] = "Dell Computing"
+
+###### When defining at the template level
+
+A hash data-store isn't that special at the global level, but is much more useful within templates. Definition is the same, but the usage only differs by name. Like sequences, dictionaries can define `scope` to separate or share data across templates. Combining them with sequences, we can synchronize data in some really cool ways.
+
+`scope` can either be `:instance`, which resets the hash for each instance of the template, or `:template`, which shares the hash across all instances of the template.
+
+Sample:
+
+    Olfactory.template :computer do |t|
+      t.has_one :hdd_manfacturer_code
+      t.has_one :gpu_manfacturer_code
+      t.has_one :cpu_manfacturer_code
+      t.dictionary :manfacturer_codes, :scope => :template
+      t.sequence :manfacturer_code, :scope => :template do |n|
+        (10000 + n)
+      end
+    end
+    
+    Olfactory.build :computer do |c|
+      c.hdd_manfacturer_code { c.manfacturer_codes["SAMSUNG"] ||= c.generate(:manfacturer_code) }
+      c.cpu_manfacturer_code { c.manfacturer_codes["AMD"] ||= c.generate(:manfacturer_code) }
+      c.gpu_manfacturer_code { c.manfacturer_codes["AMD"] ||= c.generate(:manfacturer_code) }
+    end
+    # => { :hdd_manfacturer_code => 10001,
+    #      :cpu_manfacturer_code => 10002,
+    #      :cpu_manfacturer_code => 10002 }
+    
+    Olfactory.build :computer do |c|
+      c.hdd_manfacturer_code { c.manfacturer_codes["SEAGATE"] ||= c.generate(:manfacturer_code) }
+      c.cpu_manfacturer_code { c.manfacturer_codes["AMD"] ||= c.generate(:manfacturer_code) }
+      c.gpu_manfacturer_code { c.manfacturer_codes["INTEL"] ||= c.generate(:manfacturer_code) }
+    end
+    # => { :hdd_manfacturer_code => 10003,
+    #      :cpu_manfacturer_code => 10002,
+    #      :cpu_manfacturer_code => 10004 }
+    
 ##### #preset
 
 Defines a preset of values.
@@ -323,7 +453,7 @@ Definition:
 > **preset** :name { |instance| &block }
 
 When using:
-> Olfactory.build_template template_name, :preset => preset_name, :quantity => quantity:Integer
+> Olfactory.build template_name, :preset => preset_name, :quantity => quantity:Integer
 
 See above sections for usage within templates.
 
@@ -342,7 +472,7 @@ Sample:
       t.has_one :cpu_core
     end
     # Build instance of template
-    Olfactory.build_template :computer, :preset => :dual_core
+    Olfactory.build :computer, :preset => :dual_core
     # Result
     {
       :cpus => [{
@@ -373,7 +503,7 @@ Sample:
       end
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       c.memory_sticks 2
     end
     # Result 
@@ -407,7 +537,7 @@ Sample:
       t.has_one :available_memory
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       c.memory_stick_size 2
       c.memory_sticks 2
       c.cpu do |cpu|
@@ -443,7 +573,7 @@ Sample:
       end
     end
     # Build instance of template
-    Olfactory.build_template :computer do |c|
+    Olfactory.build :computer do |c|
       c.cpu "AMD Athlon"
     end
     # Result 
@@ -462,7 +592,7 @@ Sample:
       end
     end
     # Build instance of template
-    Olfactory.build_template :phone do |c|
+    Olfactory.build :phone do |c|
       c.memory_size "1GB"
     end
     # Result 

data/Rakefile

@@ -0,0 +1,30 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new
+task :default => :spec
+task :test => :spec
+
+namespace :doc do
+  begin
+    require 'yard'
+  rescue LoadError
+    # ignore
+  else
+    YARD::Rake::YardocTask.new do |task|
+      task.files   = ['lib/**/*.rb']
+      task.options = [
+        '--protected',
+        '--output-dir', 'doc/yard',
+        '--tag', 'format:Supported formats',
+        '--markup', 'markdown',
+      ]
+    end
+  end
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -I lib -r olfactory.rb"
+end

data/lib/olfactory/dictionary.rb

@@ -0,0 +1,13 @@
+module Olfactory
+  class Dictionary < Hash
+    attr_accessor :name, :scope
+
+    def initialize(name, options = {})
+      self.name = name
+      self.scope = (options[:scope] || :global)
+    end
+    def reset
+      self.clear
+    end
+  end
+end

data/lib/olfactory/sequence.rb

@@ -0,0 +1,24 @@
+# -*- encoding : utf-8 -*-
+module Olfactory
+  class Sequence < Hash
+    def initialize(name, options, block)
+      self[:name] = name
+      self[:evaluator] = block
+      self[:scope] = (options[:scope] || :global)
+      self[:seed] = (options[:seed] || 0)
+      self[:current_seed] = (options[:seed] || 0)
+    end
+
+    def generate(name, options, block)
+      seed = options[:seed] || self[: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
+    end
+    def reset
+      self[:current_seed] = self[:seed]
+    end
+  end
+end

data/lib/olfactory/template.rb

@@ -1,11 +1,13 @@
 # -*- encoding : utf-8 -*-
 module Olfactory
   class Template < Hash
-    attr_accessor :definition, :transients, :default_mode
+    attr_accessor :definition, :transients, :sequences, :dictionaries, :default_mode
 
     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 : {}
     end
 
     def build(block, options = {})
@@ -155,6 +157,13 @@ module Olfactory
             
           field_value = build_one_item(field_definition, obj, block)
         end
+      elsif field_definition.class == Olfactory::Dictionary
+        if field_definition.scope == :template
+          return_value = field_definition
+        elsif field_definition.scope == :instance
+          return_value = (self.dictionaries[meth] ||= {})
+        end
+        do_not_set_value = true
       else
         do_not_set_value = true
       end
@@ -185,6 +194,21 @@ module Olfactory
     def transient(name, value)
       self.transients[name] = value if !(self.default_mode && self.transients.has_key?(name))
     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)
+      # 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)
+      else
+        raise "Unknown sequence '#{name}'!"
+      end
+      value
+    end
     def add_defaults(mode)
       # Prevents overwrites of custom values by defaults
       self.default_mode = true # Hackish for sure, but its efficient...
@@ -257,5 +281,13 @@ module Olfactory
         args
       end
     end
+    def reset_sequences(*names)
+      names = self.sequences.keys if names.empty?
+      names.each { |name| self.sequences[name].reset }
+    end
+    def reset_dictionaries(*names)
+      names = self.dictionaries.keys if names.empty?
+      names.each { |name| self.dictionaries[name].reset }
+    end
   end
 end

data/lib/olfactory/template_definition.rb

@@ -1,11 +1,13 @@
 # -*- encoding : utf-8 -*-
 module Olfactory
   class TemplateDefinition
-    attr_accessor :t_items, :t_subtemplates, :t_macros, :t_presets, :t_before, :t_after
+    attr_accessor :t_items, :t_subtemplates, :t_sequences, :t_dictionaries, :t_macros, :t_presets, :t_before, :t_after
 
     def initialize
       self.t_items = {}
       self.t_subtemplates = {}
+      self.t_sequences = {}
+      self.t_dictionaries = {}
       self.t_macros = {}
       self.t_presets = {}
       self.t_before = {}
@@ -55,6 +57,7 @@ module Olfactory
       definition = find_macro_definition(name)
       definition ||= find_subtemplate_definition(name)
       definition ||= find_item_definition(name)
+      definition ||= find_dictionary_definition(name)
       definition
     end
 
@@ -82,6 +85,10 @@ module Olfactory
       definition
     end
 
+    def find_dictionary_definition(name)
+      self.t_dictionaries[name]
+    end
+
     def find_preset_definition(name)
       preset_definition = self.find_definition_in_list(name, self.t_presets)
       if preset_definition.nil?
@@ -92,6 +99,15 @@ module Olfactory
       preset_definition
     end
 
+    def reset_sequences(*names)
+      names = self.t_sequences.keys if names.empty?
+      names.each { |name| self.t_sequences[name].reset }
+    end
+    def reset_dictionaries(*names)
+      names = self.t_dictionaries.keys if names.empty?
+      names.each { |name| self.t_dictionaries[name].reset }
+    end
+
     # Defines a value holding field
     def has_one(name, options = {}, &block)
       self.t_items[name] = {  :type => :item,
@@ -114,6 +130,16 @@ module Olfactory
       self.embeds_one(name, options.merge(:collection => (options[:named] ? Hash : Array)), &block)
     end
 
+    # Defines a sequence
+    def sequence(name, options = {}, &block)
+      self.t_sequences[name] = Olfactory::Sequence.new(name, { :scope => :instance }.merge(options), block)
+    end
+
+    # Defines a dictionary
+    def dictionary(name, options = {})
+      self.t_dictionaries[name] = Olfactory::Dictionary.new(name, { :scope => :instance }.merge(options))
+    end
+
     # Defines a macro
     def macro(name, options = {}, &block)
       self.t_macros[name] = { :type => :macro,

data/lib/olfactory/version.rb

@@ -1,3 +1,3 @@
 module Olfactory
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/olfactory.rb

@@ -1,29 +1,86 @@
 # -*- encoding : utf-8 -*-
+require 'olfactory/dictionary'
+require 'olfactory/sequence'
 require 'olfactory/template_definition'
 require 'olfactory/template'
 
 module Olfactory
   @@templates = {}
+  @@sequences = {}
+  @@dictionaries = {}
+
+  # Getters
   def self.templates
     @@templates
   end
+  def self.sequences
+    @@sequences
+  end
+  def self.dictionaries
+    @@dictionaries
+  end
 
+  # Definitions
   def self.template(name, &block)
-    new_template_definition = TemplateDefinition.new
+    new_template_definition = Olfactory::TemplateDefinition.new
     block.call(new_template_definition)
     self.templates[name] = new_template_definition
   end
+  def self.sequence(name, options = {}, &block)
+    sequences[name] = Olfactory::Sequence.new(name, options, block)
+  end
+  def self.dictionary(name)
+    dictionaries[name] = Olfactory::Dictionary.new(name)
+  end
 
-  def self.build_template(name, options = {}, &block)
+  # Invocations
+  def self.build(name, options = {}, &block)
     self.templates[name].build(block, options)
   end
-  def self.create_template(name, options = {}, &block)
+  def self.create(name, options = {}, &block)
     template = self.templates[name].build(block, options)
     template.save!
     template
   end
+  def self.generate(name, options = {}, &block)
+    if sequence = self.sequences[name]
+      sequence.generate(name, options, block)
+    else
+      raise "Unknown sequence '#{name}'!"
+    end
+  end
 
-  def self.reload
+  def self.clear
     @@templates = {}
+    @@sequences = {}
+    @@dictionaries = {}
+  end
+  def self.reset
+    self.reset_sequences
+    self.reset_dictionaries
+    self.reset_template_sequences
+    self.reset_template_dictionaries
+  end
+  def self.reset_sequences(*names)
+    names = self.sequences.keys if names.empty?
+    names.each do |name|
+      self.sequences[name].reset
+    end
+  end
+  def self.reset_template_sequences(template, *names)
+    if template = self.templates[template]
+      template.reset_sequences(*names)
+    end
+  end
+  def self.reset_dictionaries(*names)
+    names = self.dictionaries.keys if names.empty?
+    names.each do |name|
+      self.dictionaries[name].reset
+    end
+  end
+  def self.reset_template_dictionaries(template, *names)
+    if template = self.templates[template]
+      template.reset_dictionaries(*names)
+    end
   end
 end

data/olfactory.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.email       = 'david@davidelner.com'
   s.files       = `git ls-files`.split("\n")
   s.test_files  = `git ls-files -- {spec,features,gemfiles}/*`.split("\n")
-  s.homepage    = 'https://github.com/StreetEasy/olfactory'
+  s.homepage    = 'https://github.com/delner/olfactory'
   s.license     = 'MIT'
 
   s.require_paths = ['lib']
@@ -20,4 +20,6 @@ Gem::Specification.new do |s|
   s.add_development_dependency("pry", "~> 0.10")
   s.add_development_dependency("pry-nav", "~> 0.2")
   s.add_development_dependency("pry-stack_explorer", "~> 0.4.9")
+  s.add_development_dependency('rake', '~> 10.0.4')
+  s.add_development_dependency('yard', '~> 0.8.7.6')
 end

data/spec/olfactory/dictionary_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe Olfactory::Dictionary do
+  before(:context) do
+    Olfactory.dictionary :streets
+  end
+
+  context "given a value" do
+    before(:context) do
+      Olfactory.dictionaries[:streets][:borough => 1, :street => "BROADWAY"] = 10001
+    end
+    let(:key) do
+      { :borough => 1, :street => "BROADWAY" }
+    end
+    let(:value) { 10001 }
+
+    subject { Olfactory.dictionaries[:streets][key] }
+    it { expect(subject).to eq(value) }
+  end
+end

data/spec/olfactory/sequence_spec.rb

@@ -0,0 +1,83 @@
+require 'spec_helper'
+
+describe Olfactory::Sequence do
+  context "with no seed" do
+    before(:example) do
+      Olfactory.sequence :address do |n, options|
+        "#{(n + (n % 2)) + 2} #{"#{options[:prefix]} " if options[:prefix]}BROADWAY"
+      end
+    end
+    context "given nothing" do
+      subject do
+        Olfactory.generate(:address)
+      end
+      it { expect(subject).to eq("2 BROADWAY") }
+    end
+    context "given options" do
+      subject do
+        Olfactory.generate(:address, :prefix => "WEST")
+      end
+      it { expect(subject).to eq("2 WEST BROADWAY") }
+    end
+    context "given a block" do
+      subject do
+        Olfactory.generate(:address) do |n|
+          "#{(n + (n % 2)) + 2} JOHN STREET"
+        end
+      end
+      it { expect(subject).to eq("2 JOHN STREET") }
+    end
+    context "given options and a block" do
+      subject do
+        Olfactory.generate(:address, :suffix => "ROAD") do |n, options|
+          "#{(n + (n % 2)) + 2} JOHN#{options[:suffix] ? " #{options[:suffix]}" : " STREET"}"
+        end
+      end
+      it { expect(subject).to eq("2 JOHN ROAD") }
+    end
+  end
+  context "with a seed" do
+    before(:example) do
+      Olfactory.sequence :address, :seed => 10 do |n, options|
+        "#{(n + (n % 2))} #{"#{options[:prefix]} " if options[:prefix]}BROADWAY"
+      end
+    end
+    context "given nothing" do
+      subject do
+        Olfactory.generate(:address)
+      end
+      it { expect(subject).to eq("10 BROADWAY") }
+    end
+    context "given options" do
+      subject do
+        Olfactory.generate(:address, :prefix => "WEST")
+      end
+      it { expect(subject).to eq("10 WEST BROADWAY") }
+    end
+    context "given a block" do
+      subject do
+        Olfactory.generate(:address) do |n|
+          "#{(n + (n % 2))} JOHN STREET"
+        end
+      end
+      it { expect(subject).to eq("10 JOHN STREET") }
+    end
+    context "given options and a block" do
+      subject do
+        Olfactory.generate(:address, :suffix => "ROAD") do |n, options|
+          "#{(n + (n % 2))} JOHN#{options[:suffix] ? " #{options[:suffix]}" : " STREET"}"
+        end
+      end
+      it { expect(subject).to eq("10 JOHN ROAD") }
+    end
+  end
+  context "given sequential invocations" do
+    before(:context) do
+      Olfactory.sequence :address do |n, options|
+        "#{(n + (n % 2)) + 2} #{"#{options[:prefix]} " if options[:prefix]}BROADWAY"
+      end
+    end
+    it { expect(Olfactory.generate(:address)).to eq("2 BROADWAY") }
+    it { expect(Olfactory.generate(:address)).to eq("4 BROADWAY") }
+  end
+end