uber 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58b218477b8c36e49f66c8bd47175bf605613ef1
-  data.tar.gz: bde8206f4395aa6469f9dfe84eb3651449acd0e3
+  metadata.gz: ca88c9e957495cdf978405ff7c9c7f67d6d0258a
+  data.tar.gz: 151fb75aea52f7485dd8eee7d86afac8b80b61ab
 SHA512:
-  metadata.gz: f08f9af53d76f9800741b6eacd147d031a356b40e309172c1323cf5a80b2f1f70271c1f383f7fbcb2681ac72eaf163b64fc364a36888523688cbbb8147185d22
-  data.tar.gz: 8b6a3e28f375e50b829fe60bf5a2a5ab50daafee28cd5e6334d8488e201b85a12ed915ed0e3c1c84938f5006f5ec55a8b1be07141895bdecc8472c24bfa8348e
+  metadata.gz: 4748f03b0f45606e62428bf2d14a7ad5ab22c29b68f887c012faafb738110d4279c0c818098ba5c3b2f7c531d65dab13710ff53ec50f13f8d00aa6a21cb36e85
+  data.tar.gz: ce170857e5789abd29ea165be5aae4ee4ecb527d80de5224bf1a70c0c232461adade8483a6d1ad3af030c64a83eed1bb0c549aa57d56ebfeda5f768322be0f7b

data/CHANGES.md

@@ -1,3 +1,7 @@
+# 0.0.3
+
+* Add `Options` and `Options::Value´ for abstracting dynamic options.
+
 # 0.0.2
 
 * Add `::inheritable_attr`.

data/README.md

@@ -56,19 +56,89 @@ It's similar to ActiveSupport's `class_attribute` but with a simpler implementat
 This module is very popular amongst numerous gems like Cells, Representable, Roar and Reform.
 
 
-# Options
+# Dynamic Options
 
-Implements the pattern of defining configuration options and evaluating them at run-time.
+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 }, expire_in: 5.mins, ttl: :time_to_live
+```
+
+Usually, when processing these options, you'd have to check every option for its type, evaluate the `tag:` 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
+options = Uber::Options.new(tags: lambda { Tag.last }, expire_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
+    "n/a"
+  end
+end
+
+user = User.find(1)
+
+options.evaluate(user, *args) #=> {tags: "hot", expire_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. All `*args` are passed as block parameters to the lambda.
+* 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. This is a pattern well-known from Rails and other frameworks.
+
+## Evaluating Elements
+
+If you wanna evaluate a single option element, use `#eval`.
+
+```ruby
+options.eval(:ttl, user) #=> "n/a"
+```
+
+## Single Values
+
+Sometimes you don't need an entire hash but a dynamic value, only.
+
+```ruby
+value = Uber::Options::Value.new(lambda { |volume| volume < 0 ? 0 : volume })
+
+value.evaluate(context, -122.18) #=> 0
+```
+
+Use `Options::Value#evaluate` to handle single values.
+
+## Performance
+
+Evaluating an options hash can be time-consuming. When `Options` contains static elements only, it behaves *and performs* like an ordinary hash.
 
-Usually DSL methods accept a number of options that can either be static values, instance method names as symbols, or blocks (lambdas/Procs).
 
 Uber::Options.new volume: 9, track: lambda { |s| s.track }
 
 
-Note that `Options` behaves *and performs* like an ordinary hash when all options are static.
+dynamic: true
 
 only use for declarative assets, not at runtime (use a hash)
 
+# Undocumented Features
+
+(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.
 
 # License
 

data/lib/uber/options.rb

@@ -41,29 +41,42 @@ module Uber
 
     class Value # TODO: rename to Value.
       def initialize(value, options={})
-        @value = value || true
-        @options = options
+        @value, @options = value, options
+
+        return if @options.has_key?(:dynamic)
+
+        # conventional behaviour:
+        @callable = @options[:dynamic] = true if @value.kind_of?(Proc)
+        @options[:dynamic] = true             if @value.is_a?(Symbol)
       end
 
       def evaluate(context, *args)
-        return true if @value.is_a?(TrueClass)
+        return @value unless dynamic?
 
         evaluate_for(context, *args)
       end
 
       def dynamic?
-        @options[:instance_method] || @value.kind_of?(Proc)
+        @options[:dynamic]
       end
 
     private
-      def evaluate_for(context, *args)
-        return proc!(context, *args) unless @value.kind_of?(Proc)
-        @value.call(context, *args) # TODO: change to context.instance_exec and deprecate first argument.
+      def evaluate_for(*args)
+        return method!(*args) unless callable?
+         # TODO: change to context.instance_exec and deprecate first argument.
+         proc!(*args)
+      end
+
+      def method!(context, *args)
+        context.send(@value, *args)
       end
 
       def proc!(context, *args)
-        return context.send(@value, *args) if @options[:instance_method]
-        @value
+        context.instance_exec(*args, &@value)
+      end
+
+      def callable?
+        @callable
       end
     end
   end

data/lib/uber/version.rb

@@ -1,3 +1,3 @@
 module Uber
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/test/inheritance_test.rb

@@ -21,6 +21,9 @@ class InheritanceTest < MiniTest::Spec
 
     CODE_BLOCK = lambda { |base| base.class_eval { extend ClassMethods } } # i want that to be executed at every include
 
+    instance_exec do
+      @block = CODE_BLOCK # this would happen in inherited_included do .. end
+    end
 
     def self.included(includer) #
       # CODE_BLOCK.call(base)

data/test/options_test.rb

@@ -3,18 +3,39 @@ require 'uber/options'
 
 class UberOptionTest < MiniTest::Spec
   Value = Uber::Options::Value
+  let (:object) { Object.new }
 
   describe "#dynamic?" do
-    it { Value.new(1).dynamic?.must_equal false }
-    it { Value.new(true).dynamic?.must_equal false }
-    it { Value.new(:loud).dynamic?.must_equal false }
+    it { Value.new(1).dynamic?.must_equal nil }
+    it { Value.new(true).dynamic?.must_equal nil }
+    it { Value.new("loud").dynamic?.must_equal nil }
+    it { Value.new(:loud, :dynamic => false).dynamic?.must_equal false }
 
     it { Value.new(lambda {}).dynamic?.must_equal true }
     it { Value.new(Proc.new{}).dynamic?.must_equal true }
-    it { Value.new(:method, :instance_method => true).dynamic?.must_equal true }
+    it { Value.new(:method).dynamic?.must_equal true }
   end
 
+  describe "#evaluate" do
+    let (:version) { Module.new { def version; 999 end } }
+
+    it { Value.new(nil).evaluate(Object.new).must_equal nil }
+    # it { Value.new(nil, :dynamic => true).evaluate(Object.new).must_equal nil } # DISCUSS: should we handle that?
+
+    it { Value.new(true).evaluate(Object.new).must_equal true }
+
+    it { Value.new(:version).evaluate(object.extend(version)).must_equal 999 }
+    it { Value.new("version", :dynamic => true).evaluate(object.extend(version)).must_equal 999 }
+    it { Value.new(:version, :dynamic => false).evaluate(object.extend(version)).must_equal :version }
+  end
+
+  describe "passing options" do
+    let (:version) { Module.new { def version(*args); args.inspect end } }
+    let (:block) { Proc.new { |*args| args.inspect } }
 
+    it { Value.new(:version).evaluate(object.extend(version), 1, 2, 3).must_equal "[1, 2, 3]" }
+    it { Value.new(block).evaluate(object, 1, 2, 3).must_equal "[1, 2, 3]" }
+  end
 
   # it "speed" do
   #   require "benchmark"
@@ -34,6 +55,8 @@ class UberOptionTest < MiniTest::Spec
   # end
 end
 
+# TODO: test passing arguments to block and method optionally.
+
 class UberOptionsTest < MiniTest::Spec
   Options = Uber::Options
 
@@ -46,7 +69,7 @@ class UberOptionsTest < MiniTest::Spec
 
   describe "#evaluate" do
 
-    it { dynamic.evaluate(999).must_equal({:volume =>1, :style => "Punkrock", :track => "999"}) }
+    it { dynamic.evaluate(Object.new, 999).must_equal({:volume =>1, :style => "Punkrock", :track => "999"}) }
 
     describe "static" do
       let (:static) { Options.new(:volume =>1, :style => "Punkrock") }
@@ -67,6 +90,6 @@ class UberOptionsTest < MiniTest::Spec
   describe "#eval" do
     it { dynamic.eval(:volume, 999).must_equal 1 }
     it { dynamic.eval(:style, 999).must_equal "Punkrock" }
-    it { dynamic.eval(:track, 999).must_equal "999" }
+    it { dynamic.eval(:track, Object.new, 999).must_equal "999" }
   end
 end

metadata

@@ -1,41 +1,41 @@
 --- !ruby/object:Gem::Specification
 name: uber
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Nick Sutterer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-06 00:00:00.000000000 Z
+date: 2014-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.10.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 0.10.1
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 5.0.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - '>='
       - !ruby/object:Gem::Version
         version: 5.0.0
 description: A gem-authoring framework.
@@ -45,7 +45,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".gitignore"
+- .gitignore
 - CHANGES.md
 - Gemfile
 - LICENSE
@@ -70,17 +70,17 @@ 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.1
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Gem-authoring tools like class method inheritance in modules, dynamic options