contextr 0.1.0 → 0.1.1

data/README.txt

@@ -1,3 +1,16 @@
-README for contextr
-===================
+= ContextR
 
+A context-oriented programming library for Ruby. 
+
+Inspired by ContextL (Pascal Costanza) and ContextS (Robert Hirschfeld) with 
+thanks to Christian Neukirchen for giving the name and lots of ideas.
+
+For more information see 
+- http://contextr.rubyforge.org/
+- http://www.contextr.org/ or 
+- http://www.swa.hpi.uni-potsdam.de/cop/
+
+This code is published under the same license as Ruby. See LICENSE.txt for more 
+information.
+
+(c) 2007 - Gregor Schmidt - Berlin, Germany

data/examples/README

@@ -0,0 +1,9 @@
+All documentation may be found in /test and /spec. The first contains written
+english and some embedded usage examples, the latter a specification written in
+RSpec.
+
+This allows the documentation to be executable and testable. Therefore it is 
+more likely that is in sync with the current development of the libary. This
+is all for your best.
+
+So just have a look at the files in test and you will see what I mean.

data/lib/contextr/class_methods.rb

@@ -1,5 +1,7 @@
-module ContextR
-  module ClassMethods
+module ContextR # :nodoc:
+  module ClassMethods # :nodoc:
+    include MutexCode
+
     def const_missing(const_name)
       if const_name.to_s =~ /.*Layer$/
         self.const_set(const_name, Class.new(ContextR::Layer))
@@ -14,8 +16,22 @@ module ContextR
       end
     end
 
+    def active_layers_as_classes
+      Dynamic[:layers]
+    end
+
+    def layered_do(layers, block)
+      Dynamic.let({:layers => layers}, &block)
+    end
+
+    def layers_as_classes
+      constants.select { |l| l =~ /.+Layer$/ }.collect { |l| 
+        l.scan(/(.+)Layer/).first.first.underscore.to_sym
+      }
+    end
+
     def symbol_by_layer(lay)
-      lay.to_s.gsub( /^ContextR::(.*)Layer$/, '\1' ).underscore
+      lay.to_s.gsub( /^ContextR::(.*)Layer$/, '\1' ).underscore.to_sym
     end
 
     def layer_by_symbol(sym)
@@ -45,7 +61,7 @@ module ContextR
     def on_core_method_called(receiver, contextified_class, 
                               method_name, arguments, block)
       proxies = []
-      layers.each do |layer|
+      active_layers_as_classes.each do |layer|
         proxies += layer.context_proxies(contextified_class, method_name)
       end.compact 
 
@@ -62,6 +78,9 @@ module ContextR
     def observe_core_method(klass, method_name, version)
       only_once do
         klass.class_eval(%Q{
+            if self.instance_methods.include?("#{method_name}")
+              undef_method("#{method_name}")
+            end
             def #{method_name}(*arguments, &block)
               ContextR::on_core_method_called(
                 self,

data/lib/contextr/core_ext/module.rb

@@ -1,18 +1,57 @@
-class Module 
-  alias_method :include_without_layers, :include
-  def include_with_layers(associations)
-    if associations.delete(:class_side)
-      klass = class << self; self; end
-    else
-      klass = self
-    end
+#--
+# The aliasing of these methods is done in a class_eval block to avoid code
+# documentation by RDoc.
+#++
+Module.class_eval do
+  alias_method :include_without_layers, :include 
+end
+
+class Module
+  protected
+  def include_with_layers(associations) # :nodoc:
     associations.each do | modul, layer |
-      ContextR::layer_by_symbol(layer).add_method_collection(klass, modul)
+      ContextR::layer_by_symbol(layer).add_method_collection(self, modul)
     end
+    self
   end
 
+  # call-seq:
+  #    include(module, ...)    => self
+  #    include(module => layer_qualifier, ...)    => self
+  # 
+  # Invokes <code>Module.append_features</code> on each parameter in turn.
+  #
+  # If called with a hash, adds the module to the given layer. The behaviour 
+  # is associated with the class side of the object.
+  #
+  #    module Mod
+  #      def name
+  #        "Hello from #{yield(:next)}.\n"
+  #      end
+  #    end
+  #    
+  #    class Klass
+  #      def name
+  #        "Klass"
+  #      end
+  #
+  #      include Mod => :hello
+  #    end
+  #    
+  #    k = Klass.new
+  #    k.name                    #=> "Klass.\n"
+  #    ContextR::with_layer :hello do
+  #      k.name                  #=> "Hello from Klass.\n"
+  #    end
+  #    k.name                    #=> "Klass.\n"
+  #
   def include(*args)
     args.first.is_a?(Module) ? include_without_layers(*args) : 
                                include_with_layers(*args)
   end
 end
+
+Module.class_eval do
+  private :include
+  private :include_with_layers
+end

data/lib/contextr/core_ext/object.rb

@@ -1,5 +1,72 @@
+#--
+# The aliasing of these methods is done in a class_eval block to avoid code
+# documentation by RDoc.
+#++
+Object.class_eval do
+  alias_method :extend_without_layers, :extend   
+end
+
 class Object
-  def behavioural_class
+  def extend_with_layers(associations) # :nodoc:
+    klass = class << self; self; end
+    associations.each do | modul, layer |
+      ContextR::layer_by_symbol(layer).add_method_collection(klass, modul)
+    end
+    self
+  end
+
+  # call-seq:
+  #    obj.extend(module, ...)    => obj
+  #    obj.extend(module => layer_qualifier, ...)    => obj
+  # 
+  # Adds to _obj_ the instance methods from each module given as a
+  # parameter.
+  #    
+  #    module Mod
+  #      def hello
+  #        "Hello from Mod.\n"
+  #      end
+  #    end
+  #    
+  #    class Klass
+  #      def hello
+  #        "Hello from Klass.\n"
+  #      end
+  #    end
+  #    
+  #    k = Klass.new
+  #    k.hello         #=> "Hello from Klass.\n"
+  #    k.extend(Mod)   #=> #<Klass:0x401b3bc8>
+  #    k.hello         #=> "Hello from Mod.\n"
+  #
+  # If called with a hash, adds the module to the given layer. The behaviour 
+  # is associated with the class side of the object.
+  #
+  #    module Mod
+  #      def name
+  #        "Hello from #{yield(:next)}.\n"
+  #      end
+  #    end
+  #    
+  #    class Klass
+  #      def name
+  #        "Klass"
+  #      end
+  #    end
+  #    
+  #    k = Klass.new
+  #    k.extend(Mod => :hello)   #=> #<Klass:0x401b3bc8>
+  #    k.name                    #=> "Klass.\n"
+  #    ContextR::with_layer :hello do
+  #      k.name                  #=> "Hello from Klass.\n"
+  #    end
+  #    k.name                    #=> "Klass.\n"
+  def extend(*args)
+    args.first.is_a?(Module) ? extend_without_layers(*args) : 
+                               extend_with_layers(*args)
+  end
+
+  def behavioural_class #:nodoc:
     if self.kind_of?(Module)
       class << self; self; end
     else

data/lib/contextr/event_machine.rb

@@ -1,5 +1,5 @@
 module ContextR
-  class EventMachine
+  class EventMachine # :nodoc: all
     module ClassMethods
       include UniqueId 
 

data/lib/contextr/layer.rb

@@ -1,5 +1,5 @@
-module ContextR
-  class Layer
+module ContextR # :nodoc:
+  class Layer # :nodoc: all
     module ClassMethods
       def definitions
         @definitions ||= {}
@@ -10,7 +10,9 @@ module ContextR
 
       def add_method_collection(contextified_class, methods_module)
         definitions[contextified_class] ||= []
-        definitions[contextified_class] |= [methods_module]
+        definitions[contextified_class].delete(methods_module)
+        definitions[contextified_class].push(methods_module)
+
         (methods_module.instance_methods & 
          contextified_class.instance_methods).each do | method_name |
           replace_core_method(contextified_class, method_name, 0)

data/lib/contextr/modules/mutex_code.rb

@@ -1,5 +1,5 @@
 require "thread"
-module MutexCode
+module MutexCode #:nodoc:
   def semaphore
     @semaphore ||= Mutex.new
   end

data/lib/contextr/modules/unique_id.rb

@@ -1,4 +1,4 @@
-module UniqueId
+module UniqueId #:nodoc:
   def new_unique_id
     $id_semaphore ||= Mutex.new
     $id_semaphore.synchronize do

data/lib/contextr/public_api.rb

@@ -1,14 +1,12 @@
 module ContextR
-  module ClassMethods
-    include MutexCode
-
+  module PublicApi 
     # allows the explicit activation of layers within a block context
     #
     #   ContextR::with_layers(:foo, :bar) do
-    #     ContextR::current_layers            # => [:default, :foo, :bar]
+    #     ContextR::active_layers            # => [:default, :foo, :bar]
     #
     #     ContextR::with_layers(:baz) do
-    #       ContextR::current_layers          # => [:default, :foo, :bar, :baz]
+    #       ContextR::active_layers          # => [:default, :foo, :bar, :baz]
     #     end
     #
     #   end
@@ -17,20 +15,20 @@ module ContextR
     #   with_layers(layer_name, ...) { ... }
     #
     def with_layers(*layer_symbols, &block)
-      layers = layer_symbols.collect do | layer_symbol |
+      layers = layer_symbols.collect do |layer_symbol|
         layer_by_symbol(layer_symbol)
       end
-      Dynamic.let({ :layers => Dynamic[:layers] | layers }, &block)
+      layered_do(active_layers_as_classes - layers + layers, block)
     end
     alias with_layer with_layers
 
     # allows the explicit deactivation of layers within a block context
     # 
     #   ContextR::with_layers(:foo, :bar) do
-    #     ContextR::current_layers            # => [:default, :foo, :bar]
+    #     ContextR::active_layers            # => [:default, :foo, :bar]
     #
     #     ContextR::without_layers(:foo) do
-    #       ContextR::current_layers          # => [:default, :bar]
+    #       ContextR::active_layers          # => [:default, :bar]
     #     end
     #
     #   end
@@ -39,20 +37,24 @@ module ContextR
     #   without_layers(layer_name, ...) { ... }
     #
     def without_layers(*layer_symbols, &block)
-      layers = layer_symbols.collect do | layer_symbol |
+      layers = layer_symbols.collect do |layer_symbol|
         layer_by_symbol(layer_symbol)
       end
-      Dynamic.let({ :layers => Dynamic[:layers] - layers }, &block)
+      layered_do(active_layers_as_classes - layers, block)
     end
     alias without_layer without_layers
 
-    def layers
-      Dynamic[:layers]
+    # returns all currently active layers in their activation order
+    def active_layers
+      active_layers_as_classes.collect { |layer| symbol_by_layer(layer) }
     end
 
-    def layer_symbols
-      layers.collect { | layer | symbol_by_layer(layer) }
+    # returns all layers that where defined, but are not neccessarily active
+    def layers
+      layers_as_classes.collect { |layer| symbol_by_layer(layer) }
     end
+
   end
+  self.extend(PublicApi)
 end
 

data/lib/contextr/version.rb

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

data/lib/ext/active_support_subset.rb

@@ -1,5 +1,26 @@
 unless Object.const_defined? "ActiveSupport"
   class Module
+    # Encapsulates the common pattern of:
+    #
+    #   alias_method :foo_without_feature, :foo
+    #   alias_method :foo, :foo_with_feature
+    #
+    # With this, you simply do:
+    #
+    #   alias_method_chain :foo, :feature
+    #
+    # And both aliases are set up for you.
+    #
+    # Query and bang methods (foo?, foo!) keep the same punctuation:
+    #
+    #   alias_method_chain :foo?, :feature
+    #
+    # is equivalent to
+    #
+    #   alias_method :foo_without_feature?, :foo?
+    #   alias_method :foo?, :foo_with_feature?
+    #
+    # so you can safely chain foo, foo?, and foo! with the same feature.
     def alias_method_chain(target, feature)
       # Strip out punctuation on predicates or bang methods since
       # e.g. target?_without_feature is not a valid method name.
@@ -23,9 +44,24 @@ unless Object.const_defined? "ActiveSupport"
     end
   end
 
-  module Inflector
+  # The Inflector transforms words from singular to plural, class names to 
+  # table names, modularized class names to ones without, and class names to 
+  # foreign keys. The default inflections for pluralization, singularization, 
+  # and uncountable words are kept in inflections.rb.
+  module Inflector #:nodoc:
     extend self
     
+    # By default, camelize converts strings to UpperCamelCase. If the argument 
+    # to camelize is set to ":lower" then camelize produces lowerCamelCase.
+    #
+    # camelize will also convert '/' to '::' which is useful for converting 
+    # paths to namespaces
+    #
+    # Examples
+    #   "active_record".camelize #=> "ActiveRecord"
+    #   "active_record".camelize(:lower) #=> "activeRecord"
+    #   "active_record/errors".camelize #=> "ActiveRecord::Errors"
+    #   "active_record/errors".camelize(:lower) #=> "activeRecord::Errors"
     def camelize(lower_case_and_underscored_word, 
                  first_letter_in_uppercase = true)
       if first_letter_in_uppercase
@@ -37,6 +73,14 @@ unless Object.const_defined? "ActiveSupport"
       end
     end
 
+    # The reverse of +camelize+. Makes an underscored form from the expression 
+    # in the string.
+    #
+    # Changes '::' to '/' to convert namespaces to paths.
+    #
+    # Examples
+    #   "ActiveRecord".underscore #=> "active_record"
+    #   "ActiveRecord::Errors".underscore #=> active_record/errors
     def underscore(camel_cased_word)
       camel_cased_word.to_s.gsub(/::/, '/').
                             gsub(/([A-Z]+)([A-Z][a-z])/,'\1_\2').
@@ -45,6 +89,13 @@ unless Object.const_defined? "ActiveSupport"
                             downcase
     end
 
+    # Constantize tries to find a declared constant with the name specified
+    # in the string. It raises a NameError when the name is not in CamelCase
+    # or is not initialized.
+    #
+    # Examples
+    #   "Module".constantize #=> Module
+    #   "Class".constantize #=> Class
     def constantize(camel_cased_word)
       unless /\A(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\z/ =~ camel_cased_word
         raise NameError, 
@@ -55,10 +106,26 @@ unless Object.const_defined? "ActiveSupport"
     end
   end
 
-  module ActiveSupport
-    module CoreExtensions
-      module String
+  module ActiveSupport #:nodoc:
+    module CoreExtensions #:nodoc:
+      module String #:nodoc:
+        # String inflections define new methods on the String class to 
+        # transform names for different purposes. For instance, you can figure 
+        # out the name of a database from the name of a class.
+        #   "ScaleScore".tableize => "scale_scores"
         module Inflections
+          # By default, camelize converts strings to UpperCamelCase. If the 
+          # argument to camelize is set to ":lower" then camelize produces 
+          # lowerCamelCase.
+          #
+          # camelize will also convert '/' to '::' which is useful for 
+          # converting paths to namespaces 
+          #
+          # Examples
+          #   "active_record".camelize #=> "ActiveRecord"
+          #   "active_record".camelize(:lower) #=> "activeRecord"
+          #   "active_record/errors".camelize #=> "ActiveRecord::Errors"
+          #   "active_record/errors".camelize(:lower) #=> "activeRecord::Errors"
           def camelize(first_letter = :upper)
             case first_letter
             when :upper then Inflector.camelize(self, true)
@@ -67,10 +134,25 @@ unless Object.const_defined? "ActiveSupport"
           end
           alias_method :camelcase, :camelize
 
+          # The reverse of +camelize+. Makes an underscored form from the 
+          # expression in the string.
+          # 
+          # Changes '::' to '/' to convert namespaces to paths.
+          #
+          # Examples
+          #   "ActiveRecord".underscore #=> "active_record"
+          #   "ActiveRecord::Errors".underscore #=> active_record/errors
           def underscore 
             Inflector.underscore(self)
           end
 
+          # Create a class name from a table name like Rails does for table 
+          # names to models. Note that this returns a string and not a Class. 
+          # (To convert to an actual class follow classify with constantize.)
+          #
+          # Examples
+          #   "egg_and_hams".classify #=> "EggAndHam"
+          #   "post".classify #=> "Post"
           def constantize
             Inflector.constantize(self)
           end