contextr 0.1.0 → 0.1.1

data/test/test_contextr.rb

@@ -1,11 +1,19 @@
-require File.dirname(__FILE__) + '/test_helper.rb'
-
-class TestContextR < Test::Unit::TestCase
-
-  def setup
-  end
-  
-  def test_truth
-    assert true
-  end
-end
+# ContextR uses RSpec to test its implementation. For the relevant code
+# have a look at the spec folder.
+#
+# Additionally ContextR has lots of descriptive manuals that are automatically
+# 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_dynamics.rb

@@ -0,0 +1,207 @@
+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.

data/test/test_helper.rb

@@ -1,2 +1,57 @@
 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
+
+  class Test::Unit::TestCase
+    include ExampleTest::TestExtension
+  end
+  class Object 
+    include ExampleTest::ObjectExtension
+  end
+end

data/test/test_introduction.rb

@@ -0,0 +1,311 @@
+require File.dirname(__FILE__) + "/test_helper.rb"
+
+test_class(:TestIntroduction)
+
+# 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.
+#
+# 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, propably
+# 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. This could live inside an erb template, a graphical ui or
+# printed to the command line. In all these cases to_s is called automatically
+# by the standard libary 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 libary.
+# 
+# puts gregor   # => prints "Gregor"
+# "#{gregor}"   # => evaluates to "Gregor"
+# <%= gregor %>   => as well as this
+
+example do
+  output_of($gregor) == "Gregor"
+  output_of($hpi) == "HPI"
+end
+
+# 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 to 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 useing 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
+# yield(:next) is much like a super call.
+#
+# Future versions of ContextR will hopefully provide a nicer syntax here.
+module OriginMethods
+  def to_s
+    "#{yield(:next)} (#{yield(:receiver).origin})"
+  end
+end
+module ReligionMethods
+  def to_s
+    "#{yield(:next)}; #{yield(:receiver).religion}"
+  end
+end
+
+# 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.
+class Religion
+  include OriginMethods => :location
+end
+class Believer
+  include OriginMethods => :location
+  include ReligionMethods => :believe
+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, wheter
+# 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
+
+# These encaspulations 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