phenomenal 0.9.0

data/LICENSE

@@ -0,0 +1,27 @@
+Copyright (C) 2011 Thibault Poncelet <thibault.poncelet@student.uclouvain.be>
+Copyright (C) 2011 Loic Vigneron <loic.vigneron@student.uclouvain.be>
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+========================
+
+Master thesis : The phenomenal gem
+Prof : Kim Mens
+Year : 2011-2012
+Students names,sections :
+                           - Poncelet Thibault (SINF22MS)
+                           - Vigneron Loic (SINF22MS)
+Start date : May 1, 2011
+

data/README

@@ -0,0 +1,3 @@
+Phenomenal Gem is a context-oriented framework implemented in Ruby that allows context-oriented programming in Ruby and Ruby on Rails applications. 
+
+See www.phenomenal-gem.com for more details

data/Rakefile

@@ -0,0 +1,11 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new('spec')

data/lib/phenomenal.rb

@@ -0,0 +1,24 @@
+# Load the gem files in the system
+module Phenomenal end
+#Relationships
+require_relative "./phenomenal/relationships/context_relationships.rb"
+require_relative "./phenomenal/relationships/feature_relationships.rb"
+require_relative "./phenomenal/relationships/relationships_store.rb"
+require_relative "./phenomenal/relationships/relationships_manager.rb"
+require_relative "./phenomenal/relationships/relationship.rb"
+require_relative "./phenomenal/relationships/requirement.rb"
+require_relative "./phenomenal/relationships/implication.rb"
+require_relative "./phenomenal/relationships/suggestion.rb"
+
+# Core
+require_relative "./phenomenal/adaptation.rb"
+require_relative "./phenomenal/conflict_policies.rb"
+require_relative "./phenomenal/context.rb"
+require_relative "./phenomenal/feature.rb"
+require_relative "./phenomenal/logger.rb"
+require_relative "./phenomenal/manager.rb"
+require_relative "./phenomenal/proc.rb"
+
+# DSL
+require_relative "./phenomenal/relationships/dsl.rb"
+require_relative "./phenomenal/dsl.rb"

data/lib/phenomenal/adaptation.rb

@@ -0,0 +1,79 @@
+# Represent a method adaptation for a particular context
+class  Phenomenal::Adaptation
+  attr_accessor :context, :klass, :method_name, :implementation, :src_file,
+                :src_line,:instance_adaptation
+                
+  def initialize(context,klass, method_name,instance_adapatation,implementation)
+    @context = context
+    @klass = klass
+    @method_name = method_name
+    @implementation = implementation
+    @instance_adaptation=instance_adapatation
+    
+    check_validity
+    # Save the source location if any, this is used to find again the adaptation
+    # in a ctxt_proceed call. It always exists except for method directly
+    # implemented in C -> Not a problem because these one never use ctxt_proceed
+    source_location = implementation.source_location
+    if source_location
+      @src_file = implementation.source_location[0]
+      @src_line = implementation.source_location[1]
+    end
+  end
+
+  # Deploy actually the adaptation in the target class by overriding the current
+  # implementation
+  def deploy
+    method_name = self.method_name
+    implementation = self.implementation
+    if instance_adaptation?
+      klass.class_eval { define_method(method_name, implementation) }
+    else
+      klass.define_singleton_method(method_name,implementation)
+    end
+  end
+  
+  # IMPROVE check for better implementation
+  # Bind the implementation corresponding to this adaptation to 'instance' when
+  # instance_method or to implementation klass when class method 
+  def bind(instance,*args,&block)
+    if instance_adaptation?
+      if implementation.class==Proc
+        implementation.phenomenal_bind(instance).call(*args,&block)
+      else
+        implementation.bind(instance).call(*args,&block)
+      end
+    else
+      if implementation.class==Proc
+        implementation.phenomenal_class_bind(klass).call(*args,&block)
+      else
+        implementation.call(*args,&block)
+      end
+    end
+  end
+  
+  #True if the adaptation concern the class n_klass and method n_method
+  def concern?(klass,method_name,instance_adaptation)
+    self.klass==klass && 
+    self.method_name==method_name && 
+    self.instance_adaptation==instance_adaptation
+  end
+
+  alias_method :instance_adaptation?, :instance_adaptation
+  
+  # String representation
+  def to_s
+   ":#{context.name} => #{klass.name}.#{method_name} :: #{src_file}:#{src_line}"
+  end
+  
+  private
+  def check_validity
+    if klass.instance_methods.include?(method_name) && !instance_adaptation? ||
+      !klass.instance_methods.include?(method_name) &&  instance_adaptation?
+      Phenomenal::Logger.instance.error(
+        "Illegal adaptation for context: #{context}" +
+        " for #{klass.name}.#{method_name}, type mismatch"
+      )
+    end
+  end
+end

data/lib/phenomenal/conflict_policies.rb

@@ -0,0 +1,20 @@
+# Context conflict resolution policies
+module Phenomenal::ConflictPolicies
+  # Prefer not default adaptation, error if two not default ones
+    def no_resolution_conflict_policy(adaptation1,adaptation2)
+      if adaptation1.context==default_context()
+        1
+      elsif adaptation2.context.name==default_context()
+        -1
+      else #Fail if two non default adaptations
+        Phenomenal::Logger.instance.error(
+            "Error: Illegal duplicate adapation of #{adaptation1.to_s}"
+        )
+      end
+    end
+
+    # Age based conflict resolution
+    def age_conflict_policy(adaptation1, adaptation2)
+       adaptation1.context.age <=> adaptation2.context.age
+    end
+end

data/lib/phenomenal/context.rb

@@ -0,0 +1,269 @@
+# Represent a first class context
+class Phenomenal::Context
+  include Phenomenal::ContextRelationships
+  @@total_activations = 0
+  def self.create(context,*contexts,nested,closest_feature,&block)
+    manager = Phenomenal::Manager.instance
+    contexts.insert(0,context)
+    if contexts.length==1
+      if !manager.context_defined?(context)
+        context = self.new(context) 
+      else
+        context = manager.find_context(context)
+        if !context.instance_of?(self)
+          Phenomenal::Logger.instance.error(
+            "Only #{self.name} can be used with this keyword"
+          )
+        end
+      end
+    else #Combined contexts
+      if !manager.context_defined?(*contexts) # New combined context
+        context = self.new
+        context.parent=closest_feature # Set parent
+        instances = Array.new
+        first = contexts.first
+        contexts.each do |c|
+          # Use the object instance if already available
+          # otherwise create it
+          if manager.context_defined?(c)
+            c = manager.find_context(c) 
+            if !nested && c!=first && !c.instance_of?(self)
+              Phenomenal::Logger.instance.error(
+                "Only #{self.name} can be used with this keyword"
+              )
+            end
+          else
+            c = self.new(c) 
+          end
+          instances.push(c)
+          manager.shared_contexts[c]= Array.new if !manager.shared_contexts[c]
+          manager.shared_contexts[c].push(context)
+        end
+        manager.combined_contexts[context] = instances
+      else
+        context = manager.find_context(*contexts)
+      end
+    end
+    context.add_adaptations(&block)
+    context
+  end
+  
+  attr_accessor :activation_age, :activation_frequency, :adaptations, 
+    :activation_count, :parent,:forgotten
+  attr_reader :manager,:name
+  
+  def initialize(name=nil, manager=nil)
+    @manager = manager || Phenomenal::Manager.instance
+    @name = name
+    @activation_age = 0
+    @activation_count = 0
+    @adaptations = Array.new
+    @manager.register_context(self)
+    @parent=nil
+    @forgotten=false
+  end
+  
+  # Unregister the context from the context manager,
+  # This context shoudn't be used after.
+  # The context has to be inactive before being forgetted
+  # TODO handle relationships references
+  def forget
+    if active?
+      Phenomenal::Logger.instance.error(
+        "Active context cannot be forgotten"
+      )
+    else
+      manager.unregister_context(self)
+      forgotten=true
+    end
+  end
+  
+  # Add a new method adaptation to the context
+  # Return the adaptation just created
+  def add_adaptation(klass, method_name,instance,umeth=nil, &implementation)
+    if umeth
+      implementation = umeth
+      instance = klass.instance_methods.include?(method_name)
+    end
+    if adaptations.find{ |i| i.concern?(klass,method_name,instance) }
+      Phenomenal::Logger.instance.error(
+        "Error: Illegal duplicated adaptation in context: #{self} for " + 
+        "#{klass.name}:#{method_name}"
+      )
+    else
+      if klass.instance_methods.include?(method_name) && instance
+        method = klass.instance_method(method_name)
+      elsif klass.methods.include?(method_name) && !instance
+        method = klass.method(method_name)
+      else
+        Phenomenal::Logger.instance.error(
+          "Error: Illegal adaptation for context #{self},a method with "+
+          "name: #{method_name} should exist in class #{klass.name} to "+ 
+          "be adapted"
+        )
+      end
+      if method.arity != implementation.arity
+        Phenomenal::Logger.instance.error(
+          "Error: Illegal adaptation for context #{self},the adaptation "+ 
+          "have to keep the original method arity for method: " +
+          "#{klass.name}.#{method_name}: (#{method.arity} instead of " +
+          "#{implementation.arity})" 
+        )
+      end
+      
+      adaptation = Phenomenal::Adaptation.new(
+        self, klass, method_name,instance, implementation
+      )
+      adaptations.push(adaptation)
+      manager.register_adaptation(adaptation)
+      adaptation
+    end
+  end
+  
+  # Catch nested context calls and transform them in nested contexts creation
+  def context(context,*contexts,&block)
+    check_validity
+    Phenomenal::Context.create(self,context,*contexts,true,self,&block)
+  end
+  alias_method :phen_context,:context
+  
+  # Catch nested feature calls and transform them in nested contexts creation
+  def feature(feature,*features, &block)
+    check_validity
+    Phenomenal::Feature.create(self,feature,*features,true,self,&block)
+  end
+  alias_method :phen_feature,:feature
+
+  # Add multiple adaptations at definition time
+  def add_adaptations(&block)
+    instance_eval(&block) if block
+  end
+  
+  # Set the current adapted class for the next adapt calls
+  def adaptations_for(klass)
+    @current_adapted_class = klass
+  end
+  
+  # Adapt a method for @current_adapted_class
+  def adapt(method,&block)
+    add_adaptation(@current_adapted_class,method,true,&block)
+  end
+  
+  # Adapt a method for @current_adapted_class
+  def adapt_klass(method,&block)
+    add_adaptation(@current_adapted_class,method,false,&block)
+  end
+
+  # Remove a method adaptation from the context
+  def remove_adaptation(klass,method_name,instance)
+    adaptation_index =
+      adaptations.find_index{ |i| i.concern?(klass, method_name,instance) }
+    if !adaptation_index
+      Phenomenal::Logger.instance.error(
+        "Error: Illegal deleting of an inexistent adaptation in context: " +
+        "#{self} for #{klass.name}.#{method_name})"
+      )
+    end
+    
+    adaptation = adaptations.delete_at(adaptation_index)
+    manager.unregister_adaptation(adaptation)
+  end
+  
+  # Activate the context
+  def activate
+    check_validity
+    @@total_activations +=1
+    self.activation_age =@@total_activations
+    self.activation_count = self.activation_count+1
+    manager.activate_context(self)
+    self
+  end  
+  
+  # Deactivate the context
+  def deactivate(caller_context=nil)
+    check_validity
+    was_active = active?
+    if self.activation_count>0
+      #Deactivation
+      self.activation_count =  self.activation_count-1
+    end
+    if was_active && !active?
+      manager.deactivate_context(self)
+    end
+    self
+  end
+  
+  # True if the context is active
+  def active?
+    activation_count>0
+  end
+  
+  # True if the context has just became active
+  def just_activated?
+    activation_count==1
+  end
+  
+  # True if the context is anonymous
+  def anonymous?
+    name.nil?
+  end
+  
+  # Return the activation age of the context:
+  #  The age counter minus the age counter when the context was activated
+  #  for the last time
+  def age
+    @@total_activations-activation_age
+  end
+  
+  # Return context informations:
+  #   - Name
+  #   - List of the adaptations
+  #   - Active state
+  #   - Activation age
+  #   - Activation count
+  def information
+    {
+      :name=>name,
+      :adaptations=>adaptations,
+      :active=>active?,
+      :age=>age,
+      :activation_count=>activation_count,
+      :type=>self.class.name
+    }
+  end
+  
+  # Return the closest parent feature of the context
+  def parent_feature
+    p = parent
+    while p!=nil && !p.is_a?(Phenomenal::Feature) do
+      p=p.parent
+    end
+    if p.nil?
+      manager.default_context
+    else
+      p
+    end
+  end
+  
+  # String representation of the context
+  def to_s
+    if name
+      name.to_s
+    elsif self==manager.default_context
+      "'Default context'"
+    elsif manager.combined_contexts[self]
+       "'Combined context : #{manager.combined_contexts[self].flatten}'"
+    else
+      "'Anonymous context'"
+    end
+  end
+  
+  private
+  def check_validity
+    if forgotten
+      Phenomenal::Logger.instance.error(
+        "Action not allowed anymore when context has been forgotten"
+      )
+    end
+  end
+end

data/lib/phenomenal/dsl.rb

@@ -0,0 +1,119 @@
+# Define the DSL methods
+module Phenomenal::DSL
+  #Override included hook method
+  def self.included(klass)
+    klass.class_eval do
+      #Define Context
+      def phen_define_context(name=nil,priority=nil)
+        Phenomenal::Context.new(name,priority)     
+      end
+      # Define context with adaptations
+      def phen_context(context,*contexts,&block)
+        Phenomenal::Context.create(context,*contexts,false,nil,&block)
+      end
+      Phenomenal::DSL.phen_alias(:context,klass)
+      
+      # Define context with adaptations
+      def phen_feature(context,*contexts,&block)
+        Phenomenal::Feature.create(context,*contexts,false,nil,&block)
+      end
+      Phenomenal::DSL.phen_alias(:feature,klass)
+      
+      
+      # Forget Context
+      def phen_forget_context(context)
+        Phenomenal::Manager.instance.find_context(context).forget
+      end
+      
+      # Add adaptation
+      def phen_add_adaptation(context,klass, method_name, &implementation)
+        Phenomenal::Manager.instance.find_context(context).add_adaptation(
+          klass, method_name,true, &implementation
+        )
+      end
+      
+      def phen_add_class_adaptation(context,klass, method_name, &implementation)
+        Phenomenal::Manager.instance.find_context(context).add_adaptation(
+          klass, method_name,false, &implementation
+        )
+      end
+      
+      # Remove Adaptation
+      def phen_remove_adaptation(context,klass,method_name) 
+        Phenomenal::Manager.instance.find_context(context).remove_adaptation(
+          klass,method_name,true
+        )
+      end
+      
+      def phen_remove_class_adaptation(context,klass,method_name) 
+        Phenomenal::Manager.instance.find_context(context).remove_adaptation(
+          klass,method_name,false
+        )
+      end
+      
+      # Activate Context
+      def phen_activate_context(context)
+        Phenomenal::Manager.instance.find_context(context).activate
+      end
+      Phenomenal::DSL.phen_alias(:activate_context,klass)
+      
+      # Deactivate Context
+      def phen_deactivate_context(context)
+        Phenomenal::Manager.instance.find_context(context).deactivate   
+      end
+      Phenomenal::DSL.phen_alias(:deactivate_context,klass)
+      
+      # Context is active?
+      def phen_context_active?(context)
+        Phenomenal::Manager.instance.find_context(context).active?
+      end
+      
+      # Context informations
+      def phen_context_information(context)
+        Phenomenal::Manager.instance.find_context(context).information
+      end
+      
+      # Default Context
+      def phen_default_context
+        Phenomenal::Manager.instance.default_context
+      end
+      
+      # Defined context registered in the manager
+      def phen_defined_contexts    
+        Phenomenal::Manager.instance.contexts.values
+      end
+      
+      # Proceed
+      def phen_proceed(*args,&block)
+        Phenomenal::Manager.instance.proceed(caller,self,*args,&block)
+      end
+      Phenomenal::DSL.phen_alias(:proceed,klass)
+
+      # Change conflict resolution policy (for the proceed call)
+      def phen_change_conflict_policy(&block)
+        Phenomenal::Manager.instance.change_conflict_policy(&block) 
+      end
+    end
+    # Add relationships specific DSL
+    define_relationships(klass)
+  end
+  
+  private
+  def self.phen_alias(method,klass)
+    if Kernel.respond_to? method
+      Phenomenal::Logger.instance.warn(
+        "The Phenomenal DSL keyword #{method} wasn't defined, use"+
+        " phen_#{method} instead"
+      )
+    else
+      klass.class_eval do
+        alias_method method, "phen_#{method}"
+      end
+    end
+  end
+end
+
+#Load the phenomenal primitives as top level methods
+module Kernel
+  include Phenomenal::DSL
+end