contextr 0.1.1 → 0.1.9

data/test/test_introduction.rb

@@ -1,311 +1,4 @@
 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
+LiterateMarukuTest.load(__FILE__)

data/test/test_layer_state.mkd

@@ -0,0 +1,170 @@
+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
+        in_layer :cache do
+          def cache
+            @cache ||= {}
+          end
+
+          def compute(fixnum)
+            cache[fixnum] ||= yield(:next, fixnum)
+          end
+        end
+      end
+    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
+      in_layer :test_layer_state do
+        attr_accessor :state
+      end
+    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.