building_blocks 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a8b00f6d31a66e4ee00c4617a1ea5542407a060d
+  data.tar.gz: d68f14603537f03ce13da0d30ccc642e5354153e
+SHA512:
+  metadata.gz: 96a5948aa3fe772601b35ecbea6bcdbfcda56ebe8d0895a21a486077c04d808c2918fdc92a8199ec95854d2685e47cfe526198967c7a68a37c6e08e8bcf9415f
+  data.tar.gz: d7f7ec68e9dc53d0b60c913f54489326db92ac8eb16660aa3285839207523429f2158acce609c2d4ce27d5af928ddf9bfa13e52735d53da03dddb6581bef8a14

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.travis.yml

@@ -0,0 +1,22 @@
+branches:
+  only:
+    - master
+
+before_install:
+  - env
+
+before_script:
+  - bundle exec rake
+
+bundler_args: --without doc
+
+cache:
+  - apt
+  - bundler
+
+language: ruby
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1.1

data/.yardopts

@@ -0,0 +1,7 @@
+--output-dir doc/
+--readme README.md
+--title BuildingBlocks
+--markup=markdown
+--protected
+--private
+lib/**/*.rb

data/Gemfile

@@ -0,0 +1,24 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :doc do
+  gem 'yard', require: false
+end
+
+group :test do
+  gem 'coveralls', :require => false
+  gem 'faker'
+  gem 'minitest'
+  gem 'mocha', :require => false
+  gem 'shoulda-context'
+end
+
+# Dev and test gems not needed for CI
+unless ENV['CI']
+  group :development, :test do
+    gem 'guard'
+    gem 'guard-minitest'
+    gem 'pry-debugger', :platforms => :mri
+  end
+end

data/Guardfile

@@ -0,0 +1,8 @@
+guard :minitest do
+  ignore(%r{.*sw[pon]$})
+
+  watch(%r{^lib/building_blocks.rb}) { 'test' }
+  watch(%r{^lib/building_blocks/(.+)\.rb}) { |m| "test/unit/#{m[1]}_test.rb" }
+  watch(%r{^test/(?:.+/).+_test\.rb$})
+  watch('test/test_helper.rb')  { 'test' }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Interval Braining
+
+MIT License
+
+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
+NONINFRINGEMENT. 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/README.md

@@ -0,0 +1,107 @@
+# BuildingBlocks
+[![Build Status](https://travis-ci.org/interval-braining/building_blocks.png)](https://travis-ci.org/interval-braining/building_blocks)
+[![Coverage Status](https://coveralls.io/repos/interval-braining/building_blocks/badge.png)](https://coveralls.io/r/interval-braining/building_blocks)
+[![Code Climate](https://codeclimate.com/github/interval-braining/building_blocks.png)](https://codeclimate.com/github/interval-braining/building_blocks)
+[![Dependency Status](https://gemnasium.com/interval-braining/building_blocks.png)](https://gemnasium.com/interval-braining/building_blocks)
+
+Simple DSL for defining Builder classes with customized DSLs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'building_blocks'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install building_blocks
+
+## Usage
+
+BuildingBlocks strives to make it easy to create customizable block-based DSLs
+for building all variety of objects.
+
+This is achieved through the use of Builder objects. At their core, Builders are
+any object that defines a `build` method that takes in a block and returns an
+Object. How that block is used and what Object is returned can depend greatly on
+the Builder being used. In some cases the block could be ignored entirely. In
+other cases the Object returned could be a JSON string. It all depends on the
+Builder.
+
+Because Builders are just Plain Old Ruby Objects, there are no restrictions on
+how Builders can be defined or what they can accomplish during their build
+process. However, since there are a few common patterns employed by most
+Builders, BuildingBlocks offers a Buillder Builder that allows for defining
+Builder objects using a simple DSL.
+
+### BuilderBuilder DSL
+Though BuildingBlocks is not itself a Builder, it does implement a `build`
+method that delegates all calls to the configured
+`BuildingBlocks.default_builder`. By default the `default_builder` is configured
+to use `BuildingBlocks::Builders::BuilderBuilder`, a sort of meta-Builder in that
+it's a Builder that also happens to build other valid Builders.
+
+```ruby
+  # Creating a new builder class using the default builder DSL
+  Point = Struct.new(:x, :y)
+  PointBuilder = BuildingBlocks.build do
+    resource_class Point
+    attribute :x
+    attribute :y
+  end
+
+  # Creating a new Point instance using PointBuilder
+  # Both the block arg, builder, and self are the PointBuilder instance
+  point = PointBuilder.build do |builder|
+    x 1
+    y 1
+  end
+  # => #<struct Point x=1, y=1>
+
+
+  # A more complex example of the default builder DSL
+  class Circle
+    attr_accessor :radius
+    attr_reader :center
+
+    def center=(point)
+      raise ArgumentError, 'Bad point' unless point.is_a?(Point)
+      @center = point
+    end
+  end
+
+  CircleBuilder = BuildingBlocks.build do
+    resource_class Circle
+    attribute :radius
+    builder :center, :center=, PointBuilder
+    delegate :x, :x=, :center
+    delegate :y, :y=, :center
+  end
+
+  circle = CircleBuilder.build do |c|
+    radius 5
+    center do |m|
+      x 5
+      y 5
+    end
+
+    # Override the previously set value for y
+    y 1
+  end
+  # => #<Circle @center=#<struct Point x=5, y=1>, @radius=5>
+```
+
+More information on the default builder definition DSL can be found in the
+[docs](http://rubydoc.info/gems/building_blocks/0.0.1/frames)
+
+## Contributing
+
+1. Fork it ( https://github.com/interval-braining/building_blocks/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake.application.options.suppress_backtrace_pattern = /.*/
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

data/building_blocks.gemspec

@@ -0,0 +1,22 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'building_blocks/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'building_blocks'
+  spec.version       = BuildingBlocks::VERSION
+  spec.authors       = ['Danny Guinther']
+  spec.email         = ['dannyguinther@gmail.com']
+  spec.summary       = %q{Block-based Object Builders}
+  spec.description   = %q{Simple DSL for defining block-based Object builders}
+  spec.homepage      = 'https://github.com/interval-braining/building_blocks'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^test/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake', '~> 0'
+end

data/lib/building_blocks.rb

@@ -0,0 +1,59 @@
+require 'forwardable'
+require 'building_blocks/version'
+require 'building_blocks/builders/builder_builder'
+
+# Primary BuildingBlocks object providing an interface to build/define other
+# builders using builders that build new builder objects.
+module BuildingBlocks
+
+  class << self
+    extend Forwardable
+    def_delegator :default_builder, :build
+  end
+
+  # The default builder used for defining new builders when {build build}
+  # is invoked.
+  # @see build
+  # @see BuildingBlocks::Builders::BuilderBuilder
+  DEFAULT_DEFINITION_BUILDER = BuildingBlocks::Builders::BuilderBuilder
+
+  # Returns the object currently configured for use when defining new builders
+  # using {build build}. If a custom value has not been configured the
+  # {DEFAULT_DEFINITION_BUILDER default builder} is returned.
+  # @return [#build] The builder to be used for defining new builders when
+  #   {build build} is invoked.
+  # @see build
+  # @see DEFAULT_DEFINITION_BUILDER
+  def self.default_builder
+    return @default_builder || DEFAULT_DEFINITION_BUILDER
+  end
+
+  # Sets the class that is used when defining new builders when using {build
+  # build} to the provided **builder**. If a value of `nil` or `false` is
+  # provided the {DEFAULT_DEFINITION_BUILDER default builder} will be
+  # used.
+  # @param [#build] builder The object to be used when defining new builders
+  #   when using {build build}.
+  # @raise [ArgumentError] Raised if the object provided does not implement
+  #   a #build method and is neither nil nor false.
+  # @return [#build] The builder argument provided is returned.
+  # @see DEFAULT_DEFINITION_BUILDER
+  # @see build
+  def self.default_builder=(builder)
+    if !!builder && !builder.respond_to?(:build)
+      raise ArgumentError, 'Expected object that responds to #build'
+    end
+    @default_builder = builder
+  end
+
+  # Namespace for builder classes
+  module Builders; end
+
+  # @!method self.build(*args, &block)
+  #   Builds a new object using the the {default_builder default builder}. Any
+  #   **args** or **block** provided are delegated directly to the `build` method
+  #   of the {default_builder default builder}.
+  #   @return [Object] The result of invoking `build` on the
+  #     {#default_builder default builder}.
+  #   @see default_builder
+end

data/lib/building_blocks/builders/builder_builder.rb

@@ -0,0 +1,341 @@
+module BuildingBlocks
+  module Builders
+
+    # A builder that builds other builders using a minimal definition DSL.
+    # In brief, classes generated by this builder offer a number of built-in DSL
+    # macros that are used to describe how methods called against instances of
+    # the generated builder class are translated into actions to be taken on the
+    # {InstanceMethods#instance object instance} being built by the generated
+    # builder instance.
+    class BuilderBuilder
+
+      # Generates a new builder class with a number of built-in DSL methods used
+      # to describe how actions taken against instances of the builder class are
+      # translated into actions to be taken on the {InstanceMethods#instance
+      # object instance} being built. Further information on the available DSL
+      # methods can be found in {ClassInstanceMethods}.
+      # @return [Class] The generated builder class
+      # @see ClassInstanceMethods
+      def self.build
+        klass = Class.new
+        klass.extend(ClassInstanceMethods)
+        klass.send(:include, InstanceMethods)
+        klass.module_eval(&Proc.new) if block_given?
+        klass
+      end
+
+      # Methods available to classes generated by {BuilderBuilder
+      # BuilderBuilder}. Provides a generic, declarative DSL for describing
+      # custom builder classes.
+      module ClassInstanceMethods
+        include Forwardable
+
+        # The default means by which a new instance of the
+        # {ClassInstanceMethods#resource_class resource class} is initialized.
+        # @see {ClassInstanceMethods#initialize_with)
+        DEFAULT_INITIALIZE_WITH = lambda { |instance| resource_class.new }
+
+        # Declares a delegate method that will be available to instances of the
+        # generated builder class that describes a simple attribute that can be
+        # delegated directly to an existing method affiliated with the object
+        # instance being built.
+        #
+        # Though the underlying use of {delegate delegate} gives this method an
+        # enormous amount of potential power, the {attribute attribute} method
+        # is intended for use in fairly simple situations where delegation is
+        # required and the `attribute` descriptor provides some semantic value.
+        # More complex interactions should consider using the
+        # {delegate delegate} method directly to give library users some insight
+        # into the intention for more complex behavior.
+        # @param [String,Symbol] attr_name The name of the method that will be
+        #   available to instances of the generated builder class that when
+        #   invoked will trigger the **receiver_method** on the **receiver**.
+        # @param [String,Symbol] receiver_method The name of the method that
+        #   should be invoked on the **receiver** object when the **attr_name**
+        #   method is invoked. Defaults to a setter form of **attr_name**.
+        # @param [String,Symbol] receiver The object or method of the
+        #   generated builder instance that should receive invocations of
+        #   **receiver_method** when the **attr_name** method is called.
+        #   Defaults to the {InstanceMethods#instance object instance} being
+        #   built.
+        #
+        #   If a String or Symbol value is provided for **receiver**, the value
+        #   provided is resolved against the {InstanceMethods#instance object
+        #   instance} being built at runtime to determine the appropriate
+        #   receiver.
+        #
+        #   For example if a value of :foo were provided for the receiver
+        #   argument, at runtime, the receiver would be resolved to the object
+        #   returned by invoking :foo on the {InstanceMethods#instance object
+        #   instance} being built. Once resolved, the **receiver_method** would
+        #   then be invoked on the receiver with any approprate arguments.
+        # @return [Symbol] The Symbol identifier form of **attr_name**
+        #   identifying the method that will be available to instances of the
+        #   generated builder class.
+        # @see #delegate
+        def attribute(attr_name, receiver_method = :"#{attr_name}=", receiver = nil)
+          delegate(attr_name, receiver_method, receiver)
+          return attr_name.to_sym
+        end
+
+        # By default, builds a new instance of the configured {#resource_class
+        # resource class}. This is achieved by evaluating the configured
+        # {#initialize_with} proc in the context of an instance of the generated
+        # builder class to generate a new object that will be used by the
+        # builder instance. If a block is given, the block is evaluated in the
+        # context of the builder instance after initialization.
+        # @param [Proc] block Optional block evaluated by the generated builder
+        #   class instance after the {InstanceMethods#instance object instance}
+        #   being built has been initialized.
+        # @return [Object] Returns the generated {InstanceMethods#instance
+        #   object instance}.
+        # @see #initialize_with
+        def build
+          instance = instance_eval(&self.initialize_with)
+          builder = new(instance)
+          builder.instance_eval(&Proc.new) if block_given?
+          instance
+        end
+
+        # Declares a method, **attr_name**, available to instances of the
+        # generated builder class, that when called delegates to a
+        # **builder_class** to generate an object that is then passed to the
+        # **receiver_method** of the **receiver**.
+        #
+        # If a **builder_class** is given, the provided **builder_class** is
+        # used to generate the object for the receiver. If no **builder_class**
+        # is given and instead a **block** is provided, the given block is
+        # treated as an anonymous builder definition that is passed to
+        # {BuildingBlocks.build} to generate a new builder class that will be
+        # used later when **attr_name** is invoked on an instance of the
+        # generated builder class.
+        #
+        # See {InstanceMethods#example_builder_attr} for details of the method
+        # invoked when **attr_name** is called on an instance of the generated
+        # builder class.
+        #
+        # @param [String,Symbol] attr_name The name that will be used to define
+        #   the method that will be available to instances of the generated
+        #   builder class that when invoked will trigger the **builder_class**.
+        # @param [String,Symbol] receiver_method The name of the method that
+        #   should be invoked upon the **receiver** object when the
+        #   **attr_name** method is invoked. Defaults to a setter form of
+        #   **attr_name**.
+        # @param [Class] builder_class The builder class that should be used
+        #   to generate new objects when the **attr_name** method is invoked.
+        #   Cannot be used in conjunction with a given **block**.
+        # @param [Proc,String,Symbol] receiver The object or method of the
+        #   generated builder instance that should receive invocations of
+        #   **receiver_method** when the **attr_name** method is called.
+        #   Defaults to the {InstanceMethods#instance object instance} being
+        #   built.
+        #
+        #   If a String or Symbol value is provided for **receiver**, the value
+        #   provided is resolved against the {InstanceMethods#instance object
+        #   instance} being built at runtime to determine the appropriate
+        #   receiver.
+        #
+        #   For example if a value of :foo were provided for the **receiver**
+        #   argument, at runtime, the **receiver** would be resolved to the
+        #   object returned by invoking :foo on the {InstanceMethods#instance
+        #   object instance} being built. Once resolved, the **receiver_method**
+        #   would then be invoked on the **receiver** with any approprate
+        #   arguments.
+        #
+        #   If a Proc is provided for the **receiver** argument, the Proc will
+        #   be evaluated at runtime in the context of the
+        #   {InstanceMethods#instance object instance} being built and should
+        #   return the intended **receiver** object.
+        # @param [Proc] block A block may be provided in place of a predefined
+        #   **builder_class**. If such a block is provided, the given block is
+        #   evaluated by {BuildingBlocks.build} to generate a new anonymous
+        #   builder class. Cannot be used in conjunction with a predefined
+        #   **builder_class**.
+        # @raise [ArgumentError] Raised if both a **builder_class** and a
+        #   **block** are given or neither a **builder_class** nor **block** are
+        #   given.
+        # @return [Symbol] The Symbol identifier form of **attr_name**
+        #   identifying the method that will be available to instances of the
+        #   generated builder class.
+        # @see BuildingBlocks.build
+        # @see #define_builder_method
+        # @see InstanceMethods#example_builder_attr
+        def builder(attr_name, receiver_method = "#{attr_name}=", builder_class = nil, receiver = nil)
+          if block_given? ^ builder_class.nil?
+            raise ArgumentError, 'Either a builder class or a builder definition is required'
+          elsif block_given?
+            builder_class = BuildingBlocks.build(&Proc.new)
+          end
+
+          if receiver.is_a?(Proc)
+            receiver_proc = receiver
+          elsif receiver.is_a?(Symbol) || receiver.is_a?(String)
+            receiver_proc = instance_eval("lambda { |i| @instance.#{receiver} }")
+          else
+            receiver_proc = lambda { |i| @instance }
+          end
+
+          define_builder_method(attr_name, receiver_method, builder_class, receiver_proc)
+          attr_name.to_sym
+        end
+
+        # Declares a delegate method that will be available to instances of the
+        # generated builder class that describes a behavior that should be
+        # delegated from the builder instance to the **receiver_method** of the
+        # derived **receiver**.
+        #
+        # @param [String,Symbol] attr_name An identifer that will be used to
+        #   name the delegate method defined on the builder instance.
+        # @param [String,Symbol] receiver_method The method that should be
+        #   invoked on the **receiver** when the delegate method is invoked.
+        #   Defaults to the same value provided for **attr_name**.
+        # @param [String,Symbol] receiver The object or method of the
+        #   generated builder instance that should receive invocations of
+        #   **receiver_method** when the **attr_name** method is called.
+        #   Defaults to the {InstanceMethods#instance object instance} being
+        #   built.
+        #
+        #   If a String or Symbol value is provided for **receiver**, the value
+        #   provided is resolved against the {InstanceMethods#instance object
+        #   instance} being built at runtime to determine the appropriate
+        #   **receiver**.
+        #
+        #   For example if a value of :foo were provided for the **receiver**
+        #   argument, at runtime, the **receiver** would be resolved to the
+        #   object returned by invoking :foo on the {InstanceMethods#instance
+        #   object instance} being built. Once resolved, the **receiver_method**
+        #   would then be invoked on the **receiver** with any approprate
+        #   arguments.
+        # @return [Symbol] The Symbol identifier form of **attr_name**
+        #   identifying the method that will be available to instances of the
+        #   generated builder class.
+        def delegate(attr_name, receiver_method = attr_name, receiver = nil)
+          receiver = receiver.nil? || receiver.empty? ? :@instance : :"@instance.#{receiver}"
+          def_delegator(receiver, receiver_method, attr_name)
+          attr_name.to_sym
+        end
+
+        # When no block is given, returns the proc currently configured to be
+        # invoked when a new instance of {#resource_class resource class} is
+        # needed. If a custom proc has not been configured, returns the
+        # {DEFAULT_INITIALIZE_WITH default initialization proc}.
+        #
+        # When a block is given, the method acts as a setter and the provided
+        # block is preserved and later used to initialize new instances of
+        # {#resource_class resource class} as they are required.
+        # @return [Proc] The proc that will be used to initialize new instances
+        #   of {#resouce_class resource class}.
+        def initialize_with
+          @initialize_with = Proc.new if block_given?
+          @initialize_with || DEFAULT_INITIALIZE_WITH
+        end
+
+        # Sets a custom proc to be used when initializing new instances of
+        # {#resource_class resource class}.
+        # @param [Proc] initializer The proc to be used to initialize new
+        #   instances or {resource_class resource class}.
+        # @raise [ArgumentError] Raised if the provided **initializer** is
+        #   missing or is not a proc.
+        # @return [Proc] The **initializer** argument provided is returned.
+        def initialize_with=(initializer)
+          unless initializer.is_a?(Proc)
+            raise ArgumentError, "Expected proc initializer, got #{initializer.class.name}"
+          end
+          @initialize_with = initializer
+        end
+
+        # The class that the generated builder class should generate instances
+        # of. When no value is passed for the **klass** argument, returns the
+        # currently configured resource class. If a value is provided for
+        # **klass**, the method acts as a setter and the provided **klass**
+        # argument is preserved and later used for the resource class of the
+        # generated builder class. For further information on how instances of
+        # the {#resource_class resource class} are built, see {#initialize_with}.
+        # @return [Object] The class that the generated builder class will
+        #   generate instances of.
+        # @see #initialize_with
+        def resource_class(klass = nil)
+          @resource_class = klass unless klass.nil?
+          @resource_class
+        end
+
+        # Sets the class that the generated builder class will generate
+        # instances of. For further information on how instances of the
+        # {resource_class resource class} are built, see {#initialize_with}.
+        # @return [Object] The value given for the **klass** argument is
+        #   returned.
+        # @see #initialize_with
+        def resource_class=(klass)
+          @resource_class = klass
+        end
+
+        private
+
+        # Handles the wiring required to invoke a builder when **attr_name** is
+        # invoked.
+        def define_builder_method(attr_name, receiver_method, builder_class, receiver_proc)
+          define_method(attr_name) do |existing_object = nil, &block|
+            begin
+              if block.nil? ^ !!existing_object
+                raise ArgumentError, 'Either a static instance or a builder proc is required'
+              end
+              receiver = instance_eval(&receiver_proc)
+              instance = block.nil? ? existing_object : builder_class.build(&block)
+              receiver.send(receiver_method, instance)
+              instance
+            rescue Exception
+              $@.delete_if{|s| %r"#{Regexp.quote(__FILE__)}"o =~ s}
+              ::Kernel::raise
+            end
+          end
+        end
+      end
+
+      # Methods available to instances of a generated builder class.
+      module InstanceMethods
+        # Initializes a new instance of the generated builder class. Requires
+        # the {ClassInstanceMethods#resource_class resource class} **instance**
+        # that the builder will populate to be provided.
+        # @param [Object] instance The object that should be populated by the
+        #   builder instance.
+        def initialize(instance)
+          @instance = instance
+        end
+
+        # Returns the {InstanceMethods#instance object instance} being built by
+        # the builder instance.
+        # @return [Object] The {InstanceMethods#instance object instance} being
+        #   built by the builder.
+        def instance
+          return @instance
+        end
+
+        # @!method example_builder_attr(existing_object = nil, &block)
+        #   Reference for instance methods defined via {ClassInstanceMethods#builder}.
+        #
+        #   This method is not actually defined, but serves as a reference for
+        #     the instance method defined when an attribute is defined on the
+        #     parent builder class using {ClassInstanceMethods#builder}.
+        #
+        #     Invokes the `receiver_method` of `receiver` with the provided
+        #     **existing_object** or a new object generated by invoking the
+        #     *build* method of the derived `builder_class` with the given
+        #     **block**.
+        #   @param [Object] existing_object An existing object to use as the
+        #     argument to `receiver_method`. Cannot be used in conjunction
+        #     with a block.
+        #   @param [Proc] block A block to be given to the *build* method of
+        #     the derived `builder_class` to generate a new object. Cannot be
+        #     used in conjunction with a provided **existing_object**.
+        #   @raise [ArgumentError] Raised if both an **existing_object** and
+        #     **block** are given or neither an **existing_object** nor
+        #     **block** are provided.
+        #   @return [Object] The provided **existing_object** or the object
+        #     generated by invoking the *build* method of the `builder_class`
+        #     with the given **block**.
+        #   @see ClassInstanceMethods#builder
+      end
+
+    end
+  end
+end

data/lib/building_blocks/version.rb

@@ -0,0 +1,4 @@
+module BuildingBlocks
+  # The version of BuildingBlocks in use.
+  VERSION = '0.0.1'
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+if ENV['CI']
+  require 'coveralls'
+  Coveralls.wear!
+end
+
+require 'minitest/autorun'
+require 'minitest/unit'
+require 'mocha/setup'
+require 'shoulda/context'
+require 'building_blocks'

data/test/unit/builders/builder_builder_test.rb

@@ -0,0 +1,406 @@
+require 'test_helper'
+
+module BuildingBlocks
+  module Builders
+    class BuilderBuilderTest < MiniTest::Test
+
+      context 'BuilderBuilder class methods' do
+
+        should 'generate a new Builder class without block given' do
+          builder = BuilderBuilder.build
+          assert_kind_of Class, builder
+          assert builder.ancestors.include?(BuildingBlocks::Builders::BuilderBuilder::InstanceMethods)
+        end
+
+
+        should 'generate a new Builder class with block given' do
+          new_block_arg = new_self = nil
+          # Validates block form
+          builder = BuilderBuilder.build do |subclass|
+            # Leave marker of instance evaluation
+            define_singleton_method(:builder_evaluated) { true }
+            # Test usage of block argument
+            subclass.resource_class = Hash
+            # Set up variables for evaluation back in the test
+            new_self = self
+            new_block_arg = subclass
+          end
+
+          # Validate DSL context variables
+          assert_equal builder, new_block_arg
+          assert_equal builder, new_self
+
+          # Validate assignments and markers
+          assert_equal Hash, builder.resource_class
+          assert_equal true, builder.builder_evaluated
+        end
+
+      end
+
+
+      context 'BuilderBuilder generated Builder class methods' do
+
+        setup do
+          @struct = struct = Struct.new(:key, :value)
+          @dict_builder = BuildingBlocks.build do
+            resource_class struct
+            attribute(:key)
+            attribute(:value)
+          end
+          @builder = BuildingBlocks.build
+        end
+
+
+        context '::attribute' do
+
+          should 'raise ArgumentError unless attribute name provided' do
+            assert_raises(ArgumentError) { BuildingBlocks.build { attribute } }
+          end
+
+
+          should 'delegate calls to attr_name to receiver via receiver_method' do
+            @builder.expects(:def_delegator).with(:'@instance.c', :b, :a,)
+            @builder.attribute(:a, :b, :c)
+          end
+
+
+          should 'delegate to attr_name= on receiver by default' do
+            @builder.expects(:def_delegator).with(:@instance, :a=, :a,)
+            @builder.attribute(:a)
+          end
+
+
+          should 'delegate directly to the @instance by default' do
+            @builder.expects(:def_delegator).with(:@instance, :a=, :a)
+            @builder.attribute(:a)
+          end
+
+
+          should 'return the Symbol form of the provided attr_name' do
+            result = @builder.attribute(:a)
+            assert_equal :a, result
+          end
+
+        end
+
+
+        context '::builder' do
+
+          should 'raise an error unless a Builder class xor proc is provided' do
+            assert_raises(ArgumentError) do
+              BuildingBlocks.build { builder(:foo) }
+            end
+
+            dict_builder = @dict_builder
+            assert_raises(ArgumentError) do
+              BuildingBlocks.build { builder(:foo, :foo=, dict_builder) { |i| } }
+            end
+          end
+
+
+          should 'raise an error unless an attr_name is provided' do
+            assert_raises(ArgumentError) { BuildingBlocks.build { builder } }
+          end
+
+
+          should 'return the Symbol form of the provided attr_name' do
+            dict_builder = @dict_builder
+            result = @builder.builder(:foo, :value=, dict_builder)
+            assert_equal :foo, result
+          end
+
+
+          should 'take a custom receiver method name' do
+            dict_builder, struct = @dict_builder, @struct
+            builder = BuildingBlocks.build do
+              resource_class struct
+              builder(:foo, :value=, dict_builder)
+            end
+            instance = builder.build { foo { key(:a); value(:b) } }
+            assert_equal :a, instance.value.key
+            assert_equal :b, instance.value.value
+          end
+
+
+          should 'take a custom receiver proc' do
+            dict_builder, struct = @dict_builder, @struct
+            builder = BuildingBlocks.build do
+              resource_class struct
+              builder(:foo, :value=, dict_builder, lambda { |i| String })
+            end
+            String.expects(:value=)
+            builder.build { foo { key(:a); value(:b) } }
+          end
+
+
+          should 'should accept a proc that is a Builder definition' do
+            struct = @struct
+            builder = BuildingBlocks.build do
+              resource_class struct
+              builder(:foo, :value=) do |i|
+                resource_class struct
+                attribute :bar, :key=
+              end
+            end
+            instance = builder.build { foo { bar :a } }
+            assert_equal :a, instance.value.key
+          end
+
+
+          should 'accept a custom builder class' do
+            dict_builder, struct = @dict_builder, @struct
+            db = dict_builder.build
+            dict_builder.expects(:build).returns(db)
+            builder = BuildingBlocks.build do
+              resource_class struct
+              builder(:foo, :value=, dict_builder)
+            end
+            instance = builder.build { foo { |i| } }
+            assert_equal db, instance.value
+          end
+
+
+          should 'accept a custom receiver identifier' do
+            dict_builder, struct = @dict_builder, @struct
+            builder = BuildingBlocks.build do
+              resource_class struct
+              builder(:value, :value=, dict_builder)
+              builder(:foo, :value=, dict_builder, :value)
+            end
+            instance = builder.build do
+              value { key(:a) }
+              foo { |i| value(:b) }
+            end
+            assert_equal :b, instance.value.value.value
+          end
+
+        end
+
+
+        context '::delegate' do
+
+          should 'raise ArgumentError unless method_name provided' do
+            assert_raises(ArgumentError) { @builder.delegate }
+          end
+
+
+          should 'create a delegator to @instance.receiver.receiver_method aliased to method_name' do
+            @builder.expects(:def_delegator).with(:'@instance.receiver', :receiver_method, :method_name)
+            @builder.delegate(:method_name, :receiver_method, :receiver)
+          end
+
+
+          should 'create a delegator to @instance.receiver_method aliased to method_name by default' do
+            @builder.expects(:def_delegator).with(:@instance, :receiver_method, :method_name)
+            @builder.delegate(:method_name, :receiver_method)
+          end
+
+
+          should 'create a delegator to @instance.method_name aliased to method_name by default' do
+            @builder.expects(:def_delegator).with(:@instance, :method_name, :method_name)
+            @builder.delegate(:method_name)
+          end
+
+
+          should 'return the symbol identifier form of attr_name' do
+            assert_equal :method_name, @builder.delegate('method_name')
+          end
+
+        end
+
+
+        context '::new' do
+
+          should 'accept a block and evaluate the block on the builder instance' do
+            struct = @dict_builder.build do
+              key :a
+              value 'a'
+            end
+            assert_equal :a, struct.key
+            assert_equal 'a', struct.value
+          end
+
+
+          should 'return the generated instance when no block given' do
+            the_struct = @struct.new
+            the_struct.key = :a
+            the_struct.value = 'a'
+            @struct.expects(:new).returns(the_struct)
+
+            struct = @dict_builder.build
+            assert_equal :a, struct.key
+            assert_equal 'a', struct.value
+          end
+
+
+          should 'utilize a custom initialize_with proc if available' do
+            @dict_builder.initialize_with do |builder|
+              instance = resource_class.new
+              instance.key = :b
+              instance.value = 'b'
+              instance
+            end
+
+            struct = @dict_builder.build
+            assert_equal :b, struct.key
+            assert_equal 'b', struct.value
+          end
+
+        end
+
+
+        context '::initialize_with' do
+
+          setup do
+            @initializer = lambda { |i| Hash.new }
+            @dict_builder.initialize_with(&@initializer)
+          end
+
+
+          should 'set @initialize_with if given a block' do
+            assert_equal @dict_builder.initialize_with, @initializer
+            assert_equal @dict_builder.instance_variable_get(:@initialize_with), @initializer
+          end
+
+
+          should 'return @initialize_with if no block given' do
+            assert_equal @dict_builder.instance_variable_get(:@initialize_with), @dict_builder.initialize_with
+          end
+
+        end
+
+
+        context '::initialize_with=' do
+
+          setup do
+            @initializer = lambda { |i| Hash.new }
+          end
+
+
+          should 'raise an error if a non-proc is provided' do
+            assert_raises(ArgumentError) do
+              @dict_builder.initialize_with = :foo
+            end
+          end
+
+
+          should 'set @initialize_with if given a proc' do
+            @dict_builder.initialize_with = @initializer
+            assert_equal @dict_builder.initialize_with, @initializer
+            assert_equal @dict_builder.instance_variable_get(:@initialize_with), @initializer
+          end
+
+        end
+
+
+        context '::resource_class' do
+
+          should 'return the current resource_class when no arguments are given' do
+            assert_equal nil, @builder.resource_class
+            @builder.resource_class = @struct
+            assert_equal @struct, @builder.resource_class
+          end
+
+
+          should 'set the current resource_class when an argument is given' do
+            @builder.resource_class(@struct)
+            assert_equal @struct, @builder.resource_class
+          end
+
+
+          should 'set and return the argument given when given an argument' do
+            assert_equal @struct, @builder.resource_class(@struct)
+          end
+
+        end
+
+
+        context '::resource_class=' do
+
+          should 'set the current resource_class' do
+            @builder.resource_class = @struct
+            assert_equal @struct, @builder.resource_class
+          end
+
+
+          should 'return the argument given' do
+            assert_equal @struct, @builder.resource_class = @struct
+          end
+
+        end
+
+      end
+
+
+      context 'BuilderBuilder generated Builder class instance methods' do
+
+        setup do
+          @struct = struct = Struct.new(:key, :value)
+          @dict_builder = BuildingBlocks.build do
+            resource_class struct
+            attribute(:key)
+            attribute(:value)
+          end
+        end
+
+
+        context '::builder generated instance method' do
+
+          setup do
+            dict_builder, struct = @dict_builder, @struct
+            @builder_instance = BuildingBlocks.build do
+              resource_class struct
+              builder(:foo, :value=, dict_builder)
+            end
+          end
+
+
+          should 'raise ArgumentError if given static instance and block or neither' do
+            assert_raises(ArgumentError) { @builder_instance.build { foo } }
+            assert_raises(ArgumentError) do
+              @builder_instance.build { foo(true) {|i| } }
+            end
+          end
+
+
+          should 'pass a static instance to the receiver method of the receiver' do
+            instance = @builder_instance.build { foo(true) }
+            assert_equal true, instance.value
+          end
+
+
+          should 'evaluate builder definition and send instance to the receiver method of receiver' do
+            instance = @builder_instance.build { foo { value(true) } }
+            assert_equal true, instance.value.value
+          end
+
+        end
+
+
+        context '#initialize' do
+
+          should 'require an instance' do
+            assert_raises(ArgumentError) { @dict_builder.new }
+            struct = @struct.new(:k, :v)
+            builder = @dict_builder.new(struct)
+            assert_equal struct, builder.instance
+          end
+
+        end
+
+
+        context '#instance' do
+
+          should 'return the object instance being built' do
+            struct = @struct.new(:k, :v)
+            builder = @dict_builder.new(struct)
+            assert_equal struct, builder.instance
+          end
+
+        end
+
+      end
+
+    end
+  end
+end

data/test/unit/building_blocks_test.rb

@@ -0,0 +1,136 @@
+require 'test_helper'
+
+class BuildingBlocksTest < MiniTest::Test
+
+  DEFAULT_BUILDER = BuildingBlocks::DEFAULT_DEFINITION_BUILDER
+
+  context 'BuildingBlocks' do
+
+    should 'be defined' do
+      assert BuildingBlocks
+    end
+
+
+    context 'Factory methods' do
+
+      context '::build' do
+
+        setup do
+          @builder = BuildingBlocks.build
+        end
+
+
+        should 'return a default Builder instance when no block given' do
+          assert_kind_of Class, @builder
+          assert @builder.ancestors.include?(BuildingBlocks::Builders::BuilderBuilder::InstanceMethods)
+        end
+
+
+        should 'return an evaluated Builder instance when block is given' do
+          struct = Struct.new(:key, :value)
+
+          dict_builder = BuildingBlocks.build do |b|
+            resource_class struct
+            attribute :key
+            attribute :value
+          end
+
+          struct_dict_builder = BuildingBlocks.build do |i|
+            resource_class struct
+            attribute(:key)
+            builder(:value, :value=, dict_builder)
+            delegate(:inner_value, :value=, 'value')
+          end
+
+          dict = dict_builder.build do |b|
+            key(:a)
+            value(:b)
+          end
+          assert_equal :a, dict.key
+          assert_equal :b, dict.value
+
+            struct_dict = struct_dict_builder.build do |b|
+              key(:c)
+              value do
+                key(:d)
+              end
+              inner_value(:e)
+            end
+          assert_equal :c, struct_dict.key
+          assert_equal :d, struct_dict.value.key
+          assert_equal :e, struct_dict.value.value
+        end
+
+      end
+
+    end
+
+
+    context 'configuration' do
+
+      setup do
+        @original_config = BuildingBlocks.default_builder
+        @simple_builder = Class.new do
+          attr_accessor :args, :block
+          def self.build(*args)
+            instance = new
+            instance.block = Proc.new if block_given?
+            instance.args = args
+            instance
+          end
+        end
+      end
+
+
+      teardown do
+        BuildingBlocks.default_builder = @original_config
+      end
+
+
+      context '::default_builder' do
+
+        should 'return @default_defintion_builder or DEFAULT_DEFINITION_BUILDER' do
+          BuildingBlocks.default_builder = nil
+          assert_equal BuildingBlocks.default_builder, DEFAULT_BUILDER
+          BuildingBlocks.default_builder = @simple_builder
+          assert_equal BuildingBlocks.default_builder, @simple_builder
+        end
+
+      end
+
+
+      context '::default_builder=' do
+
+        [nil, false].each do |value|
+          should "accept #{value.inspect} to reset the default_builder" do
+            BuildingBlocks.default_builder = @simple_builder
+            assert_equal BuildingBlocks.default_builder, @simple_builder
+            BuildingBlocks.default_builder = value
+            assert_equal BuildingBlocks.default_builder, DEFAULT_BUILDER
+          end
+        end
+
+
+        should 'raise an error if the proivded object does not respond to #build' do
+          BuildingBlocks.default_builder = nil
+          assert_equal BuildingBlocks.default_builder, DEFAULT_BUILDER
+          assert_raises(ArgumentError) do
+            BuildingBlocks.default_builder = Class.new
+          end
+        end
+
+
+        should 'set the default_builder' do
+          BuildingBlocks.default_builder = nil
+          assert_equal BuildingBlocks.default_builder, DEFAULT_BUILDER
+          BuildingBlocks.default_builder = @simple_builder
+          assert_equal BuildingBlocks.default_builder, @simple_builder
+        end
+
+      end
+
+    end
+
+  end
+
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: building_blocks
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Danny Guinther
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple DSL for defining block-based Object builders
+email:
+- dannyguinther@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- ".yardopts"
+- Gemfile
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- building_blocks.gemspec
+- lib/building_blocks.rb
+- lib/building_blocks/builders/builder_builder.rb
+- lib/building_blocks/version.rb
+- test/test_helper.rb
+- test/unit/builders/builder_builder_test.rb
+- test/unit/building_blocks_test.rb
+homepage: https://github.com/interval-braining/building_blocks
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Block-based Object Builders
+test_files:
+- test/test_helper.rb
+- test/unit/builders/builder_builder_test.rb
+- test/unit/building_blocks_test.rb
+has_rdoc: