contextr 0.1.1 → 0.1.9

data/test/test_layer_state.rb

@@ -1,178 +1,3 @@
 require File.dirname(__FILE__) + "/test_helper.rb"
-
 test_class(:TestLayerState)
-
-# One of the most frequent examples for the use of aspect oriented programming
-# is caching. You have a method, that takes some time to compute a result,
-# but the result is always the same, if the parameters are the same. Such
-# methods are often called functions. The have no side effects and do not depend
-# on inner state.
-#
-# Perhaps you would like to attach caching to such functions. But only under
-# certain circumstances. If your application lacks time, it is a good idea to
-# activate result caching. If it lacks memory, it is a bad one.
-#
-# This perfectly sounds like a problem, that can be solved using 
-# context-oriented programming.
-#
-# But for caching, we need a place to store the computed results. One could
-# store them in the instance that computes them, but this would be strange,
-# because, the code residing in it does not make direct use of this state.
-# Perhaps we are using variables, that other methods use for their own
-# purpose and this would result in strange results. We could use cryptic 
-# instance variable names, but all this is just a workaround.
-#
-# What we want is to attach the state to the code, that uses it. This is the
-# main idea of object-oriented design anyway. So ContextR gives you the 
-# opportunity to save state inside your method modules. Code and state stay
-# side by side. This state will reside there even after deactivating the
-# layer, so you can reuse it. Perfect for our caching approach.
-
-
-# Fibonacci numbers
-# =================
-
-# We will use the good old Fibonacci numbers to demonstrate our approach. First
-# the simple recursive computation, that becomes really slow for larger numbers.
-# I know that there is a non-recursive algorithm, working faster, but this 
-# would not make such a good example. So just assume, that the following
-# code is the fastest, you could possibly get.
-
-module Fibonacci
-  module ClassMethods
-    def compute(fixnum)
-      if fixnum == 1 or fixnum == 0
-        fixnum
-      elsif fixnum < 0
-        raise ArgumentError, "Fibonacci not defined for negative numbers"
-      else
-        compute(fixnum - 1) + compute(fixnum - 2)
-      end
-    end
-  end
-  self.extend(ClassMethods)
-end
-
-example do
-  result_of(Fibonacci.compute(1)) == 1
-  result_of(Fibonacci.compute(2)) == 1
-  result_of(Fibonacci.compute(3)) == 2
-end
-
-# Just to make sure, that it is slow, I will try to compute Fib(100)
-
-require 'timeout'
-example do
-  timeout_raised = false
-  begin
-    Timeout::timeout(0.05) do
-      Fibonacci.compute(100)
-    end
-
-  rescue Timeout::Error
-    timeout_raised = true
-  end
-
-  result_of(timeout_raised) == true
-end
-
-# Okay, the 0.01 seconds are really impatient, but I know, that caching will 
-# come to rescue and makes it happen.
-#
-# Let's define a simple caching method. If I already know the result, return
-# it, if not, let the base implementation compute it and save the it into
-# our variable.
-
-module Fibonacci
-  module ClassMethods
-    module CacheMethods
-      def cache
-        @cache ||= {}
-      end
-
-      def compute(fixnum)
-        cache[fixnum] ||= yield(:next, fixnum)
-      end
-    end
-  end
-
-  extend ClassMethods::CacheMethods => :cache
-end
-
-# If you are not familiar with the above syntax, to define context dependent 
-# behaviour, have a look at test_class_side.rb.
-#
-# Now let's compute Fib(100) again. Of course with caching enabled
-
-example do
-  timeout_raised = false
-  begin
-    Timeout::timeout(0.05) do
-      ContextR::with_layer :cache do
-        result_of(Fibonacci.compute(100)) == 354_224_848_179_261_915_075
-      end
-    end
-
-  rescue Timeout::Error
-    timeout_raised = true
-  end
-
-  # This time the time out was not triggered
-  result_of(timeout_raised) == false 
-end
-
-# It is that simple to add state to your method modules. And just to make sure,
-# that I did not cheat, I will add a simple case, were instance variables and
-# layer specific variables _would_ conflict, but in fact don't.
-
-class LayerStateExample
-  attr_accessor :state
-  module StateMethods
-    attr_accessor :state
-  end
-
-  include StateMethods => :test_layer_state
-end
-
-# When StateMethods would be included normally, its attr_accessor would simply
-# be the same as in the class. But this does not happen, when using layers.
-#
-# Let's do a little warm up and make sure, everything works as expected.
-
-$layer_state_example = LayerStateExample.new
-
-example do
-  $layer_state_example.state = true
-  result_of($layer_state_example.state) == true
-  $layer_state_example.state = false 
-  result_of($layer_state_example.state) == false
-
-  ContextR::with_layer :test_layer_state do
-    $layer_state_example.state = true
-    result_of($layer_state_example.state) == true
-    $layer_state_example.state = false 
-    result_of($layer_state_example.state) == false
-  end
-end
-
-# Until now, I did not prove anything. Let's try it.
-
-example do
-  # Set the state
-  $layer_state_example.state = true
-  ContextR::with_layer :test_layer_state do
-    $layer_state_example.state = false 
-  end
-
-  # And make sure, that they differ
-  result_of($layer_state_example.state) == true
-
-  ContextR::with_layer :test_layer_state do
-    result_of($layer_state_example.state) == false
-  end
-end
-
-# The last example was very theoretical and looks strange when seen isolated.
-# Its main purpose is to show, that layer specific methods and base methods
-# do not share their state, and that the layer specific state remains, also
-# after layer deactivation. Don't take too serious.
+LiterateMarukuTest.load(__FILE__)

data/test/test_meta_api.mkd

@@ -0,0 +1,21 @@
+ContextR knows two basic reflection mechanisms. One is to query the currently
+active layers.
+
+    example do
+      ContextR::with_layer :a do
+        assert_equal([:a], ContextR::active_layers)
+        ContextR::with_layer :b do
+          assert_equal([:a, :b], ContextR::active_layers)
+        end
+        assert_equal([:a], ContextR::active_layers)
+      end
+    end
+
+The second is to query all layers, that where ever defined.
+
+    example do
+      assert(ContextR::layers.include?(:a))
+      assert(ContextR::layers.include?(:b))
+    end
+
+

data/test/test_meta_api.rb

@@ -0,0 +1,4 @@
+require File.dirname(__FILE__) + "/test_helper.rb"
+
+test_class(:TestMetaApi)
+LiterateMarukuTest.load(__FILE__)

data/test/test_ordering.mkd

@@ -0,0 +1,142 @@
+This document tries to demonstrate the invocation order within 
+context-specific method calls. There are two cases where this is relevant:
+1. There is more than one layer active, that extends the method.
+2. There is more than one module in a single layer that extends the method.
+
+Unfortunately I could not find any relevant example that clearly demonstrates
+this behaviour. Therefore I will use foo bar code. But I think it is still
+easy to get the message.
+
+I. Multiple active layers
+-------------------------
+
+Define the basis first.
+
+    class OrderingTest
+      def test_method 
+        "base_method"
+      end
+
+      module FooMethods
+        def test_method
+          "foo_before #{super} foo_after"
+        end
+      end
+      module BarMethods
+        def test_method
+          "bar_before #{super} bar_after"
+        end
+      end
+
+      in_layer :foo do
+        include FooMethods
+      end
+      in_layer :bar do
+        include BarMethods
+      end
+    end
+
+When multiple layers extend a single method, the order of activation 
+determines the order of execution.
+
+    example do
+      instance = OrderingTest.new
+      result_of(instance.test_method) == "base_method"
+
+      ContextR::with_layer :foo do
+        result_of(instance.test_method) == "foo_before base_method foo_after"
+      end
+      ContextR::with_layer :bar do
+        result_of(instance.test_method) == "bar_before base_method bar_after"
+      end
+
+      ContextR::with_layer :bar, :foo do
+        result_of(instance.test_method) == 
+                        "bar_before foo_before base_method foo_after bar_after"
+      end
+
+      ContextR::with_layer :bar do
+        ContextR::with_layer :foo do
+          result_of(instance.test_method) == 
+                        "bar_before foo_before base_method foo_after bar_after"
+        end
+      end
+
+      ContextR::with_layer :foo, :bar do
+        result_of(instance.test_method) == 
+                        "foo_before bar_before base_method bar_after foo_after"
+      end
+
+      ContextR::with_layer :foo do
+        ContextR::with_layer :bar do
+          result_of(instance.test_method) == 
+                        "foo_before bar_before base_method bar_after foo_after"
+        end
+      end
+    end
+
+As you can see, the innermost layer activation provides the innermost method
+definition. It is not important, whether the layers were activated at once
+or one after the other.
+
+Activating an already active layer may update the execution order. The outer
+activation is hidden, but is restored again after leaving the block.
+
+    example do
+      instance = OrderingTest.new
+
+      ContextR::with_layer :bar, :foo do
+        result_of(instance.test_method) == 
+                        "bar_before foo_before base_method foo_after bar_after"
+
+        ContextR::with_layer :bar do
+          result_of(instance.test_method) == 
+                        "foo_before bar_before base_method bar_after foo_after"
+        end
+
+        result_of(instance.test_method) == 
+                        "bar_before foo_before base_method foo_after bar_after"
+      end
+    end
+
+
+II. Multiple modules per layer and class
+----------------------------------------
+
+It is also possible to have more than one module define the context-dependent
+behaviour of a class. In this case it may also happen, that multiple modules
+extend the same method definition.
+
+In this case we can reuse or already defined class and modules. This time
+we include them into the same layer and see what happens.
+
+    class OrderingTest
+      in_layer :foo_bar do
+        include FooMethods
+        include BarMethods
+      end
+    end
+     
+    example do
+      instance = OrderingTest.new
+      result_of(instance.test_method) == "base_method"
+
+      ContextR::with_layer :foo_bar do
+        result_of(instance.test_method) == 
+                        "bar_before foo_before base_method foo_after bar_after"
+      end
+    end
+
+This time the last inclusion defines the outermost method. But this is just Ruby's way of (multiple) inheritance and not part of ContextR. For the same reason a second inclusion of `FooMethod`s will not update the execution order.
+
+III. Conclusion
+---------------
+
+These should be all case where ordering matters. If you are aware of the
+two basic rules, everything should work as expected. 
+
+  1. Execution order of different layers is determined by layer activation.
+  2. Execution within layers is ordered in the way Ruby handles inheritance.
+
+In an ideal world the the execution order would not be important. But hey, 
+this is not the ideal world, so you better know.

data/test/test_ordering.rb

@@ -1,146 +1,3 @@
 require File.dirname(__FILE__) + "/test_helper.rb"
-
 test_class(:TestOrdering)
-
-# This document tries to demonstrate the invocation order within 
-# context-specific method calls. There are two cases where this is relevant:
-# 1. There is more than one layer active, that extends the method.
-# 2. There is more than one module in a single layer that extends the method.
-#
-# Unfortunately I could not find any relevant example that clearly demonstrates
-# this behaviour. Therefore I will use foo bar code. But I think it is still
-# easy to get the message.
-
-# 1. Multiple active layers
-# =========================
-
-class OrderingTest
-  def test_method 
-    "base_method"
-  end
-
-  module FooMethods
-    def test_method
-      "foo_before #{yield(:next)} foo_after"
-    end
-  end
-  module BarMethods
-    def test_method
-      "bar_before #{yield(:next)} bar_after"
-    end
-  end
-
-  include FooMethods => :foo
-  include BarMethods => :bar
-end
-
-# When multiple layers extend a single method, the order of activation 
-# determines the order of execution.
-
-example do
-  instance = OrderingTest.new
-  result_of(instance.test_method) == "base_method"
-
-  ContextR::with_layer :foo do
-    result_of(instance.test_method) == "foo_before base_method foo_after"
-  end
-  ContextR::with_layer :bar do
-    result_of(instance.test_method) == "bar_before base_method bar_after"
-  end
-
-  ContextR::with_layer :bar, :foo do
-    result_of(instance.test_method) == 
-                      "bar_before foo_before base_method foo_after bar_after"
-  end
-
-  ContextR::with_layer :bar do
-    ContextR::with_layer :foo do
-      result_of(instance.test_method) == 
-                      "bar_before foo_before base_method foo_after bar_after"
-    end
-  end
-
-  ContextR::with_layer :foo, :bar do
-    result_of(instance.test_method) == 
-                      "foo_before bar_before base_method bar_after foo_after"
-  end
-
-  ContextR::with_layer :foo do
-    ContextR::with_layer :bar do
-      result_of(instance.test_method) == 
-                      "foo_before bar_before base_method bar_after foo_after"
-    end
-  end
-end
-
-# As you can see, the innermost layer activation provides the innermost method
-# definition. It is not important, whether the layers were activated at once
-# or one after the other.
-#
-# Activating and already active layer may update the execution order. The outer
-# activation is hidden, but is restored again after leaving the block.
-
-example do
-  instance = OrderingTest.new
-
-  ContextR::with_layer :bar, :foo do
-    result_of(instance.test_method) == 
-                      "bar_before foo_before base_method foo_after bar_after"
-
-    ContextR::with_layer :bar do
-      result_of(instance.test_method) == 
-                      "foo_before bar_before base_method bar_after foo_after"
-    end
-
-    result_of(instance.test_method) == 
-                      "bar_before foo_before base_method foo_after bar_after"
-  end
-end
-
-
-# Multiple modules per layer and class
-# ====================================
-
-# It is also possible to have more than one module define the context-dependent
-# behaviour of a class. In this case it may also happen, that multiple modules
-# extend the same method definition.
-#
-# In this case we can reuse or already defined class and modules. This time
-# we include them into the same layer and see what happens.
-
-class OrderingTest
-  include FooMethods => :foo_bar
-  include BarMethods => :foo_bar
-end
-
-example do
-  instance = OrderingTest.new
-  result_of(instance.test_method) == "base_method"
-
-  ContextR::with_layer :foo_bar do
-    result_of(instance.test_method) == 
-                      "bar_before foo_before base_method foo_after bar_after"
-  end
-end
-
-# This time the last inclusion defines the outermost method. This can be again
-# changed. After repeating an inclusion the ordering is updated.
-
-example do
-  class OrderingTest
-    include FooMethods => :foo_bar
-  end
-
-  instance = OrderingTest.new
-  result_of(instance.test_method) == "base_method"
-
-  ContextR::with_layer :foo_bar do
-    result_of(instance.test_method) == 
-                      "foo_before bar_before base_method bar_after foo_after"
-  end
-end
-
-# These should be all case where ordering matters. If you are aware of the
-# two basic rules, everything should work as expected. In an ideal world the
-# the execution order would not be important. But hey, this is not the ideal
-# world, so you better know.
+LiterateMarukuTest.load(__FILE__)