sequel-factory 1.0.0

data/README.md

@@ -0,0 +1,105 @@
+**Sequel::Factory** is a little [RubyGem](http://rubygems.org) that lets you
+easily specify factories for your [Sequel](http://sequel.rubyforge.org/) models.
+A factory is an object that knows how to generate an instance of a model. They
+are very useful in testing and development scenarios when you need to simulate
+the existence of real data in your system.
+
+Sequel::Factory supports the following features:
+
+  * Multiple factories per model, with different attributes
+  * Inclusion of the attributes of one factory into another
+  * Ability to configure the `Sequel::Model` method used by a factory to
+    generate instances (defaults to `create`)
+  * Ability to override factory-generated values on instance creation
+  * Sequential attributes (e.g. auto-incrementing ids)
+
+Also, the actual code is only ~100 lines of Ruby, so it should be fairly
+straightforward for you to understand.
+
+## Installation
+
+Using [RubyGems](http://rubygems.org/):
+
+    $ sudo gem install sequel-factory
+
+From a local copy:
+
+    $ git clone git://github.com/mjijackson/sequel-factory.git
+    $ cd sequel-factory
+    $ rake package && sudo rake install
+
+## Usage
+
+Sequel::Factory adds a `factory` method to `Sequel::Model`. You use this
+method to define your factories by passing a block and (optionally) a name. When
+you pass a block a new instance of `Sequel::Factory` is created.
+
+You call a factory using `Sequel::Model.make`. Each time the factory is called
+its block is `instance_eval`'d in the context of the factory. The factory uses
+`method_missing` to catch all unknown method calls and their arguments, which
+should correspond to the names and values of attributes to use for the model.
+
+This may sound a bit complex, but it works out to be very simple in practice.
+
+```ruby
+User.factory do
+  # self is User.factory (or User.factories[:default])
+  name Randgen.name
+end
+
+User.factory(:with_email) do
+  # self is User.factory(:with_email)
+  include_factory User.factory
+  email Randgen.email
+end
+
+user1 = User.make               # Has a "name" attribute
+user2 = User.make(:with_email)  # Has both "name" and "email" attributes
+```
+
+The above example defines two factories on the `User` model: a "default" factory
+and another factory named `:with_email`. The `:with_email` factory _includes_
+the default factory (using `Sequel::Factory#include_factory`), which just means
+that all attributes defined in the default factory will also be set on instances
+that are generated with the `:with_email` factory in addition to any attributes
+it defines itself.
+
+In the example above I'm using the helpful [randexp gem](http://rubygems.org/gems/randexp)
+to generate my factory values, but you can generate them however you like.
+
+If you need to generate unique sequential values you can pass a block to the
+attribute name when you call it in the factory. Each time this block is called
+it takes an incrementing integer value as its argument. The return value of the
+block is used as the value of the attribute.
+
+The following example defines a factory on the `User` model that is able to
+generate a new `User` object with unique `id` and `handle` attributes.
+
+```ruby
+User.factory do
+  id {|n| n }
+  handle "user#{id}"
+end
+```
+
+## License
+
+Copyright 2012 Michael Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+The software is provided "as is", without warranty of any kind, express or
+implied, including but not limited to the warranties of merchantability,
+fitness for a particular purpose and non-infringement. In no event shall the
+authors or copyright holders be liable for any claim, damages or other
+liability, whether in an action of contract, tort or otherwise, arising from,
+out of or in connection with the software or the use or other dealings in
+the software.

data/Rakefile

@@ -0,0 +1,62 @@
+require 'rake/clean'
+
+task :default => :package
+
+# DOCS ########################################################################
+
+desc "Generate API documentation"
+task :api => FileList['lib/**/*.rb'] do |t|
+  output_dir = ENV['OUTPUT_DIR'] || 'api'
+  rm_rf output_dir
+  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  hanna
+    --op #{output_dir}
+    --promiscuous
+    --charset utf8
+    --fmt html
+    --inline-source
+    --line-numbers
+    --accessor option_accessor=RW
+    --main Sequel::Factory
+    --title 'Sequel::Factory API Documentation'
+    #{t.prerequisites.join(' ')}
+  SH
+end
+
+CLEAN.include 'api'
+
+# PACKAGING & INSTALLATION ####################################################
+
+if defined?(Gem)
+  $spec = eval("#{File.read('sequel-factory.gemspec')}")
+
+  directory 'dist'
+
+  def package(ext)
+    "dist/#{$spec.name}-#{$spec.version}#{ext}"
+  end
+
+  file package('.gem') => %w< dist > + $spec.files do |f|
+    sh "gem build sequel-factory.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w< dist > + $spec.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc "Build packages"
+  task :package => %w< .gem .tar.gz >.map {|e| package(e) }
+
+  desc "Build and install as local gem"
+  task :install => package('.gem') do |t|
+    sh "gem install #{package('.gem')}"
+  end
+
+  desc "Upload gem to rubygems.org"
+  task :release => package('.gem') do |t|
+    sh "gem push #{package('.gem')}"
+  end
+end
+
+CLOBBER.include 'dist'

data/lib/sequel/factory.rb

@@ -0,0 +1,123 @@
+require 'sequel'
+
+module Sequel
+  class Factory
+    def initialize(values_proc)
+      @values_proc = values_proc
+    end
+
+    # The Proc this factory uses to generate a new set of values.
+    attr_reader :values_proc
+
+    # Merges all key/value pairs generated by this factory into the
+    # given +values+ hash.
+    def apply_values(values={})
+      @values = values
+      instance_eval(&values_proc)
+      @values
+    end
+
+    # Merges all key/value pairs that are generated by the given +factory+ into
+    # the values currently being generated by this factory. Should be called
+    # inside a values Proc to include values from some higher-level factory.
+    #
+    #   User.factory do
+    #     name Randgen.name
+    #   end
+    #
+    #   User.factory(:with_url) do
+    #     include_factory User.factory
+    #     url "http://www.example.com"
+    #   end
+    #
+    #   User.make               # Has only a name property
+    #   User.make(:with_url)    # Has both name *and* url properties
+    def include_factory(factory)
+      factory.apply_values(@values)
+    end
+
+    alias_method :include, :include_factory
+
+    # Gets/sets the value of the given +key+. If any +args+ are provided, the
+    # value is set to the first one. Otherwise, if a block is given it will be
+    # called with a number unique to the given +key+ (like a sequence) and the
+    # return value of the block is used as the value.
+    def method_missing(key, *args)
+      if args.any?
+        @values[key] = args.first
+      elsif block_given?
+        @counts ||= {}
+        @counts[key] ||= 0
+        @counts[key] += 1
+        @values[key] = yield(@counts[key])
+      end
+
+      @values[key]
+    end
+  end
+
+  class Model
+    class << self
+      attr_writer :factory_method
+    end
+
+    # Returns the name of the Sequel::Model class method that this factory uses
+    # to make new instances. Defaults to +:create+. Other useful methods are
+    # +:new+ (to prevent saving to the database) and +:find_or_create+ (to avoid
+    # violating uniqueness constraints in the database).
+    def self.factory_method
+      return @factory_method unless @factory_method.nil?
+      return superclass.factory_method if superclass.respond_to?(:factory_method)
+      :create
+    end
+
+    # A Hash of factories for this model, keyed by factory name.
+    def self.factories
+      @factories ||= {}
+    end
+
+    # Gets/sets the factory with the given +name+. If a block is given, uses that
+    # block to create a new factory.
+    def self.factory(name=:default)
+      factories[name] = Factory.new(Proc.new) if block_given?
+      factories[name]
+    end
+
+    def self.has_factory?(name)
+      not factory(name).nil?
+    end
+
+    # Makes an instance of this model using the factories with the given
+    # +factory_names+. If a Hash is given as the *last* argument it is used to
+    # override any factory-produced values with the same name after all factory
+    # values have been generated. The default factory is used if no factory
+    # names are given.
+    def self.make(*factory_names)
+      values = Hash === factory_names.last ? factory_names.pop : Hash.new
+      factory_names << :default if factory_names.empty?
+
+      factory_values = factory_names.inject({}) do |memo, name|
+        fac = factory(name) or raise "Unknown #{self} factory: #{name}"
+        fac.apply_values(memo)
+      end
+
+      send factory_method, factory_values.merge(values)
+    end
+
+    # Forces the #factory_method to be the given +method+ temporarily while an
+    # instance is made, then reverts to the old factory method.
+    def self.make_with(method, *args)
+      tmp = @factory_method
+      @factory_method = method
+      obj = make(*args)
+      @factory_method = tmp
+      obj
+    end
+
+    # Sugar for +make_with(:new, *args)+. Useful when the #factory_method is
+    # something other than +:new+ but you still want to use it.
+    def self.build(*args)
+      make_with(:new, *args)
+    end
+  end
+end

data/sequel-factory.gemspec

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
+
+Gem::Specification.new do |s|
+  s.name = 'sequel-factory'
+  s.version = '1.0.0'
+  s.date = Time.now.strftime('%Y-%m-%d')
+
+  s.summary = 'Simple, powerful factories for Sequel models'
+  s.description = 'Simple, powerful factories for Sequel models'
+
+  s.author = 'Michael Jackson'
+  s.email = 'mjijackson@gmail.com'
+
+  s.require_paths = %w< lib >
+
+  s.files = Dir['lib/**/*.rb'] +
+    %w< sequel-factory.gemspec Rakefile README.md >
+
+  s.add_dependency('sequel', '>= 3.32')
+  s.add_development_dependency('rake')
+
+  s.homepage = 'http://mjijackson.github.com/sequel-factory'
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification 
+name: sequel-factory
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Michael Jackson
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-06-23 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: sequel
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 3
+        - 32
+        version: "3.32"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+description: Simple, powerful factories for Sequel models
+email: mjijackson@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/sequel/factory.rb
+- sequel-factory.gemspec
+- Rakefile
+- README.md
+has_rdoc: true
+homepage: http://mjijackson.github.com/sequel-factory
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Simple, powerful factories for Sequel models
+test_files: []
+