facets 1.1.0 → 1.2.0

data/lib/facets/more/classinherit.rb

@@ -0,0 +1,216 @@
+#--
+# ClassInherit
+#
+# Copyright (c) 2005 Thomas Sawyer
+#
+# 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.
+#
+# ==========================================================================
+#  REVISION HISTORY
+# ==========================================================================
+#  2005-11-29 trans
+#    Version "2.0". Improved by adopting old #class_inherit functionality
+#    as well, i.e. ClassInherit module now will be inherited down
+#    the Hierarchy chain.
+#
+#  2005-04-28 trans
+#    Reimplemented for Calibre based on Nabu's ClassMethods work.
+# ==========================================================================
+#
+# CREDIT Credit is due Nobu and Ulysses.
+#
+#++
+
+#:title: ClassInherit
+#
+# This framework provides a very convenient way to have modules
+# pass along class methods in the inheritance chain.
+#
+# Presently in Ruby the class/module methods of a module
+# are not inherited when a module is included --contrary to
+# the behavior of classes themselves when they are subclassed.
+# To achieve the same behavior with modules requires some clever
+# Ruby karate. ClassInherit provides a nice solution.
+# Simply place the class inheritable methods in the block 
+# parameter of the special module method ClassInherit.
+#
+#   module Mix
+#     def inst_meth
+#       puts 'inst_meth'
+#     end
+#
+#     ClassInherit do
+#       def class_meth
+#         "Class Method!"
+#       end
+#     end
+#   end
+#
+#   class X
+#     include Mix
+#   end
+#
+#   X.class_meth  #=> "Class Method!"
+#
+# ClassInherit is a capitalized method. This is used because it
+# indeed creates (or reopens) a ClassInherit module in which
+# the given block is evaluated, then the ClassInherit module
+# is extended against the current module.
+#
+# The above is actually equivalent to putting the class/module 
+# methods in a nested ClassInherit module and extending the
+# module _manually_, eg.
+#
+#   module Mix
+#     def inst_meth
+#       puts 'inst_meth'
+#     end
+#
+#     module ClassInherit
+#       def class_meth
+#         "Class Method!"
+#       end
+#     end
+#
+#     extend ClassInherit
+#   end
+#
+#   class X
+#     include Mix
+#   end
+#
+#   X.class_meth  #=> "Class Method!"
+#
+# Lastly, #class_inherit is an available alias for #ClassInherit
+# if you prefer only lowercase methods.
+#
+# == Notes
+#
+# Just a quick comment on the need for this behavior.
+#
+# A module is an encapsulation of code, hence when a module is included
+# (or extends), the module itself should have discretion over how it
+# effects the receiving class/module. That is the very embodiment of
+# encapsulation. Having it otherwise, as Ruby now does, stymies the
+# practice --and we end up with "hacks" like this to compensate.
+#
+# Ruby would be much improved by making this bevaivor standard.
+# And making non-inheritance the exception, which is alwasy easy
+# enough to achieve: just put the code in a separate
+# (and thus uninherited) module.
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+# * Nobu Nakada
+# * Ulysses
+#
+
+class Module
+
+  alias_method :append_features_without_classinherit, :append_features
+
+  def append_features( base )
+    result = append_features_without_classinherit( base )
+    if const_defined?( :ClassInherit )
+      base.extend( self::ClassInherit )
+      unless base.is_a?( Class )
+        unless base.const_defined?( :ClassInherit )
+          base.const_set( :ClassInherit, Module.new )
+        end
+        my = self
+        base::ClassInherit.class_eval do
+          include my::ClassInherit
+        end
+      end
+    end
+    result
+  end
+
+  def ClassInherit( &yld )
+    if const_defined?( :ClassInherit )
+      self::ClassInherit.class_eval( &yld )
+    else
+      self.const_set( :ClassInherit, Module.new( &yld ) )
+    end
+    extend( self::ClassInherit )
+    self::ClassInherit
+  end
+
+  # For compatibility with old rendition
+  alias_method :class_inherit, :ClassInherit
+
+end
+
+class Class
+  undef_method :ClassInherit
+  undef_method :class_inherit
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin test
+
+  require 'test/unit'
+
+  class TC_ClassInherit < Test::Unit::TestCase
+
+    # fixture
+
+    module N
+      ClassInherit do
+        def n ; 43 ; end
+      end
+      #extend ClassInherit
+    end
+
+    class X
+      include N
+      def n ; 11 ; end
+    end
+
+    module K
+      include N
+      ClassInherit do
+        def n ; super + 1 ; end
+      end
+    end
+
+    class Z
+      include K
+    end
+
+    # tests
+
+    def test_01
+      assert_equal( 43, N.n )
+    end
+    def test_02
+      assert_equal( 43, X.n )
+    end
+    def test_03
+      assert_equal( 11, X.new.n )
+    end
+    def test_04
+      assert_equal( 44, K.n )
+    end
+    def test_05
+      assert_equal( 44, Z.n )
+    end
+
+  end
+
+=end

data/lib/facets/more/classmethods.rb

@@ -0,0 +1,219 @@
+#--
+# ClassMethods
+#
+# Copyright (c) 2005 Thomas Sawyer
+#
+# 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.
+#
+# ==========================================================================
+#  REVISION HISTORY
+# ==========================================================================
+#  2005-11-29 trans
+#  Version "2.0". Improved by adopting old #class_inherit functionality
+#  as well, i.e. ClassMethods module now will be inherited down
+#  the Hierarchy chain.
+#
+#  2005-04-28 trans
+#  Reimplemented for Calibre based on Nabu's work.
+# ==========================================================================
+#
+# CREDIT Credit is due Nobu and Ulysses.
+#
+#++
+
+#:title: ClassMethods
+#
+# Miniframework provides a very convenient way to have modules
+# pass along class methods in the inheritance chain.
+#
+# An oddity of Ruby, when including modules, class/module methods
+# are not inherited. To achieve this behavior requires some clever
+# Ruby Karate. Instead ClassMethods provides an easy to use and clean
+# solution. Simply place the class inheritable methods in a block of
+# the special module method #ClassMetods.
+#
+#   module Mix
+#     def inst_meth
+#       puts 'inst_meth'
+#     end
+#
+#     ClassMethods do
+#       def class_meth
+#         "Class Method!"
+#       end
+#     end
+#   end
+#
+#   class X
+#     include Mix
+#   end
+#
+#   X.class_meth  #=> "Class Method!"
+#
+# ClassMethods is a capitalized method. This is used because it
+# indeed creates (or reopens) a ClassMethods module in which
+# the given block is evaluated, then the ClassMethods module
+# is extended against the current module.
+#
+# This is equivalent to the older (but still functional) techinique of
+# putting the class/module methods in a nested ClassMethods module
+# and extending the original module *manually*. Eg.
+#
+#   module Mix
+#     def inst_meth
+#       puts 'inst_meth'
+#     end
+#
+#     module ClassMethods
+#       def class_meth
+#         "Class Method!"
+#       end
+#     end
+#
+#     extend ClassMethods
+#   end
+#
+#   class X
+#     include Mix
+#   end
+#
+#   X.class_meth  #=> "Class Method!"
+#
+# Lastly, note that #class_inherit is an available alias
+# for #ClassMethods for the sake of backward compatability
+# or if you just insist on using only lowercase methods.
+#
+# == Notes
+#
+# Just a quick comment on the need for this behavior.
+#
+# A module is an encapsulation of code, hence when a module is included
+# (or extends), the module itself should have discretion over how it
+# effects the receiving class/module. That is the very embodiment of
+# encapsulation. Having it otherwise, as Ruby now does, stymies the
+# practice --and we end up with "hacks", like this and ClassMethods,
+# to compensate.
+#
+# Ruby would be much improved by making this bevaivor standard.
+# And making non-inheritance the exception, which is alwasy easy
+# enough to achieve: put the code in a separate (and thus uninherited)
+# module.
+#
+# == Author(s)
+#
+# * Thomas Sawyer
+# * Nobu Nakada
+# * Ulysses
+#
+
+class Module
+
+  alias_method :append_features_without_classmethods, :append_features
+
+  def append_features( base )
+    result = append_features_without_classmethods( base )
+    if const_defined?( :ClassMethods )
+      base.extend( self::ClassMethods )
+      unless base.is_a?( Class )
+        unless base.const_defined?( :ClassMethods )
+          base.const_set( :ClassMethods, Module.new )
+        end
+        my = self
+        base::ClassMethods.class_eval do
+          include my::ClassMethods
+        end
+      end
+    end
+    result
+  end
+
+  def ClassMethods( &yld )
+    if const_defined?( :ClassMethods )
+      self::ClassMethods.class_eval( &yld )
+    else
+      self.const_set( :ClassMethods, Module.new( &yld ) )
+    end
+    extend( self::ClassMethods )
+    self::ClassMethods
+  end
+
+  # If you prefer not using a capitalized method
+  alias_method :class_methods, :ClassMethods
+
+  # For compatibility with old rendition
+  alias_method :class_inherit, :ClassMethods
+
+end
+
+class Class
+  undef_method :ClassMethods
+  undef_method :class_inherit
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin test
+
+  require 'test/unit'
+
+  class TC_ClassMethods < Test::Unit::TestCase
+
+    # fixture
+
+    module N
+      ClassMethods do
+        def n ; 43 ; end
+      end
+      #extend ClassMethods
+    end
+
+    class X
+      include N
+      def n ; 11 ; end
+    end
+
+    module K
+      include N
+      ClassMethods do
+        def n ; super + 1 ; end
+      end
+    end
+
+    class Z
+      include K
+    end
+
+    # tests
+
+    def test_01
+      assert_equal( 43, N.n )
+    end
+    def test_02
+      assert_equal( 43, X.n )
+    end
+    def test_03
+      assert_equal( 11, X.new.n )
+    end
+    def test_04
+      assert_equal( 44, K.n )
+    end
+    def test_05
+      assert_equal( 44, Z.n )
+    end
+
+  end
+
+=end

data/lib/facets/more/cloneable.rb

@@ -0,0 +1,55 @@
+#--
+# Cloneable (ported from Rake)
+#
+# Copyright (c) 2003, 2004 Jim Weirich
+#
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+#
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#++
+
+# :title: Cloneable
+#
+# Stadard basis for adding #dup and #clone methods to a class.
+#
+#--
+# TODO #clone should copy ad-hoc methods in contrast to #dup.
+#++
+
+module Cloneable
+  def clone
+    sibling = self.class.new
+    instance_variables.each do |ivar|
+      value = self.instance_variable_get(ivar)
+      sibling.instance_variable_set(ivar, value.rake_dup)
+    end
+    sibling
+  end
+  alias_method :dup, :clone
+end
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+=begin #test
+=end