contextr 0.1.1 → 0.1.9

data/lib/contextr/version.rb

@@ -2,7 +2,7 @@ module ContextR #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
     MINOR = 1
-    TINY  = 1
+    TINY  = 9
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/lib/ext/dynamic.rb

@@ -65,9 +65,9 @@ module Dynamic
         save[key] = self[key]
         self[key] = value
       }
-      return_value = block.call
+      block.call
+    ensure
       variables.update save
-      return_value
     end
 
     def method_missing(name, *args)

data/spec/contextr_spec.rb

@@ -2,7 +2,7 @@ require File.dirname(__FILE__) + '/spec_helper.rb'
 
 module AddressMethods
   def to_s
-    "#{yield(:next)} (#{yield(:receiver).address})"
+    "#{super} (#{yield(:receiver).address})"
   end
 end
 
@@ -11,7 +11,9 @@ class University < Struct.new(:name, :address)
     name
   end
 
-  include AddressMethods => :address
+  in_layer :address do
+    include AddressMethods
+  end
 end
 
 class Student < Struct.new(:name, :address, :education)
@@ -19,35 +21,35 @@ class Student < Struct.new(:name, :address, :education)
     name
   end
 
-  include AddressMethods => :address
-
-  module EducationMethods
+  in_layer :address do
+    include AddressMethods
+  end
+  in_layer :education do
     def to_s
-      "#{yield(:next)}, #{yield(:receiver).education}"
+      "#{super}, #{yield(:receiver).education}"
     end
   end
-
-  include EducationMethods => :education
 end
 
 class Ordering 
-  def test
+  def inner_outer
     "base"
   end
 
   module InnerMethods
-    def test
-      "inner #{yield(:next)} inner"
+    def inner_outer 
+      "inner #{super} inner"
     end
   end
-  include InnerMethods => :multiple_modules
-
   module OuterMethods
-    def test
-      "outer #{yield(:next)} outer"
+    def inner_outer
+      "outer #{super} outer"
     end
   end
-  include OuterMethods => :multiple_modules
+  in_layer :multiple_modules do
+    include InnerMethods
+    include OuterMethods
+  end
 end
 
 
@@ -104,22 +106,26 @@ describe "A contextified object" do
 
   it "should also activate multiple modules per layer" do
     ContextR::with_layers :multiple_modules do
-      Ordering.new.test.should == "outer inner base inner outer"
+      Ordering.new.inner_outer.should == "outer inner base inner outer"
     end
   end
 
   it "should show new specific behaviour after changing module definitions" do
-    module Student::EducationMethods
-      def to_s
-        "#{yield(:next)} @ #{yield(:receiver).education}"
+    class Student
+      in_layer :education do
+        def to_s
+          "#{super} @ #{yield(:receiver).education}"
+        end
       end
     end
     ContextR::with_layer :education do
       @student.to_s.should == "Gregor Schmidt @ HPI"
     end
-    module Student::EducationMethods
-      def to_s
-        "#{yield(:next)}, #{yield(:receiver).education}"
+    class Student
+      in_layer :education do
+        def to_s
+          "#{super}, #{yield(:receiver).education}"
+        end
       end
     end
   end
@@ -149,14 +155,13 @@ describe "A method modules defining context dependent behaviour" do
 
   it "should have inner state" do
     class Student
-      module LogMethods
+      in_layer :log do
         def to_s
           @i ||= 0
           @i += 1
-          "#{@i}: #{yield(:next)}"
+          "#{@i}: #{super}"
         end
       end
-      include LogMethods => :log
     end
     ContextR::with_layer :log do
       @student.to_s.should == "1: Gregor Schmidt"
@@ -172,11 +177,11 @@ describe "A method modules defining context dependent behaviour" do
   
   it "should not lose its state after redefinition of the module" do
     class Student
-      module LogMethods
+      in_layer :log do
         def to_s
           @i ||= 0
           @i += 1
-          "(#{@i}) #{yield(:next)}"
+          "(#{@i}) #{super}"
         end
       end
     end
@@ -210,7 +215,8 @@ describe "ContextR" do
   end
 
   it "should provide a method to query for all layers ever defined" do
-    ContextR::layers.sort_by{ |s| s.to_s }.should ==
-                                [:address, :education, :log, :multiple_modules]
+    [:address, :education, :log, :multiple_modules].each do |layer|
+      ContextR::layers.sort_by{ |s| s.to_s }.should include(layer)
+    end
   end
 end

data/test/lib/example_test.rb

@@ -0,0 +1,59 @@
+module ExampleTest
+  module ClassMethods
+    attr_accessor :latest_test_class
+    attr_accessor :latest_test_case
+  end
+  extend ClassMethods
+
+  module ObjectExtension
+    def test_class(name)
+      ExampleTest::latest_test_class = Class.new(Test::Unit::TestCase)
+      ExampleTest::latest_test_case  = 0
+      Object.const_set(name, ExampleTest::latest_test_class) 
+    end
+
+    def example(&block)
+      ExampleTest::latest_test_class.class_eval do
+        define_method("test_%03d" % (ExampleTest::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

data/test/lib/literate_markaby_test.rb

@@ -0,0 +1,97 @@
+require 'markaby'
+if PLATFORM == "java"
+  class Markaby::Builder
+    def pre_block(block)
+    end
+  end
+else
+  require 'ruby2ruby'
+end
+
+module LiterateMarkabyTest
+  TARGET_DIR = File.dirname(__FILE__) + "/../../website/test/"
+  module ObjectExtension
+    def test(name, &block)
+      mab = Markaby::Builder.new
+
+      mab.test_class = Class.new(Test::Unit::TestCase)
+      mab.latest_test_case = 0
+
+      Object.const_set(name, mab.test_class) 
+      mab.xhtml_strict do
+        head do
+          title { name }
+        end
+        body do
+          h1 { name }
+          div(&block) 
+        end
+      end
+
+      Dir.mkdir(TARGET_DIR) unless File.directory?(TARGET_DIR)
+      File.open(TARGET_DIR + name.to_s.underscore + ".html", "w") do |f|
+        f.puts mab.to_s
+      end
+    end
+  end
+
+  module MarkabyBuilderExtension
+    attr_accessor :test_class, :latest_test_case
+    def pre_block(block)
+      self.pre(block.to_ruby.gsub(/^proc \{\n(.*)\n\}$/m, '\1'))
+    end
+
+    def output(&block)
+      block.call
+      pre_block(block)
+    end
+    def example(&block)
+      name = "test_%03d" % (self.latest_test_case += 1)
+      test_class.class_eval do
+        define_method(name, &block)
+      end
+      pre_block(block)
+    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 LiterateMarkabyTest::TestExtension
+#end
+class Object 
+  include LiterateMarkabyTest::ObjectExtension
+end
+class Markaby::Builder
+  include LiterateMarkabyTest::MarkabyBuilderExtension
+end
+

data/test/lib/literate_maruku_test.rb

@@ -0,0 +1,108 @@
+gem "literate_maruku"
+require "literate_maruku"
+require 'markaby'
+require 'active_support'
+
+class Fixnum
+  def ordinal
+    # teens
+    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'
+    end
+  end
+end
+
+class Time
+  def pretty
+    return "#{mday}#{mday.ordinal} #{strftime('%B')} #{year}"
+  end
+end
+
+module LiterateMarukuTest
+  BASE_DIR = File.dirname(__FILE__) + "/../"
+  TARGET_DIR = File.dirname(__FILE__) + "/../../website/test/"
+
+  def self.load(file)
+    content = LiterateMaruku.require(
+                               BASE_DIR + "#{File.basename(file, '.rb')}.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
+    
+    doc = Markaby::Builder.new.xhtml_strict do
+      head do
+        title "ContextR - #{sub_title} - Documentation"
+        link :href => "../stylesheets/screen.css", :rel=>'stylesheet', 
+             :type=>'text/css', :media => "screen"
+        script :src => "../javascripts/rounded_corners_lite.inc.js",
+              :type =>"text/javascript"
+        script %Q{
+          window.onload = function() {
+            settings = {
+                tl: { radius: 10 },
+                tr: { radius: 10 },
+                bl: { radius: 10 },
+                br: { radius: 10 },
+                antiAlias: true,
+                autoPad: true,
+                validTags: ["div"]
+            }
+            var versionBox = new curvyCorners(settings, 
+                                              document.getElementById("version"));
+            versionBox.applyCornersToAll();
+          }
+        }, :type => "text/javascript"
+      end
+      body do
+        div.main! do
+          h1 sub_title 
+          div.version! :class => "clickable",
+               :onclick => "document.location='#{download}'; return false" do
+            p "Get Version"
+            a version, :href => download, :class => "numbers"
+          end
+          h1 do
+            self << "&#x2192; &#8216;"
+            a "contextr", :href => "http://contextr.rubyforge.org/"
+            self << "&#8217;" 
+          end
+
+          ul.navi! do
+            Dir[File.dirname(file) + "/test_*.mkd"].each do |mkd_file_name|
+              li do
+                name = File.basename(mkd_file_name, ".mkd").gsub("test_", "")
+                a name.titleize, :href => name + ".html" 
+              end
+            end
+          end
+
+          self << content
+          p.coda do
+            text modified.pretty
+            br
+            text "Theme extended from "
+            a "Paul Battley", :href => "http://rb2js.rubyforge.org/"
+          end
+        end
+      end
+    end
+    File.open(TARGET_DIR + 
+            "#{File.basename(file, '.rb').gsub("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">})
+      doc.to_s.each do |chunk|
+        f.puts(chunk)
+      end
+    end
+  end
+end

data/test/test_class_side.mkd

@@ -0,0 +1,234 @@
+**TODO: Update to use new in\_layer API**
+
+In Ruby there are multiple ways of defining behaviour on the class side. That
+are messages that are send to the class, not to the instance. Class side 
+behaviour is often useful for functional methods, i.e. methods that do not
+rely on inner state and have no side effects. Mathematical functions have 
+these characteristics - that is where the name probably comes from.
+
+**Note**: Java programmers may know these methods as static. It is similar but 
+not exactly the same.
+
+
+Using `def self.method_name`
+-----------------------------
+
+The simpliest way of defining class side behaviour is prepending self. to the
+method definition. This way, the method is attached to the surrounding class 
+and not instance. A simple example:
+
+    class SimpleMath
+      def self.pi
+        3.14159265
+      end
+    end
+
+    example do
+      result_of(SimpleMath.pi) == 3.14159265
+    end
+
+
+Using `class << self`
+---------------------
+
+When you are having lots of class side methods as well as instance side ones,
+it can be difficult to spot the little self. in front of the method name.
+Probably you like to group them more explicitly. You could use Ruby's
+eigenclass principle for that. It will look like the following:
+
+    class SimpleMath
+      class << self
+        def e
+          2.71828183
+        end
+      end
+    end
+
+    example do
+      result_of(SimpleMath.e) == 2.71828183 
+    end
+
+**Note**: Eigenclasses are also known as *singleton class* or *meta class*. 
+I prefer eigenclass, because it not used with different meanings in other 
+contexts, which eases talking about it with experts in different languages.
+
+Using a module
+--------------
+
+For even more encapsulation you could also use modules and extend the class 
+definition with them. I am using extend here on purpose. Module's include
+method adds the behaviour to the instance side, extend to the class side.
+Or to rephrase it: Module's include method adds the behaviour to instances, 
+extend to the class itself.
+
+    class SimpleMath
+      module ClassMethods
+        def golden_ratio
+          1.6180339887
+        end
+      end
+
+      extend ClassMethods
+    end
+
+    example do
+      result_of(SimpleMath.golden_ratio) == 1.6180339887 
+    end
+
+The last method is e.g. used in the web framework Ruby on Rails. Often
+a variation of it is used to define class and instance side behaviour for
+mixin modules
+
+    module MathMixin
+      def counter
+        @counter ||= 0
+        @counter += 1
+      end
+
+      module ClassMethods
+        def sqrt(x)
+          x ** 0.5
+        end
+      end
+
+      def self.included(base)
+        base.extend ClassMethods
+      end
+    end
+
+    class SimpleMath
+      include MathMixin
+    end
+
+    example do
+      result_of(SimpleMath.sqrt(4)) == 2
+
+      my_simple_math = SimpleMath.new
+      result_of(my_simple_math.counter) == 1
+      result_of(my_simple_math.counter) == 2
+    end
+
+This is regarded as the most elegant way of defining class and instance 
+methods for a mixin module. And the basic functionality is the same as in the
+previous example.
+
+After we now know how to define class side behaviour, everybody is curious
+to know how to extend this behaviour using context-oriented programming and
+ContextR.
+
+Additionial, context-dependent behaviour is defined in `in_layer` blocks. 
+These are then attached to the layer, in which the behaviour should reside. 
+For examples on the instance side have a look at the bottom of 
+`test_introduction`.
+
+Let's look how we can achieve the same on the class side for each of the 
+different methods of defining class side behaviour.
+
+
+Using `def self.method_name`
+----------------------------
+
+**TODO: Allow def self.method\_name to add class side behaviour**
+
+Okay, we won't get rid of the modules, used to encapsulate the 
+context-dependent behaviour, so the extension is a bit noisier, than the 
+basic notation.
+
+    class SimpleMath
+      class << self
+        in_layer :access_control do
+          def pi
+            "You are not allowed to access this method"
+          end
+        end
+      end
+    end
+
+But we can use the same principles, like we did for the instance side. Simply
+use a hash to tell extend, that the module should only be used in a certain
+layer.
+
+    example do
+      result_of(SimpleMath.pi) == 3.14159265
+
+      ContextR::with_layer :access_control do
+        result_of(SimpleMath.pi) == "You are not allowed to access this method" 
+      end
+    end
+
+
+Using `class << self`
+---------------------
+
+When your using the eigenclass, you are able to use to good old in\_layer to
+manage the extension. 
+
+    class SimpleMath
+      class << self
+        in_layer :english do
+          def e
+            "Euler's constant"
+          end
+        end
+      end
+
+      class << self
+        in_layer :german do
+          def e
+            "Eulersche Zahl"
+          end
+        end
+      end
+    end
+
+    example do
+      result_of(SimpleMath.e) == 2.71828183 
+
+      ContextR::with_layer :german do
+        result_of(SimpleMath.e) == "Eulersche Zahl" 
+      end
+      ContextR::with_layer :english do
+        result_of(SimpleMath.e) == "Euler's constant" 
+      end
+    end
+
+
+Using a module
+--------------
+
+Hey, this is what we did all the time, so it is only natural to have the same
+syntax to extend a class using in module for context-dependent behaviour. But
+for the sake of completeness, I will attach another example.
+
+    class SimpleMath
+      class << self
+        in_layer :exact_computation do
+          def golden_ratio
+            sleep(0.01) # In real life this would take a bit longer, 
+                        # but I don't have the time.
+            1.6180339887_4989484820_4586834365_6381177203_0917980576 
+          end
+        end
+      end
+    end
+
+    example do
+      result_of(SimpleMath.golden_ratio) == 1.6180339887
+
+      ContextR::with_layer :exact_computation do
+        result_of(SimpleMath.golden_ratio) == 
+                      1.6180339887_4989484820_4586834365_6381177203_0917980576 
+      end
+    end
+
+
+Conclusion
+----------
+
+In general, there are two options to define context-dependent class side
+behaviour. Use in\_layer in the eigenclass or use extend anywhere else. Both
+options result in the same behaviour, just like the different options in 
+plain ruby look different, but have the same effect.
+
+The programmer is free to use, whatever suites best. This is still Ruby.
+