contextr 0.1.1 → 0.1.9

data/test/test_dynamics.rb

@@ -1,207 +1,4 @@
 require File.dirname(__FILE__) + "/test_helper.rb"
 
 test_class(:TestDynamics)
-
-# 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
-  module GermanSequence
-    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
-
-  include GermanSequence => :german
-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
-    module GermanSequence
-      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
-    module GermanSequence
-      # 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.
+LiterateMarukuTest.load(__FILE__)

data/test/test_hello_world.mkd

@@ -0,0 +1,70 @@
+Hello World for ContextR
+
+    example do
+      class MyApplication
+        def greet
+          "Hello, World"
+        end
+      end
+
+      app = MyApplication.new
+      assert_equal "Hello, World", app.greet
+    end
+
+And what about request coming from down under? Let's introduce Localization.
+
+    example do
+      class MyApplication
+        in_layer :au do
+          def greet
+            "G'day, mate"
+          end
+        end
+      end
+
+      app = MyApplication.new
+
+      assert_equal "Hello, World", app.greet
+
+      ContextR::with_layer :au do
+        assert_equal "G'day, mate", app.greet
+      end
+    end
+
+And what if down under changed its habbits? Let's redefine it.
+
+    example do
+      class MyApplication
+        in_layer :au do
+          def greet
+            yield(:next) + " and God Save the Queen"
+          end
+        end
+      end
+
+      app = MyApplication.new
+
+      assert_equal "Hello, World", app.greet
+
+      ContextR::with_layer :au do
+        assert_equal "Hello, World and God Save the Queen", app.greet
+      end
+    end
+
+The key here is, that the method `greet` method in the `:au` layer is redefined
+and no new method is added.
+
+    example do
+      class MyApplication
+        in_layer :au do
+          $inner_module_1 = self
+        end
+      end
+      class MyApplication
+        in_layer :au do
+          $inner_module_2 = self
+        end
+      end
+
+      assert(($inner_module_1 == $inner_module_2), "Modules should be equal")
+    end

data/test/test_hello_world.rb

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

data/test/test_helper.rb

@@ -1,57 +1,8 @@
+require 'rubygems'
 require 'test/unit'
-require File.dirname(__FILE__) + '/../lib/contextr'
-
-unless Object.const_defined?("ExampleTest")
-  module ExampleTest
-    module ObjectExtension
-      def test_class(name)
-        $latest_test_class = Class.new(Test::Unit::TestCase)
-        $latest_test_case  = 0
-        Object.const_set(name, $latest_test_class) 
-      end
-
-      def example(&block)
-        $latest_test_class.class_eval do
-          define_method("test_%03d" % ($latest_test_case += 1), &block)
-        end
-      end
-    end
-    
-    module TestExtension
-      def assert_to_s(expected, actual)
-        assert_equal(expected, actual.to_s)
-      end
 
-      def result_of(object)
-        Result.new(object, self)
-      end
-
-      def output_of(object)
-        Output.new(object, self)
-      end
-
-      class Result 
-        attr_accessor :object, :test_class
-        def initialize(object, test_class)
-          self.object = object
-          self.test_class = test_class 
-        end
-        def ==(string)
-          test_class.assert_equal(string, object)
-        end
-      end
-      class Output < Result
-        def ==(string)
-          test_class.assert_equal(string, object.to_s)
-        end
-      end
-    end
-  end
+require File.dirname(__FILE__) + '/../lib/contextr'
 
-  class Test::Unit::TestCase
-    include ExampleTest::TestExtension
-  end
-  class Object 
-    include ExampleTest::ObjectExtension
-  end
+%w{example literate_maruku}.each do |lib|
+  require File.dirname(__FILE__) + "/lib/#{lib}_test"
 end

data/test/test_introduction.mkd

@@ -0,0 +1,325 @@
+Let's build a simple student's 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 
+all getters, setters and an easy constructor setting all the instance 
+variables.
+
+**Note**: In order to get a nice output in our program we override the #to\_s 
+method which is used in many cases by ruby, e.g. in Kernel#puts or in String 
+interpolation.
+
+In most of the cases, the name is sufficient to represent each entity, i.e.
+a student or a university.
+
+    class University < Struct.new(:name, :address)
+      def to_s
+        name
+      end
+    end
+
+    class Student < Struct.new(:name, :address, :university)
+      def to_s
+        name
+      end
+    end
+
+Under certain circumstances we would like to have a more verbose output.
+This could mean print the university a student belongs to or attach the
+address to the output.
+
+Additonal methods
+-----------------
+
+In a plain old Ruby project, this would result in additional methods, 
+probably encapsulated in modules, that will be included into our classes. 
+This allows reuse and better encapsulation.
+
+    module AddressOutput
+      def to_s_with_address
+        "#{self} (#{self.address})"
+      end
+    end
+
+    class University
+      include AddressOutput
+    end
+
+Now each university got a to\_s\_with\_address method that could be called 
+instead of to\_s if you would like to have additional information.
+
+    class Student
+      include AddressOutput
+
+      def to_s_with_university
+        "#{self}; #{self.unversity}"
+      end
+      def to_s_with_university_and_address
+        "#{self.to_s_with_address}; #{self.unversity.to_s_with_address}"
+      end
+    end
+
+The same for each student. #to\_s\_with\_unversity
+and #to\_s\_with\_university\_and\_address give as well additional output.
+
+So how can you use it. Let's create some instances first.
+
+    $hpi = University.new("HPI", "Potsdam")
+    $gregor = Student.new("Gregor", "Berlin", $hpi)
+
+An now some output. 
+
+**Note**: This could live inside an erb template, a graphical user 
+interface or printed to the command line. In all these cases to\_s is called 
+automatically by the standard library to receive a good representation of 
+the object.       
+The output method defined in test\_helper.rb simulates this behaviour. All
+examples are converted to test class automatically, so we can be sure, that
+this document stays in sync with the library.
+
+   puts $gregor   # => prints "Gregor"
+   "#{$gregor}"   # => evaluates to "Gregor"
+   <%= $gregor %>   => as well as this
+{:execute=false}
+
+    output_of($gregor) == "Gregor"
+    output_of($hpi) == "HPI"
+{:execute=false}
+
+Assume, we would like to print an address list now.
+
+    example do
+      output_of($gregor.to_s_with_address) == "Gregor (Berlin)"
+    end
+
+If you want a list with university and addresses, you would 
+use #to\_s\_with\_university\_and\_address. No automatic call to to\_s anymore.
+If you have your layout in an erb template, you have to change each and every 
+occurrence of your variables.
+
+
+Redefining to\_s
+---------------
+
+To solve this problem you could redefine to\_s on demand. I will demonstrate
+this with some meta programming in a fresh class.
+
+    module GenericToS
+      def to_s
+        self.class.included_vars.collect do |var|
+          self.send(var)
+        end.join("; ")
+      end
+
+
+      module ClassMethods
+        attr_accessor :included_vars
+        def set_to_s(*included_vars)
+          self.included_vars = included_vars
+        end
+      end
+
+      def self.included(base_class)
+        base_class.send(:extend, ClassMethods)
+      end
+    end
+
+    class Company < Struct.new(:name, :address)
+      include GenericToS
+    end
+
+    class Employee < Struct.new(:name, :address, :company)
+      include GenericToS
+    end
+
+I will not go into detail how this code works, but I will show you how to 
+use it. Let's get some instances first.
+
+    $ms = Company.new("Microsoft", "Redmond")
+    $bill = Employee.new("Bill", "Redmond", $ms)
+
+And now use these instances.
+
+    example do
+      Company.set_to_s(:name)
+      Employee.set_to_s(:name)
+
+      output_of($ms) == "Microsoft"
+      output_of($bill) == "Bill"
+    end
+
+Let's get the output including the addresses
+
+    example do
+      Employee.set_to_s(:name, :address)
+
+      output_of($bill) == "Bill; Redmond"
+    end
+
+And including the employer
+
+    example do
+      Employee.set_to_s(:name, :address, :company)
+
+      output_of($bill) == "Bill; Redmond; Microsoft"
+    end
+
+But hey. I wanted to have a list with all addresses, not just the 
+employee's. This should be an address list, right? But we did not tell 
+the Company class to print the address, but just the Employee class.
+
+So in our first approach, we had to change each place, where we use the
+object. In the second approach we have to know all places where an address
+is stored and apply the changes in there.
+
+By the way, what happens, if I was using a multi-threaded application and
+one user request a simple name list, and the other switches to an address 
+list in the meantime. Then the output will be mixed - with and without 
+addresses. This is not exactly what we want. So there has to be an easier, 
+thread safe solution.
+
+
+ContextR
+--------
+
+This is were context-oriented programming comes into play. I will again 
+start from the scratch. It is not much and we all know the problem space 
+now.
+
+The same setup, just another setting. First the basic implementation, just 
+like we did it in our first approach.
+
+    class Religion < Struct.new(:name, :origin)
+      def to_s
+        name
+      end
+    end
+    class Believer < Struct.new(:name, :origin, :religion)
+      def to_s
+        name
+      end
+    end
+
+Now define the additional behaviour in separate modules. Please don't be 
+scared because of the strange syntax and method calls.
+yield(:receiver) refers to the "normal" self when these modules are 
+included.
+
+Future versions of ContextR will hopefully provide a nicer syntax here.
+
+Finally we need to link our additional behaviour to our basic classes.
+We also need to tell the framework, when this behaviour should be applied.
+
+    module OriginMethods
+      def to_s
+        "#{super} (#{yield(:receiver).origin})"
+      end
+    end
+
+    class Religion
+      in_layer :location do
+        include OriginMethods
+      end
+    end
+    class Believer
+      in_layer :location do
+        include OriginMethods
+      end
+      in_layer :believe do
+        def to_s
+          "#{super}; #{yield(:receiver).religion}"
+        end
+      end
+    end
+
+The additional context dependent behaviour is organised within layers. A 
+single layer may span multiple classes - in this case the location layer 
+does. To enable the additional code, the programmes shall activate layers.
+A layer activation is only effective within a block scope and within the 
+current thread.
+
+Let's see, how it looks like when we use it.
+
+    $christianity = Religion.new("Christianity", "Israel")
+    $the_pope = Believer.new("Benedikt XVI", "Bavaria", $christianity)
+
+    example do
+      output_of($christianity) == "Christianity"
+      output_of($the_pope) == "Benedikt XVI"
+    end
+
+Would like to have an address? For this we have to activate the location 
+layer. Now the additional behaviour defined within the layer, will be 
+executed around the base method defined within the class.
+
+    example do
+      ContextR.with_layer :location do 
+        output_of($christianity) == "Christianity (Israel)"
+        output_of($the_pope) == "Benedikt XVI (Bavaria)"
+      end
+    end
+
+
+Of course the additional behaviour is deactivated automatically after the
+blocks execution.
+
+    example do
+      output_of($christianity) == "Christianity"
+      output_of($the_pope) == "Benedikt XVI"
+    end
+
+Everything back to normal.
+
+Lets activate the believe layer:
+
+    example do
+      ContextR.with_layer :believe do 
+        output_of($the_pope) == "Benedikt XVI; Christianity"
+      end
+    end
+
+Now we need both, location and believe. How does it look like? You have to
+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 
+        output_of($the_pope) == "Benedikt XVI (Bavaria); Christianity (Israel)"
+      end
+    end
+
+As you can see, the activation of the location layer is operative in the
+whole execution context of the block. Each religion prints its origin, 
+whether to\_s was called directly or indirectly.
+
+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
+          output_of($the_pope) == 
+                              "Benedikt XVI (Bavaria); Christianity (Israel)"
+
+          ContextR.without_layer :believe do 
+            output_of($the_pope) == "Benedikt XVI (Bavaria)"
+          end
+
+          output_of($the_pope) == 
+                              "Benedikt XVI (Bavaria); Christianity (Israel)"
+        end
+      end
+    end
+
+    example do
+      assert_equal(["to_s"], Religion.in_layer(:location).instance_methods)
+    end
+
+These encapsulations may be as complex as your application. ContextR will
+keep track of all activations and deactivations within the blocks and
+restore the settings after the block was executed.
+
+This was just a short introduction on a problem case, that can be solved
+with context-oriented programming. You have seen, the advantages and how
+to use it. In other files in this folder, you can learn more on the 
+dynamics and meta programming interfaces of ContextR.