paramix 1.0.1 → 1.1.0

data/HISTORY

@@ -1,5 +1,26 @@
 = RELEASE HISTORY
 
+== 1.1.0 // 2010-04-05
+
+The previous versions did not properly support nested parametric
+includes, i.e. including one parametirc mixin into another. This
+release fixed this issue. However, to do so provided difficult
+and required some changes to the API. In particular, instead
+of +mixin_params[M][:p]+ one must now use +mixin_param(M,:p)+.
+It was not longer possible to simply return a hash, since special
+lookup logic is required to handle nested mixins. It should also
+be noted that +Module#mixin_parameters+, which stores the actual
+parameters is no longer accessible at the instance level, just
+as +mixin_param()+ is soley an instance method (at the class level
+it is used to access the singleton parameters).
+
+Changes:
+
+* Proper support for nested parametric mixins.
+* Provide #mixin_param method to lookup parameters.
+* The mixin_parameters method is class-level only.
+
+
 == 1.0.1 // 2010-04-03
 
 This release simply removed dependencies on Facets.
@@ -12,8 +33,9 @@ Changes:
 
 == 1.0.0 // 2009-06-29
 
-This is the initial stand-alone release of Paramix
-spun-off from Ruby Facets.
+This is the initial stand-alone release of Paramix spun-off
+from Ruby Facets (and is actually he second major version, the
+original being spun of from the Nitro/Og Glue library).
 
 Changes:
 

data/lib/paramix.rb

@@ -1,43 +1,16 @@
-# TITLE:
-#
-#   Parametric Mixins
-#
-# SUMMARY:
-#
-#   Parametric Mixins provides parameters for mixin modules.
-#
-# COPYRIGHT:
-#
-#   Copyright (c) 2008 T. Sawyer
-#
-# LICENSE:
-#
-#   Ruby License
-#
-#   This module is free software. You may use, modify, and/or redistribute this
-#   software under the same terms as Ruby.
-#
-#   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.
-#
-# AUTHORS:
-#
-#   - Thomas Sawyer
-
-
 # = Parametric Mixin
 #
 # Parametric Mixins provides parameters for mixin modules.
 # Module parameters can be set at the time of inclusion 
 # or extension using Module#[] method, then parameters
-# can be accessed via the #mixin_parameters method.
+# can be accessed via the #mixin_param and #mixin_parameters
+# methods.
 #
 #   module MyMixin
 #     include Paramix
 #
 #     def hello
-#       puts "Hello from #{mixin_parameters[MyMixin][:name]}!"
+#       puts "Hello from #{ mixin_param(MyMixin, :name) }!"
 #     end
 #   end
 #
@@ -48,154 +21,170 @@
 #   m = MyClass.new
 #   m.hello   #=> 'Hello from Ruby!'
 #
-# You can view the full set of parameters via the #mixin_parameters
-# class method, which returns a hash keyed on the included modules.
+# You can view the full set of parameters via the +mixin_parameters+ method.
 #
-#   MyClass.mixin_parameters           #=> {MyMixin=>{:name=>'Ruby'}}
-#   MyClass.mixin_parameters[MyMixin]  #=> {:name=>'ruby'}
+#   MyClass.mixin_parameters  #=> {MyMixin => {:name => 'ruby'}}
 #
-# The include Paramix is equivalent to:
+# Including Paramix into a module is essentially equivalent to defining
+# a module method:
 #
 #   def [](parameters)
-#     Paramix.new(self, parameters)
+#     Paramix::Proxy.new(self, parameters)
 #   end
 #
-# Paramix.new can also take a block that injects code into the class
-# or module including the parametric mixin. This is useful as an
-# alternative to using the #included callback for creating dynamic
-# mixins. For example:
+# Paramix::Proxy.new can also take a block that injects code into the
+# mixin. This is useful as an alternative to using the #included
+# callback for creating metaclass dynamics based on mixin parameters.
+# For example:
 #
-#   def self.[](parameters)
-#     Paramix.new(self, parameters) do
-#       attr_accessor mixin_params[MyMixin][:name]
+#   module MyMixin
+#     def self.[](parameters)
+#       Paramix::Mixin.new(self, parameters) do
+#         attr_accessor parameters[MyMixin][:name]
+#       end
 #     end
 #   end
 #
 # As opposed to:
 #
-#   module Mixin
+#   module MyMixin
+#     include Paramix
+#
 #     def self.included(base)
 #       base.class_eval do
-#         attr_accessor mixin_params[MyMixin][:name]
+#         attr_accessor base.mixin_parameters[:name]
 #       end
+#       super(base)
 #     end
 #   end
 #
-#--
-# More conveniently a new callback has been added, #included_with_parameters,
-# which passes in the parameters in addition to the base class/module.
-#
-#   module Mixin
-#     def self.included_with_parameters( base, parms )
-#       base.class_eval {
-#         def hello
-#           puts "Hello from #{mixin_parameters[Mixin][:name]}"
-#         end
-#       }
-#     end
-#   end
-#
-# We would prefer to have passed the parameters through the #included callback
-# method itself, but implementation of such a feature is much more complicated.
-# If a reasonable solution presents itself in the future however, we will fix.
-#++
-
-module Paramix # or PatrametricMixin ?
+module Paramix
 
-  def self.append_features(base)
-    (class << base; self; end).class_eval do
-      define_method(:[]) do |parameters|  # TODO until 1.9 no &block
-        Delegator.new(base, parameters)
-      end
-    end
-  end
-
-  # It you want to define the module's ::[] method by hand. You
-  # can use Paramix.new instead of Paramix::Delegator.new.
-
-  def self.new(delegate_module, parameters={}, &base_block)
-    Delegator.new(delegate_module, parameters, &base_block)
+  #
+  def self.included(base)
+    base.extend(ClassMethods)
+    super(base)
   end
 
   #
+  module ClassMethods
+    def [](parameters)
+      Proxy.new(self, parameters)
+    end
 
-  class Delegator < Module
+    def included(base)
+      base.extend(ClassMethods)
+      super(base)
+    end
+  end
 
-    attr :module_delegate
+  class Proxy < Module
+    attr :mixin
     attr :parameters
-    attr :base_block
+    attr :block
 
     #
-
-    def initialize(module_delegate, parameters={}, &base_block)
-      @module_delegate = module_delegate
-      @parameters      = parameters
-      @base_block      = base_block
+    def initialize(mixin, parameters, &block)
+      @mixin      = mixin
+      @parameters = parameters || {}
+      @block      = block
     end
 
     #
-
     def append_features(base)
-      base.mixin_parameters[module_delegate] = parameters
+      mixin = @mixin
 
-      base.module_eval do 
-        define_method(:mixin_parameters) do
-          base.mixin_parameters
-        end
-        alias_method :mixin_params, :mixin_parameters
-      end
+      base.mixin_parameters[mixin] ||= {}
+      base.mixin_parameters[mixin].update(@parameters)
+
+      mixin.module_eval{ append_features(base) }
 
-      base.module_eval(&@base_block) if base_block
+      base.module_eval{ include InstanceParameterize }
+      #base.extend ClassParameterize
 
-      base.__send__(:include, module_delegate)
+      mixin.module_eval{ included(base) }
+
+      base.module_eval(&@block) if @block
     end
 
     #
-
     def extend_object(base)
-      baseclass = (class << base; self; end)
+      mixin = @mixin
 
-      baseclass.mixin_parameters[module_delegate] = parameters
+      metabase = (class << base; self; end)
 
-      baseclass.module_eval do 
-        define_method(:mixin_parameters) do
-          baseclass.mixin_parameters
-        end
-        alias_method :mixin_params, :mixin_parameters
-      end
+      metabase.mixin_parameters[mixin] ||= {}
+      metabase.mixin_parameters[mixin].update(@parameters)
 
-      baseclass.module_eval(&@base_block) if base_block
+      mixin.module_eval{ extend_object(base) }
+
+      base.extend ClassParameterize
+
+      metabase.module_eval(&@block) if @block
+    end
 
-      base.__send__(:extend, module_delegate)
+    #
+    module InstanceParameterize
+      #
+      def mixin_param(m, n)
+        h = {}; r = nil
+        self.class.ancestors.each do |a|
+          break if Paramix == a
+          break if m == a
+          q = a.mixin_parameters
+          #if q = Paramix.mixin_params[a]
+            if q[m] && q[m].key?(n)
+              r = q[m][n]
+            else
+              q.each do |k,v|
+                h.update(v)
+              end
+            end
+          #end
+        end
+        r ? r : h[n]
+      end
     end
 
-    def [](name)
-      @parameters[name]
+    #
+    module ClassParameterize
+      #
+      def mixin_param(m, n)
+        h = {}; r = nil
+        ancestors.each do |a|
+          break if Paramix==a
+          if q = a.meta_class.mixin_parameters #[class << a; self ; end]
+          #if q = Paramix.mixin_params[class << a; self ; end]
+            if q[m] && q[m].key?(n)
+              r = q[m][n]
+            else
+              q.each do |k,v|
+                h.update(v)
+              end
+            end
+          end
+        end
+        r ? r : h[n]
+      end
     end
 
   end
 
 end
 
-
+#
 class Module
 
-  # Store for parametric mixin parameters.
-  #
-  # Returns a hash, the keys of which are the parametric mixin module
-  # and the values are the parameters associacted with this module/class.
-  #
-  #   class C
-  #     include P(:x=>1)
-  #   end
-  #
-  #   C.mixin_parameters[P]   #=> {:x=>1}
-  #
   def mixin_parameters
-    @mixin_parameters ||= {}
+    @mixin_params ||= {}
   end
 
   alias_method :mixin_params, :mixin_parameters
 
 end
 
+module Kernel
+  def meta_class
+    (class << self; self; end)
+  end
+end

data/meta/version

@@ -1 +1 @@
-1.0.1
+1.1.0

data/test/nested/test_nested_both.rb

@@ -0,0 +1,44 @@
+require 'paramix'
+require 'test/unit'
+
+class TC_Paramix_Nested_Both < Test::Unit::TestCase
+
+  # -- fixture ------------------------------
+
+  module M
+    include Paramix
+
+    def f
+      mixin_param(M,:p)
+    end
+  end
+
+  module N
+    include Paramix
+    include M[:p=>"mood"]
+
+    def g
+      mixin_params(N,:p)
+    end
+  end
+
+  class I
+    include N[:p => "mosh"]
+  end
+
+  class E
+    extend N[:p => "many"]
+  end
+
+  # -- tests --------------------------------
+
+  def test_include
+    assert_equal( "mood", I.new.f )
+  end
+
+  #def test_extend
+  #  assert_equal( "many", E.f )
+  #end
+
+end
+

data/test/nested/test_nested_bottom.rb

@@ -0,0 +1,51 @@
+require 'paramix'
+require 'test/unit'
+
+class TC_Paramix_Nested_Bottom < Test::Unit::TestCase
+
+  # -- fixture ------------------------------
+
+  module M
+    include Paramix
+
+    def f
+      mixin_param(M,:p)
+    end
+  end
+
+  module N
+    include M
+
+    def g
+      mixin_param(N,:p)
+    end
+  end
+
+  class I
+    include N[:p => "mosh"]
+  end
+
+  class E
+    extend N[:p => "many"]
+  end
+
+  # -- tests --------------------------------
+
+  def test_include_f
+    assert_equal( "mosh", I.new.f )
+  end
+
+  def test_include_g
+    assert_equal( "mosh", I.new.g )
+  end
+
+  def test_extend_f
+    assert_equal( "many", E.f )
+  end
+
+  def test_extend_g
+    assert_equal( "many", E.g )
+  end
+
+end
+

data/test/nested/test_nested_top.rb

@@ -0,0 +1,47 @@
+require 'paramix'
+require 'test/unit'
+
+class TC_Paramix_Nested_Top < Test::Unit::TestCase
+
+  # -- fixture ------------------------------
+
+  module M
+    include Paramix
+
+    def f
+      mixin_param(M,:p)
+    end
+  end
+
+  module N
+    include M[:p=>"mood"]
+
+    def g
+      mixin_param(N,:p)
+    end
+  end
+
+  class I
+    include N
+  end
+
+  class E
+    extend N
+  end
+
+  # -- tests --------------------------------
+
+  def test_include_f
+    assert_equal( "mood", I.new.f )
+  end
+
+  def test_include_g
+    assert_equal( nil, I.new.g ) # TODO: or error ?
+  end
+
+  #def test_extend
+  #  assert_equal( "many", E.f )
+  #end
+
+end
+

data/test/test_paramix_callback.rb

@@ -3,53 +3,56 @@ require 'test/unit'
 
 class TC_Paramix_Callback < Test::Unit::TestCase
 
+  # -- fixture ------------------------------
+
   module M
     include Paramix
 
     def f
-      mixin_params[M][:p]
+      mixin_param(M,:p)
     end
 
+    #
     def self.included(base)
-      params = base.mixin_params[self]
       base.class_eval do
-        define_method :check do
-          params
-        end
+        attr_accessor mixin_parameters[M][:p]
       end
+      super(base)
     end
   end
 
-  class C
-    include M[:p => "check"]
+  class C1
+    include M[:p => "c1"]
   end
 
-  class D
-    include M[:p => "steak"]
+  class C2
+    include M[:p => "c2"]
   end
 
-  def test_01_001
-    c = C.new
-    assert_equal( "check", c.mixin_params[M][:p] )
-    assert_equal( "check", c.f )
+  # -- tests --------------------------------
+
+  def test_class_1
+    c = C1.new
+    #assert_equal( "c1", c.mixin_params[:p] )
+    assert_equal( "c1", c.f )
   end
 
-  def test_01_002
-    d = D.new
-    assert_equal( "steak", d.mixin_params[M][:p] )
-    assert_equal( "steak", d.f )
+  def test_class_2
+    c = C2.new
+    #assert_equal( "c2", c.mixin_params[:p] )
+    assert_equal( "c2", c.f )
   end
 
-  def test_01_003
-    assert_equal( {M=>{:p => "check"}}, C.mixin_parameters )
-    assert_equal( {M=>{:p => "steak"}}, D.mixin_parameters )
+  def test_callback_class_1
+    c = C1.new
+    c.c1 = :yes1
+    assert_equal(:yes1, c.c1)
   end
 
-  def test_01_004
-    c = C.new
-    assert_equal( {:p => "check"}, c.check )
-    d = D.new
-    assert_equal( {:p => "steak"}, d.check )
+  def test_callback_class_2
+    c = C2.new
+    c.c2 = :yes2
+    assert_equal(:yes2, c.c2)
   end
 
 end

data/test/test_paramix_extend.rb

@@ -0,0 +1,35 @@
+require 'paramix'
+require 'test/unit'
+
+class TC_Paramix_Extend < Test::Unit::TestCase
+
+  # -- fixture ------------------------------
+
+  module M
+    include Paramix
+
+    def f
+      mixin_param(M,:p)
+    end
+  end
+
+  class C1
+    extend M[:p => "mosh"]
+  end
+
+  class C2
+    extend M[:p => "many"]
+  end
+
+  # -- tests --------------------------------
+
+  def test_class_1
+    assert_equal( "mosh", C1.f )
+  end
+
+  def test_class_2
+    assert_equal( "many", C2.f )
+  end
+
+end
+

data/test/test_paramix_include.rb

@@ -0,0 +1,35 @@
+require 'paramix'
+require 'test/unit'
+
+class TC_Paramix_Include < Test::Unit::TestCase
+
+  # -- fixture ------------------------------
+
+  module M
+    include Paramix
+
+    def f
+      mixin_param(M,:p)
+    end
+  end
+
+  class C1
+    include M[:p => "mosh"]
+  end
+
+  class C2
+    include M[:p => "many"]
+  end
+
+  # -- tests --------------------------------
+
+  def test_class_1
+    assert_equal( "mosh", C1.new.f )
+  end
+
+  def test_class_2
+    assert_equal( "many", C2.new.f )
+  end
+
+end
+

data/test/test_paramix_inject.rb

@@ -1,63 +1,14 @@
 require 'paramix'
 require 'test/unit'
 
-class TC_Paramix_02 < Test::Unit::TestCase
+class TC_Paramix_Inject < Test::Unit::TestCase
 
-  module M
-    # Manually define Paramix method.
-    def self.[](parameters)
-      Paramix.new(self, parameters) do
-        define_method :check do
-          mixin_params[M] # or parameters
-        end
-      end
-    end
-
-    def f
-      mixin_params[M][:p]
-    end
-  end
-
-  class C
-    include M[:p => "check"]
-  end
-
-  class D
-    include M[:p => "steak"]
-  end
-
-  def test_02_001
-    c = C.new
-    assert_equal( "check", c.mixin_params[M][:p] )
-    assert_equal( "check", c.f )
-  end
-
-  def test_02_002
-    d = D.new
-    assert_equal( "steak", d.mixin_params[M][:p] )
-    assert_equal( "steak", d.f )
-  end
-
-  def test_02_003
-    assert_equal( {M=>{:p => "check"}}, C.mixin_parameters )
-    assert_equal( {M=>{:p => "steak"}}, D.mixin_parameters )
-  end
-
-  def test_02_004
-    c = C.new
-    assert_equal( {:p => "check"}, c.check )
-    d = D.new
-    assert_equal( {:p => "steak"}, d.check )
-  end
-
-end
-
-class TC_Paramix_04 < Test::Unit::TestCase
+  # -- fixture ------------------------------
 
   module O
     def self.[](parameters)
-      Paramix.new(self, parameters) do
-        attr_accessor mixin_parameters[O][:name]
+      Paramix::Proxy.new(self, parameters) do
+        attr_accessor mixin_parameters[O][:name] #mixin_params(O, :name)
       end
     end
   end
@@ -66,6 +17,8 @@ class TC_Paramix_04 < Test::Unit::TestCase
     include O[:name=>"x"]
   end
 
+  # -- tests --------------------------------
+
   def test_attribute
     o = X.new
     assert_nothing_raised{ o.x = 10 }

data/test/test_paramix_namespace.rb

@@ -1,39 +1,38 @@
 require 'paramix'
 require 'test/unit'
 
-class TC_Paramix_Basic < Test::Unit::TestCase
+class TC_Paramix_Namespace < Test::Unit::TestCase
 
-  module Q1
+  # -- fixture ------------------------------
+
+  module N1
     module M
       include Paramix
 
       def f
-        mixin_params[M][:p]
+        mixin_param(M,:p)
       end
     end
   end
 
-  module Q2
-    class C
-      extend Q1::M[:p => "mosh"]
+  module N2
+    class I
+      include N1::M[:p => "mosh"]
     end
 
-    class D
-      extend Q1::M[:p => "many"]
+    class E
+      extend N1::M[:p => "many"]
     end
   end
 
-  def test_03_001
-    assert_equal( "mosh", Q2::C.f )
-  end
+  # -- tests --------------------------------
 
-  def test_03_002
-    assert_equal( "many", Q2::D.f )
+  def test_class_1
+    assert_equal( "mosh", N2::I.new.f )
   end
 
-  def test_03_003
-    assert_equal( {Q1::M=>{:p => "mosh"}}, (class << Q2::C; self; end).mixin_parameters )
-    assert_equal( {Q1::M=>{:p => "many"}}, (class << Q2::D; self; end).mixin_parameters )
+  def test_class_2
+    assert_equal( "many", N2::E.f )
   end
 
 end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
-  - 0
   - 1
-  version: 1.0.1
+  - 0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Thomas Sawyer
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-03 00:00:00 -04:00
+date: 2010-04-05 00:00:00 -04:00
 default_executable: 
 dependencies: []
 
@@ -42,14 +42,17 @@ files:
 - meta/summary
 - meta/title
 - meta/version
-- test/test_paramix_basic.rb
+- test/nested/test_nested_both.rb
+- test/nested/test_nested_bottom.rb
+- test/nested/test_nested_top.rb
 - test/test_paramix_callback.rb
+- test/test_paramix_extend.rb
+- test/test_paramix_include.rb
 - test/test_paramix_inject.rb
 - test/test_paramix_namespace.rb
 - LICENSE
 - README.rdoc
 - HISTORY
-- Syckfile
 has_rdoc: true
 homepage: http://rubyworks.github.com/paramix
 licenses: []
@@ -82,7 +85,11 @@ signing_key:
 specification_version: 3
 summary: Parametric Mixins
 test_files: 
-- test/test_paramix_basic.rb
+- test/nested/test_nested_both.rb
+- test/nested/test_nested_bottom.rb
+- test/nested/test_nested_top.rb
 - test/test_paramix_callback.rb
+- test/test_paramix_extend.rb
+- test/test_paramix_include.rb
 - test/test_paramix_inject.rb
 - test/test_paramix_namespace.rb

data/Syckfile

@@ -1,79 +0,0 @@
----
-announce:
-  service : Email
-  file    : ~
-  subject : ~
-  mailto  : ruby-talk@ruby-lang.org
-  active  : true
-
-box:
-  service: Box
-  active : true
-  types  : [gem, tar]
-  include: [bin, demo, lib, meta, test, "[A-Z]*"]
-  exclude: ~
-
-rdoc:
-  service  : RDoc
-  template : redfish
-  include  : ~
-  exclude  : ~
-  main     : ~
-  extra    : ~
-  active   : true
-
-ridoc:
-  service: RIDoc
-  include: ~
-  exclude: ~
-  active : true
-
-notes:
-  service  : DNotes
-  loadpath : ~
-  labels   : ~
-  output   : ~
-  format   : ~
-  active   : false
-
-stats:
-  service  : Stats
-  title    : ~
-  loadpath : ~
-  exclude  : ~
-  output   : ~
-  active   : true
-
-testrb:
-  service  : testrb
-  tests    : ~
-  exclude  : ~
-  loadpath : ~
-  requires : ~
-  live     : false   
-  active   : true
-
-syntax:
-  service  : Syntax
-  loadpath : ~
-  exclude  : ~
-  active   : false
-
-vclog:
-  service  : VClog
-  format   : html   # xml, txt
-  layout   : rel    # gnu
-  typed    : false
-  output   : ~
-  active   : false
-
-
-#rubyforge:
-#  service : Rubyforge
-#  unixname: <%= project %>
-#  groupid : ~
-#  package : <%= package %>
-#  sitemap:
-#    doc/rdoc: <%= package %>
-#  active  : false
-

data/test/test_paramix_basic.rb

@@ -1,36 +0,0 @@
-require 'paramix'
-require 'test/unit'
-
-class TC_Paramix_Basic < Test::Unit::TestCase
-
-  module M
-    include Paramix
-
-    def f
-      mixin_params[M][:p]
-    end
-  end
-
-  class C
-    extend M[:p => "mosh"]
-  end
-
-  class D
-    extend M[:p => "many"]
-  end
-
-  def test_03_001
-    assert_equal( "mosh", C.f )
-  end
-
-  def test_03_002
-    assert_equal( "many", D.f )
-  end
-
-  def test_03_003
-    assert_equal( {M=>{:p => "mosh"}}, (class << C; self; end).mixin_parameters )
-    assert_equal( {M=>{:p => "many"}}, (class << D; self; end).mixin_parameters )
-  end
-
-end
-