uber 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0665bfd37394ce176ce0d33f2c1d1f55f32dfa70
-  data.tar.gz: 9a7bf2915ff6dd350d8d99c92c6a4b4afb9b6510
+  metadata.gz: 496f58fb856e20541ca2984b42e5ff34d6e5ce8d
+  data.tar.gz: 4344bb9b85e4e8ebaa198b1b532045b01cb6ebd9
 SHA512:
-  metadata.gz: b5dc8ce07c0dc65cf1f818294f785f6c6bba0849a4ddf45152a379747ecbc3c981d895a6a6e9f0e8964eecd972234dc1838cbcb27b15f12f25bc12f44268dfbf
-  data.tar.gz: d2dec91003d742e658c4c53350430f3793d3cf2edd43f4ae7644aeb6e12e9cab68c584bbcc4c7b9352feb6e970789fc4ce1ff8699347bf20ed353d825d2c3990
+  metadata.gz: 5adad36ffeacd88e2b0e66aeec0d99eb4f7b51baa8bfaeef89045d23bfbf6adcb70c7d6a94f0fbdecb1fe7a9137b15c07775a9ebdaf9cc9e430119c9fda76c6f
+  data.tar.gz: 78c7dbe731c85b2d8150e020b5d5afeda6bb9cf247d9706cc9fd39c06aad16c7da9cdb4b877479534daed35cbb3cba5f46bcecbc018aacac1daf82a97dded431

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.0.9
+
+* Add `Uber::Builder`.
+
 # 0.0.8
 
 * Add `Uber::Delegates` that provides delegation that can be overridden and called with `super`.

data/README.md

@@ -6,7 +6,9 @@ _Gem-authoring tools like class method inheritance in modules, dynamic options a
 
 Add this line to your application's Gemfile:
 
-    gem 'uber'
+```ruby
+gem 'uber'
+```
 
 Ready?
 
@@ -190,34 +192,74 @@ song.title #=> "helloween!"
 
 Note how `#title` calls the original title and then downcases the string.
 
+
+# Builder
+
+When included, `Builder` allows to add builder instructions on the class level. These can then be evaluated when instantiating
+the class to conditionally build (sub-)classes based on the incoming parameters.
+
+```ruby
+class Listener
+  include Uber::Builder
+
+  builds do |params|
+    SignedIn if params[:current_user]
+  end
+end
+
+class SignedIn
+end
+```
+
+The class then has to use the builder to compute a class name using the build blocks you defined.
+
+```ruby
+class Listener
+  def self.build(params)
+    class_builder.call(params).
+    new(params)
+  end
+end
+```
+
+As you can see, it's still up to you to _instantiate_ the object, the builder only helps you computing the concrete class.
+
+```ruby
+Listener.build({}) #=> Listener
+Listener.build({current_user: @current_user}) #=> SignedIn
+```
+
+This pattern is used in [Cells](https://github.com/apotonick/cells), [Trailblazer](https://github.com/apotonick/trailblazer) and soon Reform and Representable/Roar, too.
+
+
 # Version
 
 Writing gems against other gems often involves checking for versions and loading appropriate version strategies - e.g. _"is Rails >= 4.0?"_. Uber gives you `Version` for easy, semantic version deciders.
 
 ```ruby
-  version = Uber::Version.new("1.2.3")
+version = Uber::Version.new("1.2.3")
 ```
 
 The API currently gives you `#>=` and `#~`.
 
 ```ruby
-  version >= "1.1" #=> true
-  version >= "1.3" #=> false
+version >= "1.1" #=> true
+version >= "1.3" #=> false
 ```
 
 The `~` method does a semantic check (currently on major and minor level, only).
 
 ```ruby
-  version.~ "1.1" #=> false
-  version.~ "1.2" #=> true
-  version.~ "1.3" #=> false
+version.~ "1.1" #=> false
+version.~ "1.2" #=> true
+version.~ "1.3" #=> false
 ```
 
 Accepting a list of versions, it makes it simple to check for multiple minor versions.
 
 ```ruby
-  version.~ "1.1", "1.0" #=> false
-  version.~ "1.1", "1.2" #=> true
+version.~ "1.1", "1.0" #=> false
+version.~ "1.1", "1.2" #=> true
 ```
 
 
@@ -225,10 +267,10 @@ Accepting a list of versions, it makes it simple to check for multiple minor ver
 
 (Please don't read this!)
 
-* You can enforce treating values as dynamic (or not): `Uber::Options::Value.new("time_to_live", dynamic: true)` will always run `#time_to_live` as an instance method on the context, even thou it is not a symbol.
+* You can enforce treating values as dynamic (or not): `Uber::Options::Value.new("time_to_live", dynamic: true)` will always run `#time_to_live` as an instance method on the context, even though it is not a symbol.
 
 # License
 
 Copyright (c) 2014 by Nick Sutterer <apotonick@gmail.com>
 
-Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).
+Roar is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/lib/uber/builder.rb

@@ -0,0 +1,90 @@
+require 'uber/inheritable_attr'
+
+module Uber
+  # When included, allows to add builder on the class level.
+  #
+  #   class Operation
+  #     include Uber::Builder
+  #
+  #     builds do |params|
+  #       SignedIn if params[:current_user]
+  #     end
+  #
+  #     class SignedIn
+  #     end
+  #
+  # The class then has to call the builder to compute a class name using the build blocks you defined.
+  #
+  #     def self.build(params)
+  #       class_builder.call(params).
+  #       new(params)
+  #     end
+  module Builder
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.extend(InheritableAttr)
+      base.inheritable_attr :builders
+      base.builders = []
+    end
+
+    class Constant
+      def initialize(constant) # TODO: evaluate usage of builders and implement using Uber::Options::Value.
+        @constant     = constant
+        @builders     = @constant.builders # only dependency, must be a Cell::Base subclass.
+      end
+
+      def call(*args)
+        build_class_for(*args)
+      end
+
+    private
+      def build_class_for(*args)
+        @builders.each do |blk|
+          klass = run_builder_block(blk, *args) and return klass
+        end
+        @constant
+      end
+
+      def run_builder_block(block, *args)
+        block.call(*args)
+      end
+    end
+
+    module ClassMethods
+      # Adds a builder to the cell class. Builders are used in #cell to find out the concrete
+      # class for rendering. This is helpful if you frequently want to render subclasses according
+      # to different circumstances (e.g. login situations) and you don't want to place these deciders in
+      # your view code.
+      #
+      # Passes the model and options from #cell into the block.
+      #
+      # Multiple build blocks are ORed, if no builder matches the building cell is used.
+      #
+      # Example:
+      #
+      # Consider two different user box cells in your app.
+      #
+      #   class AuthorizedUserBox < UserInfoBox
+      #   end
+      #
+      #   class AdminUserBox < UserInfoBox
+      #   end
+      #
+      # Now you don't want to have deciders all over your views - use a declarative builder.
+      #
+      #   UserInfoBox.build do |model, options|
+      #     AuthorizedUserBox if options[:is_signed_in]
+      #     AdminUserBox if model.admin?
+      #   end
+      #
+      # In your view #cell will instantiate the right cell for you now.
+      def builds(&block)
+        builders << block
+      end
+
+      def class_builder
+        @class_builder ||= Constant.new(self)
+      end
+    end # ClassMethods
+  end
+end

data/lib/uber/uber_version.rb

@@ -1,3 +1,3 @@
 module Uber
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

data/test/builder_test.rb

@@ -0,0 +1,59 @@
+require 'test_helper'
+require "uber/builder"
+
+class BuilderTest < MiniTest::Spec
+  Evergreen = Struct.new(:title)
+  Hit  = Struct.new(:title)
+
+  class Song
+    include Uber::Builder
+
+    builds do |options|
+      if options[:evergreen]
+        Evergreen
+      elsif options[:hit]
+        Hit
+      end
+    end
+
+    def self.build(options)
+      class_builder.call(options).new
+    end
+  end
+
+  # building class if no block matches
+  it { Song.build({}).must_be_instance_of Song }
+
+  it { Song.build({evergreen: true}).must_be_instance_of Evergreen }
+  it { Song.build({hit: true}).must_be_instance_of Hit }
+
+  # test chained builds.
+  class Track
+    include Uber::Builder
+
+    builds do |options|
+      Evergreen if options[:evergreen]
+    end
+
+    builds do |options|
+      Hit if options[:hit]
+    end
+
+    def self.build(options)
+      class_builder.call(options).new
+    end
+  end
+
+  it { Track.build({}).must_be_instance_of Track }
+  it { Track.build({evergreen: true}).must_be_instance_of Evergreen }
+  it { Track.build({hit: true}).must_be_instance_of Hit }
+
+
+  # test inheritance.
+  class Play < Song
+  end
+
+  it { Play.build({}).must_be_instance_of Play }
+  it { Play.build({evergreen: true}).must_be_instance_of Evergreen }
+  it { Play.build({hit: true}).must_be_instance_of Hit }
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: uber
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-01 00:00:00.000000000 Z
+date: 2014-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -52,12 +52,14 @@ files:
 - README.md
 - Rakefile
 - lib/uber.rb
+- lib/uber/builder.rb
 - lib/uber/callable.rb
 - lib/uber/delegates.rb
 - lib/uber/inheritable_attr.rb
 - lib/uber/options.rb
 - lib/uber/uber_version.rb
 - lib/uber/version.rb
+- test/builder_test.rb
 - test/delegates_test.rb
 - test/inheritable_attr_test.rb
 - test/inheritance_test.rb
@@ -92,6 +94,7 @@ specification_version: 4
 summary: Gem-authoring tools like class method inheritance in modules, dynamic options
   and more.
 test_files:
+- test/builder_test.rb
 - test/delegates_test.rb
 - test/inheritable_attr_test.rb
 - test/inheritance_test.rb