mixin 0.4.1 → 0.7.0

data/README

@@ -1,6 +1,97 @@
-Mixin by Hersch Stevenson (xain)
+= Mixin - mixins made classier.
 
-http://rdoc.persapient.com/mixin
+Mixin extends Ruby's +Module+ class with a small, yet powerful set of features
+that make the experience of writing mixins more like that of writing classes
+when it comes to defining class methods.
 
+Typically, the way to implement a mixin that defines class methods for its
+includees (at least that I have noticed) is to define a module within the mixin
+module, usually called +ClassMethods+, which gets automatically extended to an
+including class by overwriting the mixin's +inherited+ method. This technique
+is usually sufficient for most situations, but it has a few limitations. One of
+these is the fact that class attributes referenced in +ClassMethods+ do not
+exist in the same scope as the enclosing mixin's class attributes.
 
-This must be an early beta version.
+=== When to use it
+
+Mixin comes in handy in following situations:
+
+* When you are writing a mixin with class methods that need to access class
+  attributes defined within the mixin module.
+
+* When you want to define a "sub-mixin" module which includes another mixin
+  in order to expand upon its class methods in addition to its instance methods
+  (similar to defining a hierarchy of abstract base classes). This includes calls
+  to +super+ to invoke a "super-mixin's" implementation of a given class method.
+
+* When you wish that certian module methods would get 'inherited' by including
+  modules in the same manner that class methods get inherited by subclasses.
+
+* When you simply get tired of writing the same old "<tt>def self.inherited(base);
+  base.extend(ClassMethods)</tt>" method (or some variation of it) over and over
+  again, thereby violating the sacred DRY principle ;)
+
+== Example
+
+  require 'mixin'
+
+  module FooBase
+    @@foo_class_attr = "FooBase's class attribute"
+
+    class_mixin do
+
+      def foo_class_method
+        @@foo_class_attr + " accessed from FooBase's class mixin"
+      end
+
+    end
+  end
+
+
+  module FooExtended
+    include FooBase
+
+    class_mixin do
+
+      def another_foo_class_method
+        @@foo_class_attr + " accessed from FooExtended's class mixin"
+      end
+
+    end
+  end
+
+
+  class FooBar
+    include FooExtended
+  end
+
+  FooBar.foo_class_method         -> "FooBase's class attribute accessed from FooBase's class mixin"
+  FooBar.another_foo_class_method -> "FooBase's class attribute accessed from FooExtended's class mixin"
+
+
+== Extra Stuff
+
+As briefly mentioned above, Mixin also provides a way to define module methods
+on a mixin that get 'inherited' by including modules, but that are not extended
+to classes. The semantics for defining such methods are identical to defining
+class methods via +_class_mixin_+ (see +module_mixin+).
+
+Also packaged with Mixin is the bonus mixin Metable which provides a fistful
+of useful metaprogramming-friendly methods such as +alias_singleton_method+ and
++define_class_method+.
+
+== Installation
+
+  % sudo gem install mixin
+
+== License[link://files/LICENSE.html]
+
+Copyright (c) 2008 Christian Herschel Stevenson, Persapient Systems. Released
+under the same license[link://files/LICENSE.html] as Ruby.
+
+== Support
+
+You're pretty much looking at it.
+
+For more information, contact mailto:stevenson@persapient.com. This documentation
+can be found online at http://api.persapient.com/mixin

data/lib/metable.rb

@@ -17,43 +17,34 @@ require 'mixin'
 #
 # === Public Instance Methods
 # * eigen_eval
-# * eigenclass
-# * metaclass
+# * eigenclass <em>(aliased as metaclass)</em>
 # * private_singleton_method
 # * protected_singleton_method
 # * public_singleton_method
 #
 # === Private Instance Methods
 # * alias_singleton_method
-# * define_singleton_method
+# * define_singleton_method <em>(aliased as define_public_singleton_method)</em>
 # * define_private_singleton_method
 # * define_protected_singleton_method
-# * define_public_singleton_method
 #
 # === Public Module Mixin & Class Mixin Methods
 # * class_method_defined?
 # * eigen_eval
-# * eigenclass
-# * metaclass
+# * eigenclass <em>(aliased as metaclass)</em>
 # * private_class_method_defined?
 # * private_singleton_method
 # * protected_class_method
 # * protected_class_method_defined?
-# * protected_singleton_method
+# * protected_singleton_method <em>(aliased as protected_class_method)</em>
 # * public_class_method_defined?
 # * public_singleton_method
 #
 # === Private Module Mixin & Class Mixin Methods
-# * alias_class_method
-# * alias_singleton_method
-# * define_class_method
-# * define_singleton_method
-# * define_private_class_method
-# * define_private_singleton_method
-# * define_protected_class_method
-# * define_protected_singleton_method
-# * define_public_class_method
-# * define_public_singleton_method
+# * alias_singleton_method <em>(aliased as alias_class_method)</em>
+# * define_singleton_method <em>(aliased as define_class_method, define_public_class_method, define_public_singleton_method)</em>
+# * define_private_singleton_method <em>(aliased as define_private_class_method)</em>
+# * define_protected_singleton_method <em>(aliased as define_protected_class_method)</em>
 # * enclosed_attr
 # * private_enclosure
 # * protected_enclosure
@@ -61,6 +52,6 @@ require 'mixin'
 #
 module Metable
   include Metable::InstanceMethods
-  extend_class_mixin Metable::ClassMethods
-  extend_module_mixin Metable::ClassMethods
+  class_extend Metable::ClassMethods
+  module_extend Metable::ClassMethods
 end

data/lib/mixin.rb

@@ -1,9 +1,6 @@
 require 'metable/class_methods'
 
 
-# Mixin is an extension to +Module+ that is intended to ease the development
-# of mixins that involve both class and instance methods.
-#
 module Mixin
   include Metable::InstanceMethods
   extend Metable::ClassMethods
@@ -33,7 +30,7 @@ module Mixin
   # Extends the given modules to the classes that subsequently include the
   # invoking module or one of its submodules.
   #
-  # Calling <tt>SomeMixin.extend_class_mixin(SomeClassMethods)</tt>
+  # Calling <tt>SomeMixin.class_extend(SomeClassMethods)</tt>
   # would be equivalent to:
   #
   #   module SomeMixin
@@ -42,15 +39,15 @@ module Mixin
   #     end
   #   end
   #
-  def extend_class_mixin(*modules)
+  def class_extend(*modules)
     class_mixin { include *modules }
   end
 
 
-  # Works like +extend_class_mixin+ except that the given modules are instead
+  # Works like +class_extend+ except that the given modules are instead
   # extended to the invoking module and the modules that subsequently include
   # it rather than their including classes.
-  def extend_module_mixin(*modules)
+  def module_extend(*modules)
     module_mixin { include *modules }
   end
 
@@ -132,8 +129,8 @@ module Mixin
     if submodule.kind_of?(Class) || submodule.kind_of?(SingletonMixin)
       submodule.extend __class_mixin__
     else
-      submodule.extend_module_mixin __module_mixin__
-      submodule.extend_class_mixin __class_mixin__
+      submodule.module_extend __module_mixin__
+      submodule.class_extend __class_mixin__
     end
     super
   end
@@ -142,7 +139,7 @@ end
 
 
 
-[:module_mixin, :extend_module_mixin, :class_mixin, :extend_class_mixin].each do |name|
+[:module_mixin, :module_extend, :class_mixin, :class_extend].each do |name|
   Module.class_eval %Q{
     def #{name}(*args, &block)
       extend ::Mixin

data/test/mixin_case.rb

@@ -124,8 +124,8 @@ class MixinTest < Test::Unit::TestCase
     assert_same :cls_mxn_ping, Xtended.ping
     assert_same :cls_mxn_ping, Xtendedr.ping
 
-    Xtendr.extend_module_mixin Plain
-    Xtendr.extend_class_mixin Plain
+    Xtendr.module_extend Plain
+    Xtendr.class_extend Plain
 
     assert_same :vanilla, Xtendr.flavor
     assert_no_response Xtendrer, :flavor
@@ -194,7 +194,7 @@ class MixinTest < Test::Unit::TestCase
     assert SansMxn.private_methods.include?('module_mixin')
     assert SansMxn.private_methods.include?('class_mixin')
     assert !SansMxn.kind_of?(Mixin)
-    SansMxn.extend_class_mixin Module.new
+    SansMxn.class_extend Module.new
     assert_kind_of Mixin, SansMxn
   end
 

data/test/test_subjects/clevers.rb

@@ -1,5 +1,5 @@
 module Clever
-  extend_module_mixin class_mixin
+  module_extend class_mixin
 
   class_mixin do
     def trick?
@@ -10,8 +10,8 @@ end
 
 
 module Deft
-  extend_module_mixin self
-  extend_class_mixin self
+  module_extend self
+  class_extend self
 
   def technique?
     true

data/test/test_subjects/extenders.rb

@@ -2,8 +2,8 @@ require 'nudgers'
 
 
 module Xtendr
-  extend_module_mixin ModNudgr
-  extend_class_mixin ClsNudgr
+  module_extend ModNudgr
+  class_extend ClsNudgr
 
   module_mixin do
     def ping

data/test/test_subjects/sleepers.rb

@@ -2,11 +2,11 @@ module SansMxn
 end
 
 module LazyModExt
-  extend_module_mixin SansMxn
+  module_extend SansMxn
 end
 
 module LazyClsExt
-  extend_class_mixin SansMxn
+  class_extend SansMxn
 end
 
 module LazyModMxn

data/test/test_subjects/soopers.rb

@@ -12,7 +12,7 @@ end
 
 
 module Soopr1
-  extend_module_mixin SooprMX
+  module_extend SooprMX
 
   module_mixin do
     def giv_er
@@ -93,7 +93,7 @@ end
 
 module Soopr4
   include Soopr3
-  extend_class_mixin DooprCX
+  class_extend DooprCX
 
   class_mixin do
     def giv_em

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: mixin
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.7.0
 platform: ruby
 authors: 
 - Hersch Stevenson (xian)
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2008-09-08 00:00:00 -07:00
+date: 2008-09-09 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -27,21 +27,21 @@ files:
 - lib/metable/class_methods.rb
 - lib/mixin.rb
 - lib/metable.rb
-- test/test_subjects/scopers.rb
-- test/test_subjects/meepers.rb
+- test/mixin_case.rb
 - test/test_subjects/extenders.rb
-- test/test_subjects/sleepers.rb
+- test/test_subjects/scopers.rb
 - test/test_subjects/hopons.rb
+- test/test_subjects/meepers.rb
 - test/test_subjects/nudgers.rb
 - test/test_subjects/includers.rb
 - test/test_subjects/soopers.rb
+- test/test_subjects/sleepers.rb
 - test/test_subjects/clevers.rb
-- test/mixin_case.rb
 - README
 - LICENSE
 - Rakefile
 has_rdoc: true
-homepage: http://www.persapient.com/mixin
+homepage: http://api.persapient.com/mixin
 post_install_message: 
 rdoc_options: []
 
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: mixin
-rubygems_version: 1.2.0
+rubygems_version: 1.0.1
 signing_key: 
 specification_version: 2
 summary: An extention to Module that is intended to ease the development of mixins that involve both class and instance methods.