contextr 0.1.9 → 1.0.0

data/test/{test_dynamic_scope.mkd → dynamic_scope.mkd}

@@ -29,11 +29,11 @@ the rest is support code.
       one_block = lambda do
         mutex.lock
         ContextR::with_layer :b do
-          step(3, :a, :b)
+          step(3, :b, :a)
           mutex.unlock
           sleep(0.1)
           mutex.lock
-          step(5, :a, :b)
+          step(5, :b, :a)
         end
       end
 

data/test/{test_dynamics.mkd → dynamics.mkd}

@@ -79,10 +79,10 @@ should both return true, when the :red_and_yellow state is active.
         end
 
         def red
-          (yield(:receiver).current == :red_and_yellow) or yield(:next)
+          (yield(:receiver).current == :red_and_yellow) or super 
         end
         def yellow 
-          (yield(:receiver).current == :red_and_yellow) or yield(:next)
+          (yield(:receiver).current == :red_and_yellow) or super 
         end
       end
     end
@@ -151,7 +151,7 @@ traffic light.
             if yield(:receiver).current == :red_and_yellow
               "It's red and yellow at once. It will be green soon."
             else
-              yield(:next)
+              super 
             end
           end
         end

data/test/{test_hello_world.mkd → hello_world.mkd}

@@ -37,7 +37,7 @@ And what if down under changed its habbits? Let's redefine it.
       class MyApplication
         in_layer :au do
           def greet
-            yield(:next) + " and God Save the Queen"
+            super + " and God Save the Queen"
           end
         end
       end

data/test/{test_introduction.mkd → introduction.mkd}

@@ -1,4 +1,4 @@
-Let's build a simple student's database. Each University has a name and 
+Let's build a simple students database. Each University has a name and 
 address. Each student has a name, address and an associated university.
 
 We are using a `Struct` to build our classes in an easy way. This provides 
@@ -283,7 +283,7 @@ options. You may activate the two one after the other or all at once. It
 is just a matter of taste, the result remains the same.
 
     example do
-      ContextR.with_layer :believe, :location do 
+      ContextR.with_layer :location, :believe do 
         output_of($the_pope) == "Benedikt XVI (Bavaria); Christianity (Israel)"
       end
     end
@@ -296,8 +296,8 @@ If you change your mind within your call stack, you may of course
 deactivate layers again.
 
     example do
-      ContextR.with_layer :believe do 
-        ContextR::with_layer :location do
+      ContextR::with_layer :location do
+        ContextR.with_layer :believe do 
           output_of($the_pope) == 
                               "Benedikt XVI (Bavaria); Christianity (Israel)"
 

data/test/{test_layer_state.mkd → layer_state.mkd}

@@ -87,7 +87,7 @@ our variable.
           end
 
           def compute(fixnum)
-            cache[fixnum] ||= yield(:next, fixnum)
+            cache[fixnum] ||= super 
           end
         end
       end
@@ -101,7 +101,7 @@ Now let's compute Fib(100) again. Of course with caching enabled
     example do
       timeout_raised = false
       begin
-        Timeout::timeout(0.05) do
+        Timeout::timeout(0.1) do
           ContextR::with_layer :cache do
             result_of(Fibonacci.compute(100)) == 354_224_848_179_261_915_075
           end

data/test/lib/example_test.rb

@@ -12,11 +12,11 @@ module ExampleTest
       Object.const_set(name, ExampleTest::latest_test_class) 
     end
 
-    def example(&block)
+    def example(version = RUBY_VERSION, &block)
       ExampleTest::latest_test_class.class_eval do
         define_method("test_%03d" % (ExampleTest::latest_test_case += 1), 
                       &block)
-      end
+      end if RUBY_VERSION =~ Regexp.new(version.to_s)
     end
   end
   

data/test/lib/literate_maruku_test.rb

@@ -1,6 +1,7 @@
 gem "literate_maruku"
 require "literate_maruku"
 require 'markaby'
+require 'maruku'
 require 'active_support'
 
 class Fixnum
@@ -9,10 +10,10 @@ class Fixnum
     return 'th' if (10..19).include?(self % 100)
     # others
     case self % 10
-    when 1: return 'st'
-    when 2: return 'nd'
-    when 3: return 'rd'
-    else    return 'th'
+    when 1 then return 'st'
+    when 2 then return 'nd'
+    when 3 then return 'rd'
+    else        return 'th'
     end
   end
 end
@@ -27,16 +28,16 @@ module LiterateMarukuTest
   BASE_DIR = File.dirname(__FILE__) + "/../"
   TARGET_DIR = File.dirname(__FILE__) + "/../../website/test/"
 
-  def self.load(file)
+  def self.load(test)
     content = LiterateMaruku.require(
-                               BASE_DIR + "#{File.basename(file, '.rb')}.mkd", 
+                               BASE_DIR + "#{test}.mkd", 
                                :inline => true,
                                :attributes => {:execute => true})
 
     download = "http://rubyforge.org/projects/contextr"
     version = ContextR::VERSION::STRING 
     modified = Time.now 
-    sub_title = File.basename(file, '.rb').gsub("test_", "").titleize
+    sub_title = test.titleize
     
     doc = Markaby::Builder.new.xhtml_strict do
       head do
@@ -77,7 +78,7 @@ module LiterateMarukuTest
           end
 
           ul.navi! do
-            Dir[File.dirname(file) + "/test_*.mkd"].each do |mkd_file_name|
+            Dir[File.dirname(__FILE__) + "/../*.mkd"].each do |mkd_file_name|
               li do
                 name = File.basename(mkd_file_name, ".mkd").gsub("test_", "")
                 a name.titleize, :href => name + ".html" 
@@ -95,8 +96,9 @@ module LiterateMarukuTest
         end
       end
     end
+    Dir.mkdir(TARGET_DIR) unless File.exist?(TARGET_DIR)
     File.open(TARGET_DIR + 
-            "#{File.basename(file, '.rb').gsub("test_", "")}.html", "w") do |f|
+            "#{test}.html", "w") do |f|
       f.puts(%q{<!DOCTYPE html
           PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">})

data/test/{test_meta_api.mkd → meta_api.mkd}

@@ -5,7 +5,7 @@ active layers.
       ContextR::with_layer :a do
         assert_equal([:a], ContextR::active_layers)
         ContextR::with_layer :b do
-          assert_equal([:a, :b], ContextR::active_layers)
+          assert_equal([:b, :a], ContextR::active_layers)
         end
         assert_equal([:a], ContextR::active_layers)
       end

data/test/method_missing.mkd

@@ -0,0 +1,40 @@
+It is used in ContextR as well, and its
+redefinition is simple, The functionality of method missing is 
+one of the core ingredients of cleanly designed Ruby programs, it is still 
+possible to extend it with context-dependent behaviour.
+
+The following code will show the right usage.
+
+    class MethodMissingExample
+      def method_missing(*a)
+        "base"
+      end
+
+      in_layer :one do
+        def method_missing(*a, &b)
+          "pre_one " + super
+        end
+      end
+      in_layer :two do
+        def method_missing(*a, &b)
+          super + " post_two"
+        end
+      end
+    end
+
+    example do
+      instance = MethodMissingExample.new
+      result_of(instance.any_method) == "base"
+
+      ContextR::with_layer :one do
+        result_of(instance.any_method) == "pre_one base"
+      end
+      ContextR::with_layer :two do
+        result_of(instance.any_method) == "base post_two"
+      end
+
+      ContextR::with_layer :one, :two do
+        result_of(instance.any_method) == "pre_one base post_two"
+      end
+    end
+

data/test/{test_ordering.mkd → ordering.mkd}

@@ -50,25 +50,25 @@ determines the order of execution.
         result_of(instance.test_method) == "bar_before base_method bar_after"
       end
 
-      ContextR::with_layer :bar, :foo do
+      ContextR::with_layer :foo, :bar 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
+      ContextR::with_layer :foo do
+        ContextR::with_layer :bar do
           result_of(instance.test_method) == 
                         "bar_before foo_before base_method foo_after bar_after"
         end
       end
 
-      ContextR::with_layer :foo, :bar do
+      ContextR::with_layer :bar, :foo 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
+      ContextR::with_layer :bar do
+        ContextR::with_layer :foo do
           result_of(instance.test_method) == 
                         "foo_before bar_before base_method bar_after foo_after"
         end
@@ -85,11 +85,11 @@ activation is hidden, but is restored again after leaving the block.
     example do
       instance = OrderingTest.new
 
-      ContextR::with_layer :bar, :foo do
+      ContextR::with_layer :foo, :bar do
         result_of(instance.test_method) == 
                         "bar_before foo_before base_method foo_after bar_after"
 
-        ContextR::with_layer :bar do
+        ContextR::with_layer :foo do
           result_of(instance.test_method) == 
                         "foo_before bar_before base_method bar_after foo_after"
         end

data/test/restrictions.mkd

@@ -0,0 +1,177 @@
+There are certain cases (i.e. Classes and Methods), that may not be extended
+with ContextR. These are e.g. some methods in Enumberable, Array and Hash, 
+that are used internally in ContextR. Extending them would simply result in 
+endless stacks.
+
+In custom classes, i.e. classes defined by your code, every method may be 
+extended. There are only 3 exceptions.
+
+First the exceptions. You may never extend
+
+* `__id__`
+* `__send__`
+* `__clone__`
+
+They shall not be redefined, that is why it triggers a warning. ContextR sticks
+to this convention, that's why it does not support `__id__` and `__clone__`. It
+uses it internally, that's why it does not support `__send__`.
+
+Accessing `self`
+----------------
+
+Then there are other problems, related to the way ContextR is implemented and
+its archetecture is designed. The additional context-dependent behaviour does 
+not reside in the extended object itself but in the corresponding layer, or to
+be exact, in an anonymous module, that is constructed for each 
+layer-class-combination. This results in different `self`s for base code and
+layer code. This is in fact not by intention but by accident.
+
+In order to access the original `self`, the one defined by the object, the 
+message was sent to, there is a workaround. Since we did not want to change
+the method signature, the receiver is avaible in a block, that is passed to
+each layer method. `yield(:receiver)` gives you a pointer to it. Please be 
+aware, that you will be able to access public methods only. Everything else 
+could be easily implemented using `instance_eval`, although this has some 
+performance implications.
+
+If you would like to see `yield(:receiver)` in action, have a look at the other
+examples, e.g. the buttom of the Introduction.
+
+Passing Blocks
+--------------
+
+As already mentioned, ContextR uses a block to pass parameters to each layered
+method. This implies, that methods, expecting a block, cannot easily access it.
+
+But this is only partially true. Every method in a layered stack may access it
+simply by calling `yield(:block)` or execute it with `yield(:block!)`. Of 
+course, you should test, if a block was given with `yield(:block_given?)`. It 
+is also possible to pass a new block to subsequent calls, but that is not to 
+easy, since it is not possible to pass a block as argument to a block. But 
+again, there is a slightly ugly workaround.
+
+All this may be observed in the following artificial example.
+
+    class TheMagi
+      include Enumerable
+
+      def casper; "Casper"; end
+      def melchior; "Melchior"; end
+      def balthasar; "Balthasar"; end
+
+      def name_methods
+        %w(casper melchior balthasar)
+      end
+
+      def each
+        if block_given?
+          name_methods.each do |name|
+            yield self.send(name)
+          end
+        else
+          raise ArgumentError, "No block given"
+        end
+      end
+    end
+
+    example do
+      the_magi = TheMagi.new
+      names = the_magi.inject do |akku, element|
+        akku.to_s + " " + element.to_s 
+      end
+
+      result_of(names) == "Casper Melchior Balthasar"
+    end
+
+Okay, now we got a working `TheMagi` class, providing an Array-like interface.
+Let's assume, we need HTML-output under certain circumstances. I know this
+example is not to useful, but I needed anything to explain some things.
+
+    class TheMagi
+      in_layer :html_output do
+        def each
+          if yield(:block_given?)
+            yield(:receiver).name_methods.each do |name|
+              king = yield(:receiver).send(name)
+              yield(:block!, "<strong>#{king}</strong>")
+            end
+          else
+            raise ArgumentError, "No block given"
+          end
+        end
+      end
+    end
+
+    example do
+      the_magi = TheMagi.new
+      ContextR::with_layer :html_output do
+        names = the_magi.inject do |akku, element|
+          akku.to_s + " " + element.to_s 
+        end
+
+        result_of(names) == "<strong>Casper</strong> " +
+                            "<strong>Melchior</strong> " +
+                            "<strong>Balthasar</strong>"
+      end
+    end
+
+So this is how you would use a block, that is provided by a user of your method.
+But you may as well change the block, that will be passed to subsequent layers
+including the base method.
+
+The `each` in the `:html_output` layer could as well be implemented in another
+way. I will name it `:xml_output` lacking a better name. I'm sorry, that this
+looks so ugly. I would be happy, if I would know a nicer way.
+
+    class TheMagi
+      in_layer :xml_output do
+        def each
+          old_block = yield(:block)
+
+          new_block = lambda do |element|
+            old_block.call("<name>" + element + "</name>")
+          end
+
+          yield(:block=, new_block)
+
+          return_value = super
+
+          yield(:block=, old_block)
+
+          return_value
+        end
+      end
+    end
+ 
+In the first step, we store the original block in a local variable. Afterwards,
+we create the block, i.e. a lambda, that should replace the old block. We
+may easily access the old one, since we stored it beforehand. This local 
+variable will still be available, when the block is executed.
+
+In the next step, the `new_block` is registered as parameter for subsequent 
+methods. Then we may call super to pass the control flow to the next layer and
+the base method. Finally we should restore the old block, since layers, that
+were execute before, will get control again, after this execution is finished 
+and they might be confused, that the block changed by calling super. This would
+break the call stack behaviour.
+
+Finally, we need to store the return value and give it back explicitly, 
+otherwise the block would be the result.
+
+If in future, this functionality is more often used, I may think about a way
+to make this easier. For now, this is the way to go. Sorry.
+
+Oh. Let's use the code and test its output:
+
+    example do
+      the_magi = TheMagi.new
+      ContextR::with_layer :xml_output do
+        names = the_magi.inject do |akku, element|
+          akku.to_s + " " + element.to_s 
+        end
+
+        result_of(names) == "<name>Casper</name> " +
+                            "<name>Melchior</name> " +
+                            "<name>Balthasar</name>"
+      end
+    end

data/test/test_contextr.rb

@@ -5,3 +5,10 @@
 # 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"
+
+%w(class_side dynamic_scope dynamics hello_world introduction
+   layer_state meta_api method_missing ordering restrictions).each do |test|
+  test_class("test_#{test}".camelcase.to_sym)
+  LiterateMarukuTest.load(test)
+end