declarative-builder 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8a7a21a5da3c82bf9edcbfc53a0b493e3c886ad0
+  data.tar.gz: 62bb129cb86b262e81792e59bb83ec841ec8df7e
+SHA512:
+  metadata.gz: 574cc0bb1eb623eb61c57b84d156470e400f864f4fc840a1c391826191399f4716a136c4e84de11f666c63397d8217447360efe1d5198c4202e1a5dd69b11e57
+  data.tar.gz: 67a36117a847c5069ac2131eadcb75e9a1116ae1e59a486df79917934dcbbe945b4af59bc8f32b348c9451fd0ee5b0212ed24cd7ecb1d2c869a85b75a6a59f8d

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,10 @@
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - 2.1
+  - 2.2
+  - 2.3.1
+  - jruby-19mode
+  - jruby
+before_install:
+  - gem install bundler

data/CHANGES.md

@@ -0,0 +1,3 @@
+# 0.1.0
+
+* Introduce `Declarative::Builder` as a replacement for `Uber::Builder`.

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in uber.gemspec
+gemspec
+
+gem "minitest-line"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Nick Sutterer
+
+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,355 @@
+# Uber
+
+_Gem-authoring tools like class method inheritance in modules, dynamic options and more._
+
+## Installation
+
+[![Gem Version](https://badge.fury.io/rb/uber.svg)](http://badge.fury.io/rb/uber)
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'uber'
+```
+
+Uber runs with Ruby >= 1.9.3.
+
+# Inheritable Class Attributes
+
+If you want inherited class attributes, this is for you.
+This is a mandatory mechanism for creating DSLs.
+
+```ruby
+require 'uber/inheritable_attr'
+
+class Song
+  extend Uber::InheritableAttr
+
+  inheritable_attr :properties
+  self.properties = [:title, :track] # initialize it before using it.
+end
+```
+
+Note that you have to initialize your class attribute with whatever you want - usually a hash or an array.
+
+```ruby
+Song.properties #=> [:title, :track]
+```
+
+A subclass of `Song` will have a `clone`d `properties` class attribute.
+
+```ruby
+class Hit < Song
+end
+
+Hit.properties #=> [:title, :track]
+```
+
+The cool thing about the inheritance is: you can work on the inherited attribute without any restrictions. It is a _copy_ of the original.
+
+```ruby
+Hit.properties << :number
+
+Hit.properties  #=> [:title, :track, :number]
+Song.properties #=> [:title, :track]
+```
+
+It's similar to ActiveSupport's `class_attribute` but with a simpler implementation.
+It is less dangerous. There are no restrictions for modifying the attribute. [compared to `class_attribute`](http://apidock.com/rails/v4.0.2/Class/class_attribute).
+
+## Uncloneable Values
+
+`::inheritable_attr` will `clone` values to copy them to subclasses. Uber won't attempt to clone `Symbol`, `nil`, `true` and `false` per default.
+
+If you assign any other unclonable value you need to tell Uber that.
+
+```ruby
+class Song
+  extend Uber::InheritableAttr
+  inheritable_attr :properties, clone: false
+```
+
+This won't `clone` but simply pass the value on to the subclass.
+
+
+# Dynamic Options
+
+Implements the pattern of defining configuration options and dynamically evaluating them at run-time.
+
+Usually DSL methods accept a number of options that can either be static values, symbolized instance method names, or blocks (lambdas/Procs).
+
+Here's an example from Cells.
+
+```ruby
+cache :show, tags: lambda { Tag.last }, expires_in: 5.mins, ttl: :time_to_live
+```
+
+Usually, when processing these options, you'd have to check every option for its type, evaluate the `tags:` lambda in a particular context, call the `#time_to_live` instance method, etc.
+
+This is abstracted in `Uber::Options` and could be implemented like this.
+
+```ruby
+require 'uber/options'
+
+options = Uber::Options.new(tags:       lambda { Tag.last },
+                            expires_in: 5.mins,
+                            ttl:        :time_to_live)
+```
+
+Just initialize `Options` with your actual options hash. While this usually happens on class level at compile-time, evaluating the hash happens at run-time.
+
+```ruby
+class User < ActiveRecord::Base # this could be any Ruby class.
+  # .. lots of code
+
+  def time_to_live(*args)
+    "n/a"
+  end
+end
+
+user = User.find(1)
+
+options.evaluate(user, *args) #=> {tags: "hot", expires_in: 300, ttl: "n/a"}
+```
+
+## Evaluating Dynamic Options
+
+To evaluate the options to a real hash, the following happens:
+
+* The `tags:` lambda is executed in `user` context (using `instance_exec`). This allows accessing instance variables or calling instance methods.
+* Nothing is done with `expires_in`'s value, it is static.
+* `user.time_to_live?` is called as the symbol `:time_to_live` indicates that this is an instance method.
+
+The default behaviour is to treat `Proc`s, lambdas and symbolized `:method` names as dynamic options, everything else is considered static. Optional arguments from the `evaluate` call are passed in either as block or method arguments for dynamic options.
+
+This is a pattern well-known from Rails and other frameworks.
+
+## Uber::Callable
+
+A third way of providing a dynamic option is using a "callable" object. This saves you the unreadable lambda syntax and gives you more flexibility.
+
+```ruby
+require 'uber/callable'
+class Tags
+  include Uber::Callable
+
+  def call(context, *args)
+    [:comment]
+  end
+end
+```
+
+By including `Uber::Callable`, uber will invoke the `#call` method on the specified object.
+
+Note how you simply pass an instance of the callable object into the hash instead of a lambda.
+
+```ruby
+options = Uber::Options.new(tags: Tags.new)
+```
+
+## Option
+
+`Uber::Option` implements the pattern of taking an option, such as a proc, instance method name, or static value, and evaluate it at runtime without knowing the option's implementation.
+
+Creating `Option` instances via `::[]` usually happens on class-level in DSL methods.
+
+```ruby
+with_proc    = Uber::Option[ ->(options) { "proc: #{options.inspect}" } ]
+with_static  = Uber::Option[ "Static value" ]
+with_method  = Uber::Option[ :name_of_method ]
+
+def name_of_method(options)
+  "method: #{options.inspect}"
+end
+```
+
+Use `#call` to evaluate the options at runtime.
+
+```ruby
+with_proc.(1, 2)         #=> "proc: [1, 2]"
+with_static.(1, 2)       #=> "Static value"   # arguments are ignored
+with_method.(self, 1, 2) #=> "method: [1, 2]" # first arg is context
+```
+
+It's also possible to evaluate a callable object. It has to be marked with `Uber::Callable` beforehand.
+
+```ruby
+class MyCallable
+  include Uber::Callable
+
+  def call(context, *args)
+    "callable: #{args.inspect}, #{context}"
+  end
+end
+
+with_callable = Uber::Option[ MyCallable.new ]
+```
+
+The context is passed as first argument.
+
+```ruby
+with_callable.(Object, 1, 2) #=> "callable: [1, 2] Object"
+```
+
+You can also make blocks being `instance_exec`ed on the context, giving a unique API to all option types.
+
+```ruby
+with_instance_proc  = Uber::Option[ ->(options) { "proc: #{options.inspect} #{self}" }, instance_exec: true ]
+```
+
+The first argument now becomes the context, exactly the way it works for the method and callable type.
+
+```ruby
+with_instance_proc.(Object, 1, 2) #=> "proc [1, 2] Object"
+```
+
+
+# Delegates
+
+Using `::delegates` works exactly like the `Forwardable` module in Ruby, with one bonus: It creates the accessors in a module, allowing you to override and call `super` in a user module or class.
+
+```ruby
+require 'uber/delegates'
+
+class SongDecorator
+  def initialize(song)
+    @song = song
+  end
+  attr_reader :song
+
+  extend Uber::Delegates
+
+  delegates :song, :title, :id # delegate :title and :id to #song.
+
+  def title
+    super.downcase # this calls the original delegate #title.
+  end
+end
+```
+
+This creates readers `#title` and `#id` which are delegated to `#song`.
+
+```ruby
+song = SongDecorator.new(Song.create(id: 1, title: "HELLOWEEN!"))
+
+song.id #=> 1
+song.title #=> "helloween!"
+```
+
+Note how `#title` calls the original title and then downcases the string.
+
+# Builder
+
+Builders are good for polymorphically creating objects without having to know where that happens. You define a builder with conditions in one class, and that class takes care of creating the actual desired class.
+
+## Declarative Interface
+
+Include `Uber::Builder` to leverage the `::builds` method for adding builders, and `::build!` to run those builders in a given context and with arbitrary options.
+
+
+```ruby
+require "uber/builder"
+
+class User
+  include Uber::Builder
+
+  builds do |options|
+    Admin if params[:admin]
+  end
+end
+
+class Admin
+end
+```
+
+Note that you can call `builds` as many times as you want per class.
+
+Run the builders using `::build!`.
+
+```ruby
+User.build!(User, {})              #=> User
+User.build!(User, { admin: true }) #=> Admin
+```
+The first argument is the context in which the builder blocks will be executed. This is also the default return value if all builders returned a falsey value.
+
+All following arguments will be passed straight through to the procs.
+
+Your API should communicate `User` as the only public class, since the builder hides details about computing the concrete class.
+
+### Builder: Procs
+
+You may also use procs instead of blocks.
+
+```ruby
+class User
+  include Uber::Builder
+
+  builds ->(options) do
+    return SignedIn if params[:current_user]
+    return Admin    if params[:admin]
+    Anonymous
+  end
+end
+```
+
+Note that this allows `return`s in the block.
+
+## Builder: Direct API
+
+In case you don't want the `builds` DSL, you can instantiate a `Builders` object yourself and add builders to it using `#<<`.
+
+```ruby
+MyBuilders = Uber::Builder::Builders.new
+MyBuilders << ->(options) do
+  return Admin if options[:admin]
+end
+```
+
+Note that you can call `Builders#<<` multiple times per instance.
+
+Invoke the builder using `#call`.
+
+```ruby
+MyBuilders.call(User, {})              #=> User
+MyBuilders.call(User, { admin: true }) #=> Admin
+```
+
+Again, the first object is the context/default return value, all other arguments are passed to the builder procs.
+
+## Builder: Contexts
+
+Every proc is `instance_exec`ed in the context you pass into `build!` (or `call`), allowing you to define generic, shareable builders.
+
+```ruby
+MyBuilders = Uber::Builder::Builders.new
+MyBuilders << ->(options) do
+  return self::Admin if options[:admin] # note the self:: !
+end
+
+class User
+  class Admin
+  end
+end
+
+class Instructor
+  class Admin
+  end
+end
+```
+
+Now, depending on the context class, the builder will return different classes.
+
+```ruby
+MyBuilders.call(User, {})              #=> User
+MyBuilders.call(User, { admin: true }) #=> User::Admin
+MyBuilders.call(Instructor, {})              #=> Instructor
+MyBuilders.call(Instructor, { admin: true }) #=> Instructor::Admin
+```
+
+Don't forget the `self::` when writing generic builders, and write tests.
+
+# License
+
+Copyright (c) 2014 by Nick Sutterer <apotonick@gmail.com>
+
+Uber is released under the [MIT License](http://www.opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+desc 'Test the representable gem.'
+task :default => :test
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.test_files = FileList['test/*_test.rb']
+  test.verbose = true
+end

data/declarative-builder.gemspec

@@ -0,0 +1,22 @@
+require File.expand_path('../lib/declarative/builder/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Nick Sutterer"]
+  gem.email         = ["apotonick@gmail.com"]
+  gem.description   = %q{Generic builder pattern.}
+  gem.summary       = %q{Generic builder pattern.}
+  gem.homepage      = "https://github.com/apotonick/declarative-builder"
+  gem.license       = "MIT"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "declarative-builder"
+  gem.require_paths = ["lib"]
+  gem.version       = Declarative::Builder::VERSION
+
+  gem.add_dependency "declarative-option", "< 0.2.0"
+
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "minitest"
+end

data/lib/declarative-builder.rb

@@ -0,0 +1 @@
+require "declarative/builder"

data/lib/declarative/builder.rb

@@ -0,0 +1,44 @@
+require "declarative/option"
+
+module Declarative
+  module Builder
+    def self.included(base)
+      base.extend DSL
+      base.extend Build
+    end
+
+    class Builders < Array
+      def call(context, *args)
+        each do |block|
+          klass = block.(context, *args) and return klass # Declarative::Option#call()
+        end
+
+        context
+      end
+
+      def <<(proc)
+        super Declarative::Option( proc, instance_exec: true ) # lambdas are always instance_exec'ed.
+      end
+    end
+
+    module DSL
+      def builders
+        @builders ||= Builders.new
+      end
+
+      def builds(proc=nil, &block)
+        builders << (proc || block)
+      end
+    end
+
+    module Build
+      # Call this from your class to compute the concrete target class.
+      def build!(context, *args)
+        builders.(context, *args)
+      end
+    end
+  end
+end
+
+
+# Declarative::Builder(->(options) { options[:current_user] ? Bla : Blubb  })

data/lib/declarative/builder/version.rb

@@ -0,0 +1,5 @@
+module Declarative
+  module Builder
+    VERSION = "0.1.0"
+  end
+end

data/test/builder_test.rb

@@ -0,0 +1,147 @@
+require "test_helper"
+require "declarative/builder"
+
+class BuilderTest < MiniTest::Spec
+  Evergreen = Struct.new(:title)
+  Hit  = Struct.new(:title)
+
+  class Song
+    include Declarative::Builder
+
+    builds do |options|
+      if options[:evergreen]
+        Evergreen
+      elsif options[:hit]
+        Hit
+      end
+    end
+
+    def self.build(options)
+      build!(self, 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 Declarative::Builder
+
+    builds do |options|
+      Evergreen if options[:evergreen]
+    end
+
+    builds do |options|
+      Hit if options[:hit]
+    end
+
+    def self.build(options)
+      build!(self, 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. builder do not inherit.
+  class Play < Song
+  end
+
+  it { Play.build({}).must_be_instance_of Play }
+  it { Play.build({evergreen: true}).must_be_instance_of Play }
+  it { Play.build({hit: true}).must_be_instance_of Play }
+
+  # test return from builds
+  class Boomerang
+    include Declarative::Builder
+
+    builds ->(options) do
+      return Song if options[:hit]
+    end
+
+    def self.build(options)
+      build!(self, options).new
+    end
+  end
+
+  it { Boomerang.build({}).must_be_instance_of Boomerang }
+  it { Boomerang.build({hit: true}).must_be_instance_of Song }
+end
+
+
+class BuilderScopeTest < MiniTest::Spec
+  def self.builder_method(options)
+    options[:from_builder_method] and return self
+  end
+
+  class Hit; end
+
+  class Song
+    class Hit
+    end
+
+    include Declarative::Builder
+
+    builds :builder_method # i get called first.
+    builds ->(options) do  # and i second.
+      self::Hit
+    end
+
+    def self.build(context, options={})
+      build!(context, options)
+    end
+  end
+
+  it do
+    Song.build(self.class).must_equal BuilderScopeTest::Hit
+
+    # this runs BuilderScopeTest::builder_method and returns self.
+    Song.build(self.class, from_builder_method: true).must_equal BuilderScopeTest
+  end
+
+  class Evergreen
+    class Hit
+    end
+
+    include Declarative::Builder
+
+    class << self
+      attr_writer :builders
+    end
+    self.builders = Song.builders
+
+    def self.build(context, options={})
+      build!(context, options)
+    end
+
+    def self.builder_method(options)
+      options[:from_builder_method] and return self
+    end
+  end
+
+  it do
+    # running the "copied" block in Evergreen will reference the correct @context.
+    Evergreen.build(Evergreen).must_equal BuilderScopeTest::Evergreen::Hit
+
+    Evergreen.build(Evergreen, from_builder_method: true).must_equal BuilderScopeTest::Evergreen
+  end
+
+  #---
+  # Builders API
+  # Builders#call
+  # Builders#<<
+  A = Class.new
+  MyBuilders = Declarative::Builder::Builders.new
+  MyBuilders << ->(options) do
+    return Song if options[:hit]
+  end
+
+  it { MyBuilders.call(A, {}).new.must_be_instance_of A }
+  it { MyBuilders.call(A, { hit: true }).new.must_be_instance_of Song }
+end

data/test/test_helper.rb

@@ -0,0 +1 @@
+require "minitest/autorun"

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: declarative-builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nick Sutterer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-01-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: declarative-option
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  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: Generic builder pattern.
+email:
+- apotonick@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".travis.yml"
+- CHANGES.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- declarative-builder.gemspec
+- lib/declarative-builder.rb
+- lib/declarative/builder.rb
+- lib/declarative/builder/version.rb
+- test/builder_test.rb
+- test/test_helper.rb
+homepage: https://github.com/apotonick/declarative-builder
+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.6.3
+signing_key: 
+specification_version: 4
+summary: Generic builder pattern.
+test_files:
+- test/builder_test.rb
+- test/test_helper.rb