contextr 0.1.0 → 0.1.1

data/test/test_layer_state.rb

@@ -0,0 +1,178 @@
+require File.dirname(__FILE__) + "/test_helper.rb"
+
+test_class(:TestLayerState)
+
+# 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
+    module CacheMethods
+      def cache
+        @cache ||= {}
+      end
+
+      def compute(fixnum)
+        cache[fixnum] ||= yield(:next, fixnum)
+      end
+    end
+  end
+
+  extend ClassMethods::CacheMethods => :cache
+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
+  module StateMethods
+    attr_accessor :state
+  end
+
+  include StateMethods => :test_layer_state
+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.

data/test/test_ordering.rb

@@ -0,0 +1,146 @@
+require File.dirname(__FILE__) + "/test_helper.rb"
+
+test_class(:TestOrdering)
+
+# This document tries to demonstrate the invocation order within 
+# context-specific method calls. There are two cases where this is relevant:
+# 1. There is more than one layer active, that extends the method.
+# 2. There is more than one module in a single layer that extends the method.
+#
+# Unfortunately I could not find any relevant example that clearly demonstrates
+# this behaviour. Therefore I will use foo bar code. But I think it is still
+# easy to get the message.
+
+# 1. Multiple active layers
+# =========================
+
+class OrderingTest
+  def test_method 
+    "base_method"
+  end
+
+  module FooMethods
+    def test_method
+      "foo_before #{yield(:next)} foo_after"
+    end
+  end
+  module BarMethods
+    def test_method
+      "bar_before #{yield(:next)} bar_after"
+    end
+  end
+
+  include FooMethods => :foo
+  include BarMethods => :bar
+end
+
+# When multiple layers extend a single method, the order of activation 
+# determines the order of execution.
+
+example do
+  instance = OrderingTest.new
+  result_of(instance.test_method) == "base_method"
+
+  ContextR::with_layer :foo do
+    result_of(instance.test_method) == "foo_before base_method foo_after"
+  end
+  ContextR::with_layer :bar do
+    result_of(instance.test_method) == "bar_before base_method bar_after"
+  end
+
+  ContextR::with_layer :bar, :foo 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
+      result_of(instance.test_method) == 
+                      "bar_before foo_before base_method foo_after bar_after"
+    end
+  end
+
+  ContextR::with_layer :foo, :bar 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
+      result_of(instance.test_method) == 
+                      "foo_before bar_before base_method bar_after foo_after"
+    end
+  end
+end
+
+# As you can see, the innermost layer activation provides the innermost method
+# definition. It is not important, whether the layers were activated at once
+# or one after the other.
+#
+# Activating and already active layer may update the execution order. The outer
+# activation is hidden, but is restored again after leaving the block.
+
+example do
+  instance = OrderingTest.new
+
+  ContextR::with_layer :bar, :foo do
+    result_of(instance.test_method) == 
+                      "bar_before foo_before base_method foo_after bar_after"
+
+    ContextR::with_layer :bar do
+      result_of(instance.test_method) == 
+                      "foo_before bar_before base_method bar_after foo_after"
+    end
+
+    result_of(instance.test_method) == 
+                      "bar_before foo_before base_method foo_after bar_after"
+  end
+end
+
+
+# Multiple modules per layer and class
+# ====================================
+
+# It is also possible to have more than one module define the context-dependent
+# behaviour of a class. In this case it may also happen, that multiple modules
+# extend the same method definition.
+#
+# In this case we can reuse or already defined class and modules. This time
+# we include them into the same layer and see what happens.
+
+class OrderingTest
+  include FooMethods => :foo_bar
+  include BarMethods => :foo_bar
+end
+
+example do
+  instance = OrderingTest.new
+  result_of(instance.test_method) == "base_method"
+
+  ContextR::with_layer :foo_bar do
+    result_of(instance.test_method) == 
+                      "bar_before foo_before base_method foo_after bar_after"
+  end
+end
+
+# This time the last inclusion defines the outermost method. This can be again
+# changed. After repeating an inclusion the ordering is updated.
+
+example do
+  class OrderingTest
+    include FooMethods => :foo_bar
+  end
+
+  instance = OrderingTest.new
+  result_of(instance.test_method) == "base_method"
+
+  ContextR::with_layer :foo_bar do
+    result_of(instance.test_method) == 
+                      "foo_before bar_before base_method bar_after foo_after"
+  end
+end
+
+# These should be all case where ordering matters. If you are aware of the
+# two basic rules, everything should work as expected. In an ideal world the
+# the execution order would not be important. But hey, this is not the ideal
+# world, so you better know.

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: contextr
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
-date: 2007-09-07 00:00:00 +02:00
+  version: 0.1.1
+date: 2007-09-16 00:00:00 +02:00
 summary: The goal is to equip Ruby with an API to allow context-oriented programming.
 require_paths: 
 - lib
@@ -25,17 +25,39 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIDODCCAiCgAwIBAgIBADANBgkqhkiG9w0BAQUFADBCMQ0wCwYDVQQDDARydWJ5
+  MR0wGwYKCZImiZPyLGQBGRYNc2NobWlkdHdpc3NlcjESMBAGCgmSJomT8ixkARkW
+  AmRlMB4XDTA3MDkxNjEwMzkyN1oXDTA4MDkxNTEwMzkyN1owQjENMAsGA1UEAwwE
+  cnVieTEdMBsGCgmSJomT8ixkARkWDXNjaG1pZHR3aXNzZXIxEjAQBgoJkiaJk/Is
+  ZAEZFgJkZTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAOzbl83o33wh
+  veLMQ2JyEstgOulisHRBFpfbF9LbdavuS/EdoOUeEPkziWL/ZI0jvUo0MGmQ/8Of
+  F9DJbvNbhDdg0bK7BMe4R/I3Wpu49mX+7pOsdlC44nzJkVG1DQ67qWp6jx1zvDRc
+  iCoXaQKnROtsx6bCavVvm4P7XLrAQvs7l+1Ke5KLkXRtJ9xJWtAyBLRFoM4e6DeT
+  Py0DsixF9Zb5Nrb7UvK0CN8m6dulsKXNRDVQLHkFa5Zg/BEb0RI93LPmeBt8KGIE
+  eYVjk+6z+py03D18xd9KsUhOB/0lC0a5vWSZIKfZnxf1uYY9TTZVqTGGUMFi1sD4
+  k2TYBqQVsS8CAwEAAaM5MDcwCQYDVR0TBAIwADALBgNVHQ8EBAMCBLAwHQYDVR0O
+  BBYEFAeq4388e2PUlF/YeemzaY8neefWMA0GCSqGSIb3DQEBBQUAA4IBAQAArQQo
+  3teQbCcYmZFTrdOzujMca6F4JVzTp+yTnOsp1/5hiBEUMc3GreCVAPh2tU9+IpuB
+  Lif+s5nLfYdI+JrpCHDzm+ecJEJ7u7gxidzUwEBPYpVuU32ALge7fuWWhQfi29JY
+  QwNZgIkGe34z3a2+r2GLBns/GY7t0Lomv6U2SvwLreLc8g7thr2hZfgEJidvcrJR
+  Q6amsFqY06NalH+I175Bp4y9rR7IArgNDS3I5Cly5/heVKK2SRm5Z+IACmKMxIXh
+  hzBK8YDsrjUvPNIJn9yl0LeEsZ5VhupI2OXr6Cqa/tVMJq0oiTsLfel3Tsb9Ph83
+  y3O9DT3o4BiyPe77
+  -----END CERTIFICATE-----
+
 post_install_message: 
 authors: 
 - Gregor Schmidt
 files: 
+- COPYING.txt
 - History.txt
-- License.txt
+- LICENSE.txt
 - Manifest.txt
 - README.txt
 - Rakefile
-- examples/general.rb
-- examples/ordering.rb
+- examples/README
 - lib/contextr.rb
 - lib/contextr/class_methods.rb
 - lib/contextr/core_ext.rb
@@ -54,25 +76,30 @@ files:
 - spec/contextr_spec.rb
 - spec/spec.opts
 - spec/spec_helper.rb
+- test/test_class_side.rb
 - test/test_contextr.rb
+- test/test_dynamics.rb
 - test/test_helper.rb
-- website/index.html
-- website/index.txt
-- website/javascripts/rounded_corners_lite.inc.js
-- website/stylesheets/screen.css
-- website/template.rhtml
+- test/test_introduction.rb
+- test/test_layer_state.rb
+- test/test_ordering.rb
 test_files: 
+- test/test_class_side.rb
 - test/test_contextr.rb
+- test/test_dynamics.rb
 - test/test_helper.rb
+- test/test_introduction.rb
+- test/test_layer_state.rb
+- test/test_ordering.rb
 rdoc_options: 
 - --main
 - README.txt
 extra_rdoc_files: 
+- COPYING.txt
 - History.txt
-- License.txt
+- LICENSE.txt
 - Manifest.txt
 - README.txt
-- website/index.txt
 executables: []
 
 extensions: []

data/License.txt

@@ -1,20 +0,0 @@
-Copyright (c) 2007 FIXME full name
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/examples/general.rb

@@ -1,152 +0,0 @@
-require File.dirname(__FILE__) + "/../lib/contextr.rb"
-
-module Common
-  module AddressMethods
-    def to_s
-      [yield(:next), yield(:receiver).address].join("; ")
-    end
-  end
-end
-
-class Student < Struct.new(:first_name, :last_name, :address, :university)
-  def to_s
-    [first_name, last_name].join(" ")
-  end
-
-  module EducationMethods
-    def to_s
-      [yield(:next), yield(:receiver).university].join("; ")
-    end
-  end
-
-  include Common
-  include EducationMethods => :education
-  include AddressMethods => :address
-end
-
-class University < Struct.new(:name, :address)
-  def to_s
-    name
-  end
-
-  include Common
-  include AddressMethods => :address
-end
-
-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
-
-    module LoggingMethods
-      def compute(fixnum)
-        print "."
-        yield(:next, fixnum)
-      end
-    end
-
-    module CacheMethods
-      def cache
-        @cache ||={}
-      end
-
-      def compute(fixnum)
-        cache[fixnum] ||= yield(:next, fixnum)
-      end
-    end
-  end
-
-  self.extend(ClassMethods)
-  include :class_side => true,
-           ClassMethods::CacheMethods    => :cache,
-           ClassMethods::LoggingMethods  => :logging
-end
-
-puts
-puts "Example on Instance Side"
-module Example
-  module ClassMethods
-    def show
-      me = Student.new("Gregor", "Schmidt", "Berlin")
-      hpi = University.new("HPI", "Potsdam")
-      me.university = hpi
-      print(me)
-    end
-
-    def print(me)
-      puts me
-      with_addresses do
-        puts me
-      end
-      with_education do
-        puts me
-      end
-      with_education do
-        with_addresses do
-          puts me
-        end
-      end
-    end
-
-    def with_addresses
-      ContextR::with_layers :address do
-        yield
-      end
-    end
-
-    def with_education
-      ContextR::with_layers :education do
-        yield
-      end
-    end
-  end
-  self.extend(ClassMethods)
-end
-Example.show
-
-puts
-puts "Example with changed instance methods after behaviour registration"
-class Student
-  def to_s
-    [first_name, last_name].reverse.join(", ")
-  end
-end
-Example.show
-
-puts
-puts "Example with changed behaviour methods after their registration"
-module Student::EducationMethods
-  def to_s
-    [yield(:next), yield(:receiver).university].join("\n - ")
-  end
-end
-Example.show
-
-puts
-puts "Example on Class Side"
-class ExampleClassSide
-  module ClassMethods
-    def show(int = 3)
-      puts Fibonacci.compute(int)
-      ContextR::with_layers :cache do
-        puts Fibonacci.compute(int)
-      end
-      ContextR::with_layers :logging do
-        puts Fibonacci.compute(2 * int)
-
-        ContextR::with_layers :cache do
-          puts Fibonacci.compute(2 * int)
-        end
-      end
-    end
-  end
-  self.extend(ClassMethods)
-end
-ExampleClassSide.show