contextr 0.1.1 → 0.1.9

data/test/test_class_side.rb

@@ -1,225 +1,4 @@
 require File.dirname(__FILE__) + "/test_helper.rb"
 
 test_class(:TestClassSide)
-
-# In Ruby there are multiple ways of defining behaviour on the class side. That
-# are messages that are send to the class, not on the instance. Class side 
-# behaviour is often useful for functional methods, i.e. methods that do not
-# rely on inner state and have no side effects. Mathematical functions have 
-# these characteristics - that is where the name probably comes from.
-
-
-# Using def self.method_name
-# ==========================
-
-# The simpliest way of defining class side behaviour is prepending self. to the
-# method definition. This way, the method is attached to the surrounding class 
-# and not instance. A simple example:
-
-class SimpleMath
-  def self.pi
-    3.14159265
-  end
-end
-
-example do
-  result_of(SimpleMath.pi) == 3.14159265
-end
-
-
-# Using class << self
-# ===================
-
-# When you are having lots of class side methods as well as instance side ones,
-# it can be difficult to spot the little self. in front of the method name.
-# Probably you like to group them more explicitly. You could use Ruby's
-# eigenclass principle for that. It will look like the following:
-
-class SimpleMath
-  class << self
-    def e
-      2.71828183
-    end
-  end
-end
-
-example do
-  result_of(SimpleMath.e) == 2.71828183 
-end
-
-
-# Using a module
-# ==============
-
-# For even more encapsulation you could also use modules and extend the class 
-# definition with them. I am using extend here on purpose. Module's include
-# method adds the behaviour to the instance side, extend to the class side.
-
-class SimpleMath
-  module ClassMethods
-    def golden_ratio
-      1.6180339887
-    end
-  end
-
-  extend ClassMethods
-end
-
-example do
-  result_of(SimpleMath.golden_ratio) == 1.6180339887 
-end
-
-# The last method is e.g. often used in the web framework Ruby on Rails. Often
-# a variation of it is used to define class and instance side behaviour for
-# mixin modules
-
-module MathMixin
-  def counter
-    @counter ||= 0
-    @counter += 1
-  end
-
-  module ClassMethods
-    def sqrt(x)
-      x ** 0.5
-    end
-  end
-
-  def self.included(base)
-    base.send(:extend, ClassMethods)
-  end
-end
-
-class SimpleMath
-  include MathMixin
-end
-
-example do
-  result_of(SimpleMath.sqrt(4)) == 2
-
-  my_simple_math = SimpleMath.new
-  result_of(my_simple_math.counter) == 1
-  result_of(my_simple_math.counter) == 2
-end
-
-# This is regarded as the most elegant way of defining class and instance 
-# methods for a mixin module. And the basic functionality is the same as in the
-# previous example.
-
-# After we now know how to define class side behaviour, everybody is curious
-# to know how to extend this behaviour using context-oriented programming and
-# ContextR.
-#
-# Additionial, context-dependent behaviour is defined in modules. These modules
-# are then attached to the class with a selector representing the layer, in
-# which the behaviour should reside. For examples on the instance side
-# have a look at the bottom of test_introduction.
-#
-# Let's how we can achieve the same on the class side for each of the different
-# methods of defining class side behaviour.
-
-
-# Using def self.method_name
-# ==========================
-
-# Okay, we won't get rid of the modules, used to encapsulate the 
-# context-dependent behaviour, so the extension is a bit noisier, than the 
-# basic notation.
-
-class SimpleMath
-  module AccessControlMethods
-    def pi
-      "You are not allowed to access this method"
-    end
-  end
-
-  extend AccessControlMethods => :access_control
-end
-
-# But we can use the same principles, like we did for the instance side. Simply
-# use a hash to tell extend, that the module should only be used in a certain
-# layer.
-
-example do
-  result_of(SimpleMath.pi) == 3.14159265
-
-  ContextR::with_layer :access_control do
-    result_of(SimpleMath.pi) == "You are not allowed to access this method" 
-  end
-end
-
-
-# Using class << self
-# ===================
-
-# When your using the eigenclass, you are able to use to good old include to
-# manage the extension. But nobody stops you if you fell in love with extend.
-
-class SimpleMath
-  class << self
-    module EnglishMethods
-      def e
-        "Euler's constant"
-      end
-    end
-    include EnglishMethods => :english
-  end
-
-  module GermanMethods
-    def e
-      "Eulersche Zahl"
-    end
-  end
-  extend GermanMethods => :german
-end
-
-example do
-  result_of(SimpleMath.e) == 2.71828183 
-
-  ContextR::with_layer :german do
-    result_of(SimpleMath.e) == "Eulersche Zahl" 
-  end
-  ContextR::with_layer :english do
-    result_of(SimpleMath.e) == "Euler's constant" 
-  end
-end
-
-
-# Using a module
-# ==============
-
-# Hey, this is what we did all the time, so it is only natural to have the same
-# syntax to extend a class using in module for context-dependent behaviour. But
-# for the sake of completeness, I will attach another example.
-
-class SimpleMath
-  module ExactComputationMethods
-    def golden_ratio
-      sleep(0.01) # In real life this would take a bit longer, 
-                  # but I don't have the time.
-      1.6180339887_4989484820_4586834365_6381177203_0917980576 
-    end
-  end
-
-  extend ExactComputationMethods => :exact_computation
-end
-
-example do
-  result_of(SimpleMath.golden_ratio) == 1.6180339887
-
-  ContextR::with_layer :exact_computation do
-    result_of(SimpleMath.golden_ratio) == 
-                      1.6180339887_4989484820_4586834365_6381177203_0917980576 
-  end
-end
-
-
-# Conclusion
-# ==========
-
-# In general, there are two options to define context-dependent class side
-# behaviour. Use include in the eigenclass or use extend anywhere else. Both
-# options result in the same behaviour, just like the different options in 
-# plain ruby look different, but have the same effect.
-#
-# The programmer is free to use, whatever suites best. This is still Ruby.
+LiterateMarukuTest.load(__FILE__)

data/test/test_contextr.rb

@@ -5,15 +5,3 @@
 # converted to tests, to make sure, that all documentation is in sync with
 # the implementation. You may find these documents in this directory. It is
 # just, that they do not look like test, but they are. Believe me.
-#
-# require File.dirname(__FILE__) + '/test_helper.rb'
-# 
-# class TestContextR < Test::Unit::TestCase
-# 
-#   def setup
-#   end
-#   
-#   def test_truth
-#     assert true
-#   end
-# end

data/test/test_dynamic_scope.mkd

@@ -0,0 +1,61 @@
+This explanation is a bit tricky. First of all thread programming is always 
+tricky and then, testing threads to gain repeatable results makes it even less 
+readable.
+
+I tried to improve it by defining a little helper method called `step`. It shall
+test if all chunks are executed in the expected order and additionally check
+if the expected layers are activated. 
+
+
+Layer activation shall be dynamically scoped. This is basically no problem, but
+it gets messy when doing thread programming and switching between scopes. The
+ugly part is done by Christian Neukirchen's dynamic.rb library.
+
+The following example does not demonstrate anything useful. It is just a more or
+less readable test. Follow the `step`s, if you want to get the execution order.
+As you may see, leaving the inner block in step 5 results in the "lost" layer 
+`:b` and it is "restored" in step 6. This is the base line of this test. All 
+the rest is support code.
+
+    example do
+      def step(index, *layers)
+        @step ||= 0
+        assert_equal(index, @step += 1) if index
+        assert_equal(layers, ContextR::active_layers)
+      end
+
+      mutex = Mutex.new
+
+      one_block = lambda do
+        mutex.lock
+        ContextR::with_layer :b do
+          step(3, :a, :b)
+          mutex.unlock
+          sleep(0.1)
+          mutex.lock
+          step(5, :a, :b)
+        end
+      end
+
+      two_block = lambda do
+        mutex.lock
+        step(4, :a)
+        mutex.unlock
+      end
+
+      step(1)
+      ContextR::with_layer :a do
+        step(2, :a)
+
+        one = Thread.new(&one_block) 
+        two = Thread.new(&two_block)
+        
+        step(nil, :a)
+
+        one.join
+        two.join
+
+        step(6, :a)
+      end
+      step(7)
+    end

data/test/test_dynamic_scope.rb

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

data/test/test_dynamics.mkd

@@ -0,0 +1,201 @@
+One of the most powerful features of Ruby is the concept of open classes. At
+everytime, the programmer is able to change class, instances and methods. 
+This has immediate effects on all instances and works like a charm.
+
+One of the goals of ContextR 0.1.0 was to bring this power to the 
+context-oriented abstraction. The following examples will simply demonstrate,
+that it works. Not more, not less.
+
+    class TrafficLight
+      def initialize
+        @state = 0
+      end
+
+      def state_ordering
+        @state_ordering ||= [:red, :yellow, :green, :yellow]
+      end
+
+      def current
+        state_ordering[@state]
+      end
+
+      def next
+        @state += 1
+        @state = 0 if @state >= state_ordering.size
+        current
+      end
+
+      def red
+        current == :red
+      end
+      def yellow 
+        current == :yellow
+      end
+      def green
+        current == :green
+      end
+      
+      def text
+        current.to_s
+      end
+    end
+
+Here we have a simple dutch traffic light. Let's test if it works.
+
+    $traffic_light = TrafficLight.new
+    example do
+      # It is always a good idea, to start with red
+      result_of($traffic_light.red) == true 
+
+      $traffic_light.next
+      result_of($traffic_light.yellow) == true 
+
+      $traffic_light.next
+      result_of($traffic_light.green) == true 
+
+      $traffic_light.next
+      result_of($traffic_light.yellow) == true
+
+      $traffic_light.next
+      result_of($traffic_light.red) == true
+    end
+
+But in Germany the lights work different. The sequence looks like the 
+following
+  red
+  red and yellow
+  green
+  yellow
+  red
+
+Let's build it with in an additional :german layer. All we need to do is
+insert the new state ordering and change the red and yellow methods. They
+should both return true, when the :red_and_yellow state is active.
+
+    class TrafficLight
+      in_layer :german do
+        def state_ordering
+          @state_ordering ||= [:red, :red_and_yellow, :green, :yellow]
+        end
+
+        def red
+          (yield(:receiver).current == :red_and_yellow) or yield(:next)
+        end
+        def yellow 
+          (yield(:receiver).current == :red_and_yellow) or yield(:next)
+        end
+      end
+    end
+
+    example do
+      ContextR::with_layer :german do
+        result_of($traffic_light.red) == true 
+
+        $traffic_light.next
+        result_of($traffic_light.red) == true 
+        result_of($traffic_light.yellow) == true 
+
+        $traffic_light.next
+        result_of($traffic_light.green) == true 
+
+        $traffic_light.next
+        result_of($traffic_light.yellow) == true
+
+        $traffic_light.next
+        result_of($traffic_light.red) == true
+      end
+    end
+
+
+Now we have a traffic light, that is able to work in the Netherlands and in 
+Germany. But this is just the start. This example should show, that both
+method modules and the base implementation may be changed at runtime and
+the changes have immediate effect, just like they do in the basic ruby world.
+
+In this example would like to change the textual representation a bit. I
+think they do not give much information. Let's change extend them. 
+
+    example do
+      result_of($traffic_light.text) == "red"
+      class TrafficLight
+        # When running these test with ruby -w the following line will raise a 
+        # warning, that you are discarding the old method definition. To avoid 
+        # these simply undefine it before defining a new implementation.
+        def text
+          case @state
+          when 0 : "It's red. Stop immediately."
+          when 1 : "It's yellow. Prepare to start. It will be green soon."
+          when 2 : "It's green. Hit it."
+          when 3 : "It's yellow. Attention, it will be red soon. You better stop."
+          end
+        end
+      end
+      result_of($traffic_light.text) == "It's red. Stop immediately."
+    end
+
+Okay this works fine. But we also need to change it in case of the german
+traffic light.
+
+    example do
+      # The old behaviour
+      ContextR::with_layer :german do
+        $traffic_light.next
+        result_of($traffic_light.text) == 
+                        "It's yellow. Prepare to start. It will be green soon."
+      end
+
+      # It's redefinition
+      class TrafficLight
+        in_layer :german do
+          def text
+            if yield(:receiver).current == :red_and_yellow
+              "It's red and yellow at once. It will be green soon."
+            else
+              yield(:next)
+            end
+          end
+        end
+      end
+
+      # The new behaviour
+      ContextR::with_layer :german do
+        result_of($traffic_light.text) == 
+                          "It's red and yellow at once. It will be green soon."
+      end
+    end
+
+One could argue, that we did not actually change the implementation, but just
+added a method. Okay. Then let's change this method and translate the text.
+This is a german traffic light, right?
+
+    example do
+      # The old behaviour
+      ContextR::with_layer :german do
+        result_of($traffic_light.text) == 
+                          "It's red and yellow at once. It will be green soon."
+      end
+
+      class TrafficLight
+        in_layer :german do
+          # When running these test with ruby -w the following line will raise 
+          # a warning, that you are discarding the old method definition. To 
+          # avoid these simply undefine it before defining a new implementation.
+          def text
+            case yield(:receiver).current
+            when :red : "Es ist rot. Anhalten."
+            when :red_and_yellow : "Es ist gelb und rot gleichzeitig."
+            when :green : "Grün. Gib Gas."
+            when :yellow : "Das ist gelb. Gleich ist es rot. Halt lieber an."
+            end
+          end
+        end
+      end
+
+      # The new behaviour
+      ContextR::with_layer :german do
+        result_of($traffic_light.text) == "Es ist gelb und rot gleichzeitig."
+      end
+    end
+
+This was just a simple demonstration, that all the dynamics that are within
+Ruby are still present, when you are using ContextR. No need to worry.