assembler 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 710b5f3b455cad26bf924085ddb529d5f0f2be3d
-  data.tar.gz: 411e7b9d2ff6cce59cc57b8eb65b236aec9806af
+  metadata.gz: 459053f97aea6e47c8993857b8bdb82695c39354
+  data.tar.gz: eb0b24fda83cfe8b556a97f0cdcd5108af2970b7
 SHA512:
-  metadata.gz: 0857a9705d3ed323475d2629853ca0aec90bec6572b3e9cf1693a8017202cd12150a23902e07218a191044f5b0c671f49a0c924f1b59121ba10259cd6e26b01d
-  data.tar.gz: 2a26f698cf4103bed5f8521c5e21764731eee1ccacafbbbaba84733a2a9b10f4d1b9f450a7997964ed1b0d2e85ea1bc8fff90ca16589349e809c6093e590c022
+  metadata.gz: 6a52ab6904aec79e71a8725aded5372880c75172c52a3101c6794b50a8bd5e4520a12f20d8e7ae4fe4c369376b1d6e5d2c8a4440679e5a62611aa0bf8cb4d3ec
+  data.tar.gz: 4566485a70fc557fb3321bf0586d58e11f1f69f041f946ce166b7e34d7188e5df3d2ab664683142e54def16f3b6e014912e94d5479aec5e18c07836ba97979a0

data/.travis.yml

@@ -3,7 +3,7 @@ rvm:
   - 2.1.1
   - 2.1.0
   - 2.0.0
-  # - 1.9.3
-  # - jruby-19mode
+  - 1.9.3
+  - jruby-19mode
 script:
   - bundle exec rake

data/CHANGES.md

@@ -1,5 +1,11 @@
 # Changes
 
+## 1.1.0
+
+* Make Ruby 1.9-compatible. (Ryan Michael)
+* Rename `assembler_initializer` to `assemble_from`. (Ben Hamill)
+* Better examples in the README. (Ben Hamill)
+
 ## 1.0.0
 
 * Initial Release. (Ben Hamill)

data/README.md

@@ -17,10 +17,10 @@ care of storing the parameters and gives you private accessors, too.
 You use it like this:
 
 ```ruby
-class AwesomeThing
+class IMAPConnection
   extend Assembler
 
-  assembler_initializer :required_param, optional_param: 'default value'
+  assemble_from :hostname, use_ssl: true, port: nil
 
   # Additional business logic here...
 end
@@ -31,51 +31,116 @@ For example:
 
 ```ruby
 # These two are equivalent:
-AwesomeThing.new(required_param: 'specialness')
-AwesomeThing.new do |aw|
-  aw.required_param = 'specialness'
+IMAPConnection.new(hostname: 'imap.example.com')
+IMAPConnection.new do |aw|
+  aw.hostname = 'imap.example.com'
 end
 
 # These two are equivalent:
-AwesomeThing.new(required_param: 'specialness', optional_param: 'override')
-AwesomeThing.new do |aw|
-  aw.required_param = 'specialness'
-  aw.optional_param = 'override'
+IMAPConnection.new(hostname: 'imap.example.com', use_ssl: false)
+IMAPConnection.new do |aw|
+  aw.hostname = 'imap.example.com'
+  aw.use_ssl = false
 end
 ```
 
-This enables some trickery when you're dealing with a world of uncertainty:
+Note that when we 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.
+
+You get private `attr_reader`s for the parameters you specify, but you can
+always override them, if you like. You might have this lower down in your
+`IMAPConnection` class:
 
 ```ruby
-class Foo
-  extend Assembler
-  assembler_initializer :name, :awesome, favorite_color: 'green'
+class IMAPConnection
+  attr_reader :hostname # makes `hostname` public
+
+  def ssl?
+    !!use_ssl
+  end
 
-  def awesome?
-    !!awesome
+  def port
+    @port ||= ssl? ? 993 : 143
   end
 end
+```
 
-def delegating_method(name, awesome=true, favorite_color=nil)
-  Foo.new do |foo|
-    foo.name = name
-    foo.awesome = awesome
+These various syntaxes enable some trickery when you're dealing with a world of
+uncertainty. Let's look at a more complicated example.
 
-    foo.favorite_color = favorite_color if favorite_color
-  end
+Say we've got 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
+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.
+
+```ruby
+class AmazonELB
+  extend Assembler
+  assemble_from(
+    :name,
+    load_balancer_name: nil,
+    health_check: nil,
+    listeners: nil,
+    security_groups: nil,
+    instances: nil,
+    subnets: nil,
+    availability_zones: nil,
+  )
+
+  # Additional, complex business logic...
 end
 ```
 
-The delegating method, here, is empowered to reverse the default for `awesome`,
-but then respect the default for `favorite_color` if the calling code doesn't
-pass anything in (assuming `nil` is unacceptable). It also respects if `awesome`
-has a falsey value passed in.
+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.
+
+``` ruby
+module ELBFactory
+  def self.make_me_an_elb(subnet_ids=nil, availability_zones=nil, name_prefix='', instance_ids=[], security_groups=[])
+    AmazonELB.new do |elb|
+      elb.name = name(name_prefix)
+      elb.load_balancer_name = name(name_prefix)
+      elb.security_groups = security_groups
+      elb.instance_ids = instance_ids
+
+      elb.health_check =  HealthCheck.new (
+        target: 'HTTP:8000/',
+        healthy_threshold: '3',
+        unhealthy_threshold: '5',
+        interval: '30',
+        timeout: '5'
+      )
+      elb.listeners = [Listener.new(...), Listener.new(...)]
+
+      if subnet_ids
+        elb.subnets = subnet_ids
+      else
+        elb.availability_zones = availability_zones
+      end
+    end
+  end
+
+  def self.name(name_prefix)
+    "#{sanitize_for_name(name_prefix)}LoadBalancer"
+  end
+
+  def self.sanitize_for_name(string)
+    # ...
+  end
+end
+```
 
-Especially when you have objects with a lot of potential arguments being passed
-in and don't want to pass keys that you don't have any information about (did
-my caller pass in this `nil`, or is it my own default?), you can use conditional
-logic in the block, rather than conditionally build of a hash just to pass to a
-constructor method.
+Note the `if`/`else` block near the end of the initialization block. If the
+initialization method only took hashes, you would either have to wrap object
+creation in an `if`/`else` and repeat all the constructor arguments that were
+shared between the two cases, or else pre-construct your argument hash, which
+would look similar to the above, but require you to assign an intermediate
+variable for no semantic benefit.
 
 
 ## Contributing

data/lib/assembler.rb

@@ -2,16 +2,37 @@ require "assembler/version"
 require "assembler/initializer"
 
 module Assembler
-  attr_reader :required_params, :optional_params, :all_param_names
+  attr_writer :required_params, :optional_params
+
+  def assemble_from(*args)
+    optional = args.last.is_a?(Hash) ? args.pop : {}
+    required = args
 
-  def assembler_initializer(*required, **optional)
     include Assembler::Initializer
 
-    @required_params = required
-    @optional_params = optional
-    @all_param_names = (required + optional.keys).map(&:to_sym)
+    self.required_params += required
+    self.optional_params = optional_params.merge(optional)
 
     attr_reader *all_param_names
     private *all_param_names
   end
+  alias_method :assemble_with, :assemble_from
+
+  def assembler_initializer(*args)
+    caller_file, caller_line, _ = caller.first.split(':')
+    warn "The `assembler_initializer` method is deprecated and will be phased out in version 2.0. Please use `assemble_from` instead. Called from #{caller_file}:#{caller_line}."
+    assemble_from(*args)
+  end
+
+  def required_params
+    @required_params ||= []
+  end
+
+  def optional_params
+    @optional_params ||= {}
+  end
+
+  def all_param_names
+    (required_params + optional_params.keys).map(&:to_sym)
+  end
 end

data/lib/assembler/version.rb

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

data/spec/assembler_spec.rb

@@ -2,13 +2,13 @@ require 'spec_helper'
 require 'assembler'
 
 describe Assembler do
-  describe "#assembler_initializer" do
+  describe "#assemble_from" do
     context "without parameters" do
       subject do
         Class.new do
           extend Assembler
 
-          assembler_initializer
+          assemble_from
         end
       end
 
@@ -30,7 +30,7 @@ describe Assembler do
         Class.new do
           extend Assembler
 
-          assembler_initializer :foo, bar: 'bar'
+          assemble_from :foo, bar: 'bar'
         end
       end
 
@@ -83,5 +83,26 @@ describe Assembler do
         }.to raise_error(NoMethodError)
       end
     end
+
+    context "when called more than once" do
+      subject do
+        Class.new do
+          extend Assembler
+
+          assemble_from :foo
+          assemble_from bar: 'bar'
+        end
+      end
+
+      it "still takes both arguments" 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
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: assembler
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Ben Hamill
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-01 00:00:00.000000000 Z
+date: 2014-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler