assembler 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 459053f97aea6e47c8993857b8bdb82695c39354
-  data.tar.gz: eb0b24fda83cfe8b556a97f0cdcd5108af2970b7
+  metadata.gz: e1d3eb4e375c75519e76037b6ac633be9901d78d
+  data.tar.gz: 0fd01f2626ac0d88104703fa5ea2545d7c581f85
 SHA512:
-  metadata.gz: 6a52ab6904aec79e71a8725aded5372880c75172c52a3101c6794b50a8bd5e4520a12f20d8e7ae4fe4c369376b1d6e5d2c8a4440679e5a62611aa0bf8cb4d3ec
-  data.tar.gz: 4566485a70fc557fb3321bf0586d58e11f1f69f041f946ce166b7e34d7188e5df3d2ab664683142e54def16f3b6e014912e94d5479aec5e18c07836ba97979a0
+  metadata.gz: 4ff23dd635deec43014f704eabbc1282de5f5a7cd1fa6bd584da667eba048ecb39e2b895989e321dfb70c7acb515d219402e15ed983dc8650f262e166bb46842
+  data.tar.gz: d833e8aba1907888013f186e4afc2f22a42edea19d81ff6893791f6dc05f60ca8781396c27a97f8b8e6cc8931081383f8dddf6b509dc5df7b576fab5b8f1b25d

data/.rspec

@@ -1,2 +1 @@
---color
---format documentation
+--require spec_helper

data/CHANGES.md

@@ -1,5 +1,16 @@
 # Changes
 
+## 1.2.0
+
+* Add ability to access (optionally) coerced values on the builder object, for
+  example Foo.new(some: 'value') {|b| puts b.some}. (Ryan Michael)
+* Add `assemble_from_options` DSL method for defining coercions and aliases. (Ryan Michael)
+* Add `before_assembly` and `after_assembly` hooks. (Ben Hamill)
+* Make the `before_assembly` and `after_assembly` hooks additive, in the case
+  that those methods are called more than once. (Ben Hamill)
+* Change up spec set up and move project documentation around a little. (Ben
+  Hamill)
+
 ## 1.1.0
 
 * Make Ruby 1.9-compatible. (Ryan Michael)

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing
+
+Help is gladly welcomed. If you have a feature you'd like to add, it's much more
+likely to get in (or get in faster) the closer you stick to these steps:
+
+1. Open an Issue to talk about it. We can discuss whether it's the right
+  direction or maybe help track down a bug, etc.
+1. Fork the project, and make a branch to work on your feature/fix. Master is
+  where you'll want to start from.
+1. Turn the Issue into a Pull Request. There are several ways to do this, but
+  [hub](https://github.com/defunkt/hub) is probably the easiest.
+1. Make sure your Pull Request includes tests.
+1. Bonus points if your Pull Request updates `CHANGES.md` to include a summary
+   of your changes and your name like the other entries. If the last entry is
+   the last release, add a new `## Unreleased` heading.
+1. *Do not* rev the version number in your pull request.
+
+If you don't know how to fix something, even just a Pull Request that includes a
+failing test can be helpful. If in doubt, make an Issue to discuss.

data/README.md

@@ -7,14 +7,26 @@ bunch of nanomachines that can build [almost anything](http://en.wikipedia.org/w
 
 Assembler is a library that gives you a DSL to describe a super-handy
 initializer pattern. You specify the parameters your object should take and
-Assembler give you an initializer that takes an options hash as well as yielding
-a [builder object](http://c2.com/cgi/wiki?BuilderPattern) to a block. It takes
-care of storing the parameters and gives you private accessors, too.
+Assembler gives you an initializer that takes an options hash as well as
+yielding a [builder object](http://c2.com/cgi/wiki?BuilderPattern) to a block.
+It takes care of storing the parameters and gives you private accessors, too.
+
+## Contents
+
+* [Usage](#usage)
+  * [assemble_from](#assemble_from)
+  * [assemble_from_options](#assemble_from_options)
+  * [Before and After Hooks](#before-and-after-hooks)
+* [Contributing](#contributing)
 
 
 ## Usage
 
-You use it like this:
+### `assemble_from`
+
+The `assemble_from` method is the core of Assembler. It's also aliased as
+`assemble_with`. The basic use case is to pass in required parameters followed
+by optional parameters (and their defaults). Take this simple example:
 
 ```ruby
 class IMAPConnection
@@ -26,8 +38,8 @@ class IMAPConnection
 end
 ```
 
-Then you can instantiate your object with either an options hash or via a block.
-For example:
+This enables you to instantiate your object with either an options hash or via a
+block. For example:
 
 ```ruby
 # These two are equivalent:
@@ -42,9 +54,14 @@ IMAPConnection.new do |aw|
   aw.hostname = 'imap.example.com'
   aw.use_ssl = false
 end
+
+# Or you can do a combination, if you need to:
+IMAPConnection.new(hostname: 'imap.example.com') do |aw|
+  aw.use_ssl = false
+end
 ```
 
-Note that when we set `use_ssl` to `false`, the code respects that, rather than
+Note that when you set `use_ssl` to `false`, the code respects that, rather than
 over-writing anything falsey with the default. If you don't want that, override
 it like with `port`, below.
 
@@ -69,12 +86,14 @@ end
 These various syntaxes enable some trickery when you're dealing with a world of
 uncertainty. Let's look at a more complicated example.
 
-Say we've got a class that lets us describe an Elastic Load Balancer for Amazon
+Say you want a class that lets us describe an Elastic Load Balancer for Amazon
 Web Services. There's a lot of complexity in what each of these arguments might
-be, but the key thing for our example is this: If you have `subnets`, you
+be, but the key thing for this example is this: If you have `subnets`, you
 shouldn't have `availability_zones` and if you have `availability_zones`, you
 shouldn't have `subnets`. And, importantly, you shouldn't send in extraneous
-keys.
+keys; you need to be able to differentiate callers sending `nil` explicitly from
+not sending in anything when you make whatever API calls you're going to make to
+Amazon.
 
 ```ruby
 class AmazonELB
@@ -95,9 +114,9 @@ end
 ```
 
 Now, since there's a lot of complexity in what each of these arguments might be,
-say we've developed some best-practices about what each of them should be. And
-we want to make it easy to pop off slight variations on what we consider to be a
-"standard" ELB.
+say you've developed some best-practices about what each of them should be. And
+you want to make it easy to pop off slight variations on what you consider to be
+a "standard" ELB.
 
 ``` ruby
 module ELBFactory
@@ -108,7 +127,7 @@ module ELBFactory
       elb.security_groups = security_groups
       elb.instance_ids = instance_ids
 
-      elb.health_check =  HealthCheck.new (
+      elb.health_check = HealthCheck.new(
         target: 'HTTP:8000/',
         healthy_threshold: '3',
         unhealthy_threshold: '5',
@@ -143,21 +162,125 @@ would look similar to the above, but require you to assign an intermediate
 variable for no semantic benefit.
 
 
+### `assemble_from_options`
+
+If you need to do something more complicated than what's provided by
+`assemble_from`, you can specify per-argument options using
+`assemble_from_options`. Like `assemble_from`, it's also aliased as
+`assemble_with_options`.
+
+Default values can be specified using the `:default` option, and work the same
+as using hash-syntax with `assemble_from`.
+
+If you would like to do some type of value coercion you can specify either a
+symbol or a callable using the `:coerce` option. Symbols will be passed as
+messages to the input object, and anything that responds to `#call` will be
+called with the input object as an argument.
+
+If you need to accept aliased key names you can use the `:aliases` option to
+specify a list of keys. Aliases only apply to input processing; instance
+variables aren't set and accessors aren't be provided.
+
+```ruby
+class IMAPConnection
+  extend Assembler
+
+  # Here we want to assign an IP address so we only do DNS lookup once.
+  assemble_from_options :hostname, coerce: ->(h) { Resolv.getaddress(h) }
+
+  # Defaults must be specified explicitly; arguments with no default are required.
+  assemble_from_options :use_ssl, default: false
+
+  # We'll accept values named 'port' or 'host_port' (but we'll only assign '@port').
+  # Symbols can also be passed for coercions.
+  assemble_from_options :port, default: nil, coerce: :to_i, aliases: [:host_port]
+end
+
+instance = IMAPConnection.new(hostname: 'localhost') do |b|
+  puts b.hostname   # => '127.0.0.0' - i.e. the accessor returns the coerced value.
+  puts b.use_ssl    # => false - i.e. the accessor returns the default value if none is specified.
+  b.port = '100'    # Will be coerced to the integer 100.
+end
+
+instance.host_port  # => MethodMissing error - accessors aren't defined for aliases.
+```
+
+### Before and After Hooks
+
+In some cases, you might need to take care of some extra things during object
+initialization. One simple case would be if you're inheriting from another class
+and need to call `super` to make sure it initializes correctly. Enter
+`before_assembly` and `after_assembly`.
+
+They both take a block and that block gets evaluated in the scope of your
+instance before or after the rest of Assembler's initializer runs. This means
+instance variables and private methods are available to you and that `self` is
+the object being created. Nothing is `yield`ed to the blocks.
+
+If you don't need to pass arguments or always pass the same arguments, you could
+do something like this:
+
+```ruby
+class Professor < Employee
+  extend Assembler
+
+  before_assembly do
+    super('teaching')
+  end
+end
+```
+
+If, however, you need to react to or interact with options that are passed in,
+you can do something like this:
+
+```ruby
+class Professor < Employee
+  extend Assembler
+
+  attr_reader :title
+
+  assemble_with :department_name, :degree_subject
+  after_assembly do
+    @title = "PhD of #{degree_subject}, #{department_name}"
+  end
+end
+```
+
+If you call these methods more than once, each block will be run in the order
+declared. The most common case would be a child class adding more before or
+after functionality to that declared by a parent.
+
+```ruby
+class Employee
+  extend Assembler
+
+  assemble_with :manager_id, department_name: nil
+
+  attr_reader :manager
+
+  after_assembly do
+    @manager = Manager.find(manager_id)
+  end
+end
+
+class Professor < Employee
+  assemble_with :department_chair
+
+  attr_reader :people_answerable_to
+
+  after_assembly do
+    @people_answerable_to = [manager, department_name]
+  end
+end
+```
+
+
 ## Contributing
 
-Help is gladly welcomed. If you have a feature you'd like to add, it's much more
-likely to get in (or get in faster) the closer you stick to these steps:
-
-1. Open an Issue to talk about it. We can discuss whether it's the right
-  direction or maybe help track down a bug, etc.
-1. Fork the project, and make a branch to work on your feature/fix. Master is
-  where you'll want to start from.
-1. Turn the Issue into a Pull Request. There are several ways to do this, but
-  [hub](https://github.com/defunkt/hub) is probably the easiest.
-1. Make sure your Pull Request includes tests.
-1. Bonus points if your Pull Request updates `CHANGES.md` to include a summary
-   of your changes and your name like the other entries. If the last entry is
-   the last release, add a new `## Unreleased` heading at the top.
-
-If you don't know how to fix something, even just a Pull Request that includes a
-failing test can be helpful. If in doubt, make an Issue to discuss.
+If you'd like to contribute, please see the [contribution guidelines](CONTRIBUTING.md).
+
+
+## Releasing
+
+Maintainers: Please make sure to follow the [release steps](RELEASING.md) when
+it's time to cut a new release.

data/RELEASING.md

@@ -0,0 +1,15 @@
+# Releasing
+
+If you want to push a new version of this gem, do this:
+
+1. Ideally, every Pull Request should already have included an addition to the
+   `CHANGES.md` file summarizing the changes and crediting the author(s). It
+   doesn't hurt to review this to see if anything needs adding.
+1. Commit any changes you make.
+1. Go into version.rb and bump the version number
+   [as appopriate](http://semver.org/).
+1. Go into CHANGES.md and change the "Unlreleased" heading to match the new
+   version number.
+1. Commit these changes with a message like, "Minor version bump," or similar.
+1. Run `rake release`.
+1. High five someone nearby.

data/lib/assembler.rb

@@ -2,19 +2,27 @@ require "assembler/version"
 require "assembler/initializer"
 
 module Assembler
-  attr_writer :required_params, :optional_params
+  def assemble_from_options(*args)
+    assembly_setup do
+      options = args.last.is_a?(Hash) ? args.pop : {}
+      param_names = args
 
-  def assemble_from(*args)
-    optional = args.last.is_a?(Hash) ? args.pop : {}
-    required = args
-
-    include Assembler::Initializer
+      param_names.each do |param_name|
+        param = Parameter.new(param_name, options)
+        assembly_parameters_hash[param.name] = param
+      end
+    end
+  end
+  alias_method :assemble_with_options, :assemble_from_options
 
-    self.required_params += required
-    self.optional_params = optional_params.merge(optional)
+  def assemble_from(*args)
+    assembly_setup do
+      optional = args.last.is_a?(Hash) ? args.pop : {}
+      required = args
 
-    attr_reader *all_param_names
-    private *all_param_names
+      optional.each { |k,v| assemble_from_options(k, default: v) }
+      required.each { |k| assemble_from_options(k) }
+    end
   end
   alias_method :assemble_with, :assemble_from
 
@@ -24,15 +32,39 @@ module Assembler
     assemble_from(*args)
   end
 
-  def required_params
-    @required_params ||= []
+  def before_assembly(&block)
+    assembly_setup do
+      before_assembly_blocks << block
+    end
+  end
+
+  def before_assembly_blocks
+    @before_assembly_blocks ||= []
   end
 
-  def optional_params
-    @optional_params ||= {}
+  def after_assembly(&block)
+    assembly_setup do
+      after_assembly_blocks << block
+    end
   end
 
-  def all_param_names
-    (required_params + optional_params.keys).map(&:to_sym)
+  def after_assembly_blocks
+    @after_assembly_blocks ||= []
+  end
+
+  def assembly_parameters
+    assembly_parameters_hash.values
+  end
+
+  def assembly_parameters_hash
+    @assembly_parameters_hash ||= {}
+  end
+
+  def assembly_setup
+    yield
+  ensure
+    include Assembler::Initializer
+    attr_reader *assembly_parameters.map(&:name)
+    private *assembly_parameters.map(&:name)
   end
 end

data/lib/assembler/builder.rb

@@ -1,27 +1,30 @@
 module Assembler
   class Builder
-    def initialize(*parameter_names)
-      @parameter_names = parameter_names
+    def initialize(parameters_hash, options = {})
+      @options = options
+      @parameters_hash = parameters_hash
 
-      parameter_names.each do |parameter_name|
-        self.singleton_class.class_eval(<<-RUBY)
-          def #{parameter_name}=(value)
-            parameters[:#{parameter_name.to_sym}] = value
-          end
-        RUBY
+      parameters_hash.each do |parameter_name, parameter|
+        parameter.name_and_aliases.each do |name_or_alias|
+          self.singleton_class.class_eval(<<-RUBY)
+            def #{name_or_alias}=(value)
+              options[:#{parameter_name.to_sym}] = value
+            end
+
+            def #{name_or_alias}
+              parameters_hash[:#{parameter_name}].value_from(options)
+            end
+          RUBY
+        end
       end
     end
 
     def to_h
-      parameters
+      options
     end
 
     private
 
-    attr_reader :parameter_names
-
-    def parameters
-      @parameters ||= {}
-    end
+    attr_reader :parameters_hash, :options
   end
 end

data/lib/assembler/initializer.rb

@@ -1,39 +1,36 @@
 require "assembler/builder"
-require "assembler/parameters"
+require "assembler/parameter"
 
 module Assembler
   module Initializer
     def initialize(options={})
-      builder = Assembler::Builder.new(*self.class.all_param_names)
+      if self.class.before_assembly_blocks.any?
+        self.class.before_assembly_blocks.each do |block|
+          instance_eval(&block)
+        end
+      end
+
+      builder = Assembler::Builder.new(self.class.assembly_parameters_hash, options)
 
       yield builder if block_given?
 
-      @full_options = Assembler::Parameters.new(options.merge(builder.to_h))
+      missing_required_parameters = []
 
-      missing_required_params = []
+      self.class.assembly_parameters.each do |param|
+        if_required_and_missing = -> { missing_required_parameters << param.name }
 
-      self.class.required_params.each do |param_name|
-        remember_value_or(param_name) { missing_required_params << param_name }
-      end
+        value = param.value_from(builder.to_h, &if_required_and_missing) 
 
-      self.class.optional_params.each do |param_name, default_value|
-        remember_value_or(param_name) { default_value }
+        instance_variable_set(:"@#{param.name}", value)
       end
 
-      raise(ArgumentError, "missing keywords: #{missing_required_params.join(', ')}") if missing_required_params.any?
-    end
-
-    private
+      raise(ArgumentError, "missing keywords: #{missing_required_parameters.join(', ')}") if missing_required_parameters.any?
 
-    attr_reader :full_options
-
-    def remember_value_or(param_name, &block)
-      instance_variable_set(
-        :"@#{param_name}",
-        full_options.fetch(param_name) do
-          block.call
+      if self.class.after_assembly_blocks.any?
+        self.class.after_assembly_blocks.each do |block|
+          instance_eval(&block)
         end
-      )
+      end
     end
   end
 end

data/lib/assembler/parameter.rb

@@ -0,0 +1,79 @@
+module Assembler
+  class Parameter
+    attr_reader :name
+
+    def initialize(name, options = {})
+      @name         = name.to_sym
+      @options      = options
+    end
+
+    def name_and_aliases
+      @name_and_aliases ||= [name] + aliases.map(&:to_sym)
+    end
+
+    def value_from(hash, &if_required_and_missing)
+      @memoized_value_from ||= {}
+
+      # NOTE: Jruby's Hash#hash implementation is BS:
+      # {:foo => :foo}.hash => 1
+      # {:bar => :bar}.hash => 1
+      # {:foo => :foo}.to_a.hash => 806614226
+      # {:bar => :bar}.to_a.hash => 3120054328
+      # Go figure...
+      memoization_key = hash.to_a.hash
+
+      return @memoized_value_from[memoization_key] if @memoized_value_from[memoization_key]
+
+      first_key = key_names.find { |name_or_alias| hash.has_key?(name_or_alias) }
+
+      raw_value = hash.fetch(first_key) do
+        options.fetch(:default) do
+          if_required_and_missing.call unless if_required_and_missing.nil?
+
+          # Returning here so we don't call coerce_value(nil)
+          return
+        end
+      end
+
+      @memoized_value_from[memoization_key] = coerce_value(raw_value)
+    end
+
+    private
+
+    attr_reader :options
+
+    def key_names
+      name_and_aliases.flat_map do |name_or_alias|
+        [name_or_alias.to_sym, name_or_alias.to_s]
+      end
+    end
+
+    def has_default?
+      options.has_key?(:default)
+    end
+
+    def default
+      options[:default]
+    end
+
+    def coercion
+      options[:coerce]
+    end
+
+    def coerce_value(value)
+      if !coercion
+        value
+      elsif coercion.kind_of?(Symbol)
+        value.send(coercion)
+      elsif coercion.respond_to?(:call)
+        coercion.call(value)
+      else
+        raise ArgumentError, "don't know how to handle coerce value #{coercion}"
+      end
+    end
+
+    def aliases
+      @aliases ||= Array(options[:aliases]) + Array(options[:alias])
+    end
+  end
+end

data/lib/assembler/version.rb

@@ -1,3 +1,3 @@
 module Assembler
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 end

data/spec/after_assembly_spec.rb

@@ -0,0 +1,91 @@
+describe Assembler do
+  describe "#after_assembly" do
+    context "with no other assembler helpers called" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          after_assembly do
+            @after = true
+          end
+
+          attr_reader :after
+        end
+      end
+
+      subject { klass.new }
+
+      it "calls the after block" do
+        expect(subject.after).to be_true
+      end
+    end
+
+    context "with a more complex declaration" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          assemble_with middle: 'middle'
+
+          after_assembly do
+            a_private_method
+            @after = true
+            @middle = 'after'
+          end
+
+          attr_reader :after, :middle
+
+          private
+
+          def a_private_method
+            "Shhhhhhh! it's a secret!"
+          end
+        end
+      end
+
+      subject do
+        klass.new
+      end
+
+      it "calls the after block" do
+        expect(subject.after).to be_true
+      end
+
+      it "calls the block after running the rest of the initializer" do
+        expect(subject.middle).to eq('after')
+      end
+
+      it "allows access to private methods" do
+        expect { klass.new }.to_not raise_error
+      end
+    end
+
+    context "with two after hooks defined" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          after_assembly do
+            hooks << :first
+          end
+
+          after_assembly do
+            hooks << :second
+          end
+
+          def hooks
+            @hooks ||= []
+          end
+        end
+      end
+
+      subject do
+        klass.new
+      end
+
+      it "calls the after hooks in order of declaration" do
+        expect(subject.hooks).to eq([:first, :second])
+      end
+    end
+  end
+end

data/spec/assemble_from_options_spec.rb

@@ -0,0 +1,384 @@
+describe Assembler do
+  describe "#assemble_from_options" do
+    context "without parameters" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options
+        end
+      end
+
+      it "throws away all input parameters (method arguments)" do
+        built_object = subject.new(foo: 'foo', bar: 'bar')
+
+        expect(built_object.instance_variables).to_not include(:@foo, :@bar)
+      end
+
+      it "doesn't have methods on the builder object" do
+        subject.new do |builder|
+          expect(builder).to_not respond_to(:foo=)
+          expect(builder).to_not respond_to(:foo)
+        end
+      end
+    end
+
+    context "with no default parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, :bar
+        end
+      end
+
+      it "barfs from missing required parameters" do
+        expect { subject.new }.to raise_error(ArgumentError)
+      end
+
+      it "holds onto the parameters (method arguments)" do
+        built_object = subject.new(foo: 'baz', bar: 'qux')
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('baz')
+        expect(built_object.instance_variable_get(:@bar)).to eq('qux')
+      end
+
+      it "holds onto the parameters (block)" do
+        built_object = subject.new do |builder|
+          builder.foo = 'baz'
+          builder.bar = 'qux'
+        end
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('baz')
+        expect(built_object.instance_variable_get(:@bar)).to eq('qux')
+      end
+
+      it "ignores un-named parameters in method arguments" do
+        built_object = subject.new(foo: 'foo', bar: 'bar', baz: 'baz')
+
+        expect(built_object.instance_variables).to_not include(:@baz)
+      end
+
+      it "doesn't create builder methods for un-named parameters" do
+        expect {
+          subject.new do |builder|
+            builder.baz = 'baz'
+          end
+        }.to raise_error(NoMethodError)
+      end
+
+      it "provides accessors in the builder object" do
+        subject.new do |builder|
+          builder.foo = :new_foo
+          builder.bar = :new_bar
+
+          expect(builder.foo).to eq(:new_foo)
+        end
+      end
+
+      it "returns nil for un-assigned parameters" do
+        subject.new do |builder|
+          expect(builder.foo).to be_nil
+
+          builder.foo = :new_foo
+          builder.bar = :new_bar
+        end
+      end
+
+      it "incorporates constructor args in the builder accessors" do
+        subject.new(foo: 'new_foo', bar: 'new_bar') do |builder|
+          expect(builder.foo).to eq('new_foo')
+        end
+      end
+    end
+
+    context "with default parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, :bar, default: 'default'
+          assemble_from_options :baz, :qux, default: nil
+        end
+      end
+
+      it "uses default values for missing parameters (method arguments)" do
+        built_object = subject.new
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('default')
+        expect(built_object.instance_variable_get(:@bar)).to eq('default')
+        expect(built_object.instance_variable_get(:@baz)).to eq(nil)
+        expect(built_object.instance_variable_get(:@qux)).to eq(nil)
+      end
+
+      it "uses default values for missing parameters (block)" do
+        built_object = subject.new do |builder|
+        end
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('default')
+        expect(built_object.instance_variable_get(:@bar)).to eq('default')
+        expect(built_object.instance_variable_get(:@baz)).to eq(nil)
+        expect(built_object.instance_variable_get(:@qux)).to eq(nil)
+      end
+
+      it "holds onto the parameters (method arguments)" do
+        built_object = subject.new(foo: 'foo', bar: 'bar', baz: 'baz', qux: 'qux')
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('foo')
+        expect(built_object.instance_variable_get(:@bar)).to eq('bar')
+        expect(built_object.instance_variable_get(:@baz)).to eq('baz')
+        expect(built_object.instance_variable_get(:@qux)).to eq('qux')
+      end
+
+      it "holds onto the parameters (block)" do
+        built_object = subject.new do |builder|
+          builder.foo = 'foo'
+          builder.bar = 'bar'
+          builder.baz = 'baz'
+          builder.qux = 'qux'
+        end
+
+        expect(built_object.instance_variable_get(:@foo)).to eq('foo')
+        expect(built_object.instance_variable_get(:@bar)).to eq('bar')
+        expect(built_object.instance_variable_get(:@baz)).to eq('baz')
+        expect(built_object.instance_variable_get(:@qux)).to eq('qux')
+      end
+
+      it "ignores un-named parameters in method arguments" do
+        built_object = subject.new(nope: 'nope')
+
+        expect(built_object.instance_variables).to_not include(:@nope)
+      end
+
+      it "doesn't create builder methods for un-named parameters" do
+        expect {
+          subject.new do |builder|
+            builder.nope = 'nope'
+          end
+        }.to raise_error(NoMethodError)
+      end
+
+      it "provides accessors in the builder object" do
+        subject.new do |builder|
+          builder.foo = :new_foo
+          expect(builder.foo).to eq(:new_foo)
+        end
+      end
+
+      it "pre-fills default values in the builder accessors" do
+        subject.new do |builder|
+          expect(builder.foo).to eq('default')
+        end
+      end
+
+      it "incorporates constructor args in the builder accessors" do
+        subject.new(foo: 'new_foo') do |builder|
+          expect(builder.foo).to eq('new_foo')
+        end
+      end
+    end
+
+    context "with symbol coerce parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, coerce: :to_set
+          assemble_from_options :bar, coerce: :to_set, default: [:coerced]
+        end
+      end
+
+      let(:argument) { double('argument', to_set: Set.new([:coerced])) }
+
+      it "sends parameter value to constructor argument (method arguments)" do
+        expect(argument).to receive(:to_set).and_return(Set.new([:coerced]))
+        subject.new(foo: argument)
+      end
+
+      it "assigns the output of the coercion (method arguments)" do
+        built_object = subject.new(foo: argument)
+
+        expect(built_object.instance_variable_get(:@foo)).to eq(Set.new([:coerced]))
+      end
+      
+      it "sends parameter value to constructor argument (block)" do
+        expect(argument).to receive(:to_set).and_return(Set.new([:coerced]))
+        subject.new { |b| b.foo = argument }
+      end
+
+      it "assigns the output of the coercion (block)" do
+        built_object = subject.new { |b| b.foo = argument }
+
+        expect(built_object.instance_variable_get(:@foo)).to eq(Set.new([:coerced]))
+      end
+
+      it "coerces default values in the builder accessor" do
+        subject.new(foo: [:foo]) do |builder|
+          expect(builder.bar).to eq(Set.new([:coerced]))
+        end
+      end
+
+      it "coerces constructor args in the builder accessors" do
+        subject.new(foo: [:not_default]) do |builder|
+          expect(builder.foo).to eq(Set.new([:not_default]))
+        end
+      end
+
+      it "coerces assigned values in the buidler accessors" do
+        subject.new do |builder|
+          builder.foo = [:not_default]
+          expect(builder.foo).to eq(Set.new([:not_default]))
+        end
+      end
+    end
+
+    context "with callable coerce parameter" do
+      subject do
+        callable = double('callable')
+        allow(callable).to receive(:call) do |s|
+          [s, :called]
+        end
+
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :lambda, default: nil, coerce: ->(s) { [s, :called] }
+          assemble_from_options :proc, default: nil, coerce: Proc.new { |s| [s, :called] }
+          assemble_from_options :callable, default: nil, coerce: callable
+        end
+      end
+
+      let(:argument) { double('argument') }
+
+      it "assigns the output of the coercion (method arguments)" do
+        expect(subject.new(:lambda => :original).instance_variable_get(:@lambda)).to eq([:original, :called])
+        expect(subject.new(:proc => :original).instance_variable_get(:@proc)).to eq([:original, :called])
+        expect(subject.new(:callable => :original).instance_variable_get(:@callable)).to eq([:original, :called])
+      end
+
+      it "assigns the output of the coercion (block)" do
+        expect(subject.new {|b| b.lambda = :original}.instance_variable_get(:@lambda)).to eq([:original, :called])
+        expect(subject.new {|b| b.proc = :original}.instance_variable_get(:@proc)).to eq([:original, :called])
+        expect(subject.new {|b| b.callable = :original}.instance_variable_get(:@callable)).to eq([:original, :called])
+      end
+
+      it "coerces default values in the builder accessor" do
+        subject.new do |builder|
+          expect(builder.lambda).to eq([nil, :called])
+          expect(builder.proc).to eq([nil, :called])
+          expect(builder.callable).to eq([nil, :called])
+        end
+      end
+
+      it "coerces constructor args in the builder accessors" do
+        subject.new(:lambda => :original, :proc => :original, :callable => :original) do |builder|
+          expect(builder.lambda).to eq([:original, :called])
+          expect(builder.proc).to eq([:original, :called])
+          expect(builder.callable).to eq([:original, :called])
+        end
+      end
+
+      it "coerces assigned values in the buidler accessors" do
+        subject.new do |builder|
+          builder.lambda = :original
+          builder.proc = :original
+          builder.callable = :original
+
+          expect(builder.lambda).to eq([:original, :called])
+          expect(builder.proc).to eq([:original, :called])
+          expect(builder.callable).to eq([:original, :called])
+        end
+      end
+    end
+
+    context "with singular alias parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, :alias => :bar
+        end
+      end
+
+      it "creates an alias" do
+        expect(subject.new(bar: :bar).instance_variable_get(:@foo)).to eq(:bar)
+      end
+    end
+
+    context "with enumerable alias parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, :alias => [:bar, :baz]
+        end
+      end
+
+      it "creates aliases" do
+        expect(subject.new(bar: :bar).instance_variable_get(:@foo)).to eq(:bar)
+        expect(subject.new(baz: :baz).instance_variable_get(:@foo)).to eq(:baz)
+      end
+    end
+
+    context "with singular aliases parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, aliases: :bar
+        end
+      end
+
+      it "creates an alias" do
+        expect(subject.new(bar: :bar).instance_variable_get(:@foo)).to eq(:bar)
+      end
+    end
+
+    context "with enumerable aliases parameter" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo, aliases: [:bar, :baz]
+        end
+      end
+
+      it "creates aliases" do
+        expect(subject.new(bar: :bar).instance_variable_get(:@foo)).to eq(:bar)
+        expect(subject.new(baz: :baz).instance_variable_get(:@foo)).to eq(:baz)
+      end
+    end
+
+    context "when called more than once for the same key" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from_options :foo
+          assemble_from_options :foo, default: :foo, coerce: :to_sym, aliases: [:bar]
+        end
+      end
+
+      it "re-writes default" do
+        expect(subject.new.instance_variable_get(:@foo)).to eq(:foo)
+      end
+
+      it "re-writes aliases (method)" do
+        expect(subject.new(bar: :bar).instance_variable_get(:@foo)).to eq(:bar)
+      end
+
+      it "re-writes aliases (block)" do
+        expect(subject.new { |s| s.bar = :bar}.instance_variable_get(:@foo)).to eq(:bar)
+      end
+
+      it "re-writes coercions (method)" do
+        expect(subject.new(foo: 'foo').instance_variable_get(:@foo)).to eq(:foo)
+      end
+
+      it "re-writes coercions (block)" do
+        expect(subject.new { |s| s.foo = 'foo'}.instance_variable_get(:@foo)).to eq(:foo)
+      end
+    end
+  end
+end
+

data/spec/{assembler_spec.rb → assemble_from_spec.rb}

@@ -1,6 +1,3 @@
-require 'spec_helper'
-require 'assembler'
-
 describe Assembler do
   describe "#assemble_from" do
     context "without parameters" do
@@ -82,6 +79,25 @@ describe Assembler do
           end
         }.to raise_error(NoMethodError)
       end
+
+      it "provides accessors in the builder object" do
+        subject.new do |builder|
+          builder.foo = :new_foo
+          expect(builder.foo).to eq(:new_foo)
+        end
+      end
+
+      it "pre-fills default values in the builder accessors" do
+        subject.new(foo: 'foo') do |builder|
+          expect(builder.bar).to eq('bar')
+        end
+      end
+
+      it "incorporates contructor args in the builder accessors" do
+        subject.new(foo: 'foo', bar: 'new_bar') do |builder|
+          expect(builder.bar).to eq('new_bar')
+        end
+      end
     end
 
     context "when called more than once" do

data/spec/before_assembly_spec.rb

@@ -0,0 +1,80 @@
+describe Assembler do
+  describe "#before_assembly" do
+    context "with no other assembler helpers called" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          before_assembly do
+            @before = true
+          end
+
+          attr_reader :before
+        end
+      end
+
+      subject { klass.new }
+
+      it "calls the before block" do
+        expect(subject.before).to be_true
+      end
+    end
+
+    context "with a more complex declaration" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          assemble_with :middle
+
+          before_assembly do
+            @before = true
+            @middle = 'before'
+          end
+
+          attr_reader :before, :middle
+        end
+      end
+
+      subject do
+        klass.new(middle: 'middle')
+      end
+
+      it "calls the before block" do
+        expect(subject.before).to be_true
+      end
+
+      it "calls the block before running the rest of the initializer" do
+        expect(subject.middle).to eq('middle')
+      end
+    end
+
+    context "with two before hooks defined" do
+      let(:klass) do
+        Class.new do
+          extend Assembler
+
+          before_assembly do
+            hooks << :first
+          end
+
+          before_assembly do
+            hooks << :second
+          end
+
+          def hooks
+            @hooks ||= []
+          end
+        end
+      end
+
+      subject do
+        klass.new
+      end
+
+      it "calls the before hooks in order of declaration" do
+        expect(subject.hooks).to eq([:first, :second])
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -25,3 +25,4 @@ RSpec.configure do |config|
 end
 
 require 'pry'
+require 'assembler'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assembler
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Ben Hamill
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-13 00:00:00.000000000 Z
+date: 2014-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -79,17 +79,22 @@ files:
 - ".rspec"
 - ".travis.yml"
 - CHANGES.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
+- RELEASING.md
 - Rakefile
 - assembler.gemspec
 - lib/assembler.rb
 - lib/assembler/builder.rb
 - lib/assembler/initializer.rb
-- lib/assembler/parameters.rb
+- lib/assembler/parameter.rb
 - lib/assembler/version.rb
-- spec/assembler_spec.rb
+- spec/after_assembly_spec.rb
+- spec/assemble_from_options_spec.rb
+- spec/assemble_from_spec.rb
+- spec/before_assembly_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/benhamill/assembler#readme
 licenses:
@@ -116,5 +121,8 @@ signing_key:
 specification_version: 4
 summary: Block-based initializers for your objects.
 test_files:
-- spec/assembler_spec.rb
+- spec/after_assembly_spec.rb
+- spec/assemble_from_options_spec.rb
+- spec/assemble_from_spec.rb
+- spec/before_assembly_spec.rb
 - spec/spec_helper.rb

data/lib/assembler/parameters.rb

@@ -1,19 +0,0 @@
-module Assembler
-  class Parameters
-    def initialize(params={})
-      @params = params
-    end
-
-    def fetch(key, &block)
-      params.fetch(key.to_sym) do
-        params.fetch(key.to_s) do
-          block.call
-        end
-      end
-    end
-
-    private
-
-    attr_reader :params
-  end
-end