clafamatt 1.0.0

data/#README.rdoc#

@@ -0,0 +1,119 @@
+clafamatt
+    by Avdi Grimm
+    http://clafamatt.rubyforge.org
+
+== DESCRIPTION:
+
+ClaFamAtt (CLAss FAMily ATTributes) gives you class inheritable attributes
+without all that tedious mucking about with +@inheritable_attributes+.
+
+== FEATURES
+
+* Fully Spec'd
+* reader/writer methods are cleanly partitioned in dynamically created modules
+* No extra class variables needed for bookkeeping
+* Reader/writer methods are defined once and only once no matter how many classes 
+  inherit them
+* Family inheritable attributes can be defined in modules
+* Will not pollute the global namespace.
+
+== SYNOPSIS:
+
+  module Shared
+    include Clafamatt::Macros
+
+    class_family_accessor :foo
+  end
+
+  class Parent
+    include Shared
+
+  end
+
+  class Child < Parent
+    class_family_accessor :bar
+  end
+
+  Shared.foo                      # => nil
+  Parent.foo                      # => nil
+  Child.foo                       # => nil
+
+  Shared.foo = "klaatu"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "klaatu"
+  Child.foo                       # => "klaatu"
+
+  Parent.foo = "nikto"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "nikto"
+  Child.foo                       # => "nikto"
+
+  Child.foo = "barada"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "nikto"
+  Child.foo                       # => "barada"
+
+  Child.bar = "klaatu"
+  Child.bar                       # => "klaatu"
+  Parent.bar                      # => 
+  # ~> -:38: undefined method `bar' for Parent:Class (NoMethodError)
+
+== RATIONALE:
+
+Clafamatt sprung from a desire to have ActiveSupport-style class inheritable
+attributes without having all of ActiveSupport come with it.  It is also an
+attempt to implement class-inheritable attributes in the cleanest way possible.
+
+In contrast to the ActiveSupport version, which writes reader/writer methods
+directly into the class being extended, Clafamatt writes it's readers and
+writers into a dynamically created module which is then inserted into the class'
+(or module's) singleton class.  Among other benefits, this enables Clafamatt to
+transparently support defining inheritable attributes in either classes or
+modules.
+
+The ActiveSupport version keeps inheritable attribute values in a class-level
+@inheritable_attributes variable, which it copies whenever a new class is
+inherited.  Clafamatt stays closer to Ruby conventions by storing each
+attribute's value in a correspondingly-named class instance variable - so
+e.g. <code>Foo.bar = 42</code> will set the <code>@bar</code> instance variable.
+This is consistent with how Ruby's built-in attr_* macros behave.  Beyond the
+variables used to store values, Clafamatt needs *zero* class instance variables
+for internal bookeeping.  It also doesn't copy variables on inheritance;
+instead, it simply re-uses values from farther up the inheritance chain until an
+attribute is explicitly set.
+
+Finally, Clafamatt is only there when you ask for it, by including
+Clafamatt::Macros.  It will not pollute the global namespace.
+
+== REQUIREMENTS:
+
+* Ruby!
+
+== INSTALL:
+
+  sudo gem install clafamatt
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Avdi Grimm
+
+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.

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2008-12-14
+
+* 1 major enhancement
+  * Birthday!

data/Manifest.txt

@@ -0,0 +1,24 @@
+#README.rdoc#
+History.txt
+Manifest.txt
+README.rdoc
+Rakefile
+bin/clafamatt
+examples/synopsys.rb
+lib/clafamatt.rb
+spec/clafamatt_spec.rb
+spec/spec_helper.rb
+tasks/ann.rake
+tasks/bones.rake
+tasks/gem.rake
+tasks/git.rake
+tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake
+tasks/test.rake
+test/test_clafamatt.rb

data/README.rdoc

@@ -0,0 +1,119 @@
+clafamatt
+    by Avdi Grimm
+    http://clafamatt.rubyforge.org
+
+== DESCRIPTION:
+
+ClaFamAtt (CLAss FAMily ATTributes) gives you class inheritable attributes
+without all that tedious mucking about with +@inheritable_attributes+.
+
+== FEATURES
+
+* Fully Spec'd
+* reader/writer methods are cleanly partitioned in dynamically created modules
+* No extra class variables needed for bookkeeping
+* Reader/writer methods are defined once and only once no matter how many classes 
+  inherit them
+* Family inheritable attributes can be defined in modules
+* Will not pollute the global namespace.
+
+== SYNOPSIS:
+
+  module Shared
+    include Clafamatt::Macros
+
+    class_family_accessor :foo
+  end
+
+  class Parent
+    include Shared
+
+  end
+
+  class Child < Parent
+    class_family_accessor :bar
+  end
+
+  Shared.foo                      # => nil
+  Parent.foo                      # => nil
+  Child.foo                       # => nil
+
+  Shared.foo = "klaatu"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "klaatu"
+  Child.foo                       # => "klaatu"
+
+  Parent.foo = "nikto"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "nikto"
+  Child.foo                       # => "nikto"
+
+  Child.foo = "barada"
+  Shared.foo                      # => "klaatu"
+  Parent.foo                      # => "nikto"
+  Child.foo                       # => "barada"
+
+  Child.bar = "klaatu"
+  Child.bar                       # => "klaatu"
+  Parent.bar                      # => 
+  # ~> -:38: undefined method `bar' for Parent:Class (NoMethodError)
+
+== RATIONALE:
+
+Clafamatt sprung from a desire to have ActiveSupport-style class inheritable
+attributes without having all of ActiveSupport come with it.  It is also an
+attempt to implement class-inheritable attributes in the cleanest way possible.
+
+In contrast to the ActiveSupport version, which writes reader/writer methods
+directly into the class being extended, Clafamatt writes it's readers and
+writers into a dynamically created module which is then inserted into the class'
+(or module's) singleton class.  Among other benefits, this enables Clafamatt to
+transparently support defining inheritable attributes in either classes or
+modules.
+
+The ActiveSupport version keeps inheritable attribute values in a class-level
+@inheritable_attributes variable, which it copies whenever a new class is
+inherited.  Clafamatt stays closer to Ruby conventions by storing each
+attribute's value in a correspondingly-named class instance variable - so
+e.g. <code>Foo.bar = 42</code> will set the <code>@bar</code> instance variable.  This is
+consistent with how Ruby's built-in attr_* macros behave.  Beyond the variables
+used to store values, Clafamatt needs *zero* class instance variables for
+internal bookeeping.  It also doesn't copy variables on inheritance; instead, it
+simply re-uses values from farther up the inheritance chain until an attribute
+is explicitly set.
+
+Finally, Clafamatt is only there when you ask for it, by including
+Clafamatt::Macros.  It will not pollute the global namespace.
+
+== REQUIREMENTS:
+
+* Ruby!
+
+== INSTALL:
+
+  sudo gem install clafamatt
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Avdi Grimm
+
+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.

data/Rakefile

@@ -0,0 +1,46 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  load 'tasks/setup.rb'
+end
+
+ensure_in_path 'lib'
+require 'clafamatt'
+
+task :default => 'spec:run'
+
+PROJ.name = 'clafamatt'
+PROJ.authors = 'Avdi Grimm'
+PROJ.email = 'avdi@avdi.org'
+PROJ.url = 'http://clafamatt.rubyforge.org'
+PROJ.version = Clafamatt::VERSION
+PROJ.rubyforge.name = 'clafamatt'
+PROJ.readme_file = 'README.rdoc'
+
+# Uncomment to disable warnings
+# PROJ.ruby_opts = []
+
+# RSpec
+PROJ.spec.opts << '--color'
+
+# RDoc
+PROJ.rdoc.include << '\.rdoc$'
+
+# Email Announcement
+PROJ.ann.email[:from]     = 'avdi@avdi.org'
+PROJ.ann.email[:to]       = 'ruby-talk@ruby-lang.org'
+PROJ.ann.email[:server]   = 'smtp.gmail.com'
+PROJ.ann.email[:domain]   = 'avdi.org'
+PROJ.ann.email[:port]     = 587
+PROJ.ann.email[:acct]     = 'avdi.grimm'
+PROJ.ann.email[:authtype] = :plain
+
+# Notes
+PROJ.notes.extensions << '.rdoc'
+
+# EOF

data/bin/clafamatt

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib clafamatt]))
+
+# Put your code here
+
+# EOF

data/examples/synopsys.rb

@@ -0,0 +1,38 @@
+require File.expand_path('../lib/clafamatt', File.dirname(__FILE__))
+
+module Shared
+  include Clafamatt::Macros
+
+  class_family_accessor :foo
+end
+
+class Parent
+  include Shared
+
+end
+
+class Child < Parent
+  class_family_accessor :bar
+end
+
+Shared.foo                      # =>
+Parent.foo                      # =>
+Child.foo                       # =>
+
+Shared.foo = "klaatu"
+Shared.foo                      # =>
+Parent.foo                      # =>
+Child.foo                       # =>
+
+Parent.foo = "nikto"
+Shared.foo                      # =>
+Parent.foo                      # =>
+Child.foo                       # =>
+
+Child.foo = "barada"
+Parent.foo                      # =>
+Child.foo                       # =>
+
+Child.bar = "klaatu"
+Child.bar                       # =>
+Parent.bar                      # =>

data/lib/clafamatt.rb

@@ -0,0 +1,168 @@
+module Clafamatt
+
+  # :stopdoc:
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '*', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+  # :startdoc:
+
+  # This might be better named SingletonModule.  A MacroModule acts as a
+  # container for singleton methods attached to a given class or module.  This
+  # way we can share singleton methods across arbitrary classes and modules.
+  #
+  # MacroModule also ensures that the class being "decorated" with a MacroModule
+  # of its own will also inherit all of its ancestors' macros.
+  class MacroModule < Module
+    def self.find_or_create_for(klass)
+      mod = self.new(klass)
+      extend_klass = lambda do
+        mod.extend_class!
+        mod
+      end
+      klass_singleton = class << klass; self; end
+      klass_singleton.ancestors.find(extend_klass){|a|
+        a == mod
+      }
+    end
+    def self.find_all_for(klass)
+      klass_singleton = class << klass; self; end
+      klass_singleton.ancestors.grep(MacroModule)
+    end
+    def initialize(decorated_class)
+      @decorated_class = decorated_class
+    end
+
+    def ==(other)
+      self.class == other.class && self.decorated_class == other.decorated_class
+    end
+
+    def inspect
+      "#<Clafamatt::MacroModule:#{@decorated_class}:(#{self.instance_methods(false).join(", ")})>"
+    end
+
+    def copy_ancestor_macro_modules!
+      @decorated_class.ancestors.each do |ancestor|
+        macro_modules = self.class.find_all_for(ancestor)
+        macro_modules.each do |mm|
+          @decorated_class.extend(mm)
+        end
+      end
+    end
+
+    def extend_class!
+      copy_ancestor_macro_modules!
+      @decorated_class.extend(self)
+    end
+    attr_reader :decorated_class
+  end
+
+  module Macros
+    def self.append_features(other)
+      other.extend(ClassMethods)
+      super(other)
+    end
+
+    module ClassMethods
+      def class_family_reader(*symbols)
+        symbols.each do |name|
+          ivar   = '@' + name.to_s
+          define_macro(name) do ||
+              # Explicitly checking for variable definition avoids warnings.
+              if instance_variable_defined?(ivar)
+                instance_variable_get(ivar)
+               # super() doesn't work the way we need in singleton class world
+              elsif can_pass?(name)
+                pass(name)
+              else
+                nil
+              end
+          end
+        end
+      end
+      def class_family_writer(*symbols)
+        symbols.each do |name|
+          setter = name.to_s + '='
+          ivar   = '@' + name.to_s
+          define_macro(setter) do |new_value|
+            instance_variable_set(ivar, new_value)
+          end
+        end
+      end
+      def class_family_accessor(*symbols)
+        class_family_reader(*symbols)
+        class_family_writer(*symbols)
+      end
+
+      private
+
+      def append_features(other)
+        other.extend(ClassMethods)
+        cmm = clafamatt_macro_module
+        other.extend(cmm)
+        super(other)
+      end
+
+      def define_macro(name, &block)
+        cmm = clafamatt_macro_module
+        cmm.module_eval do
+          define_method(name, &block)
+        end
+      end
+
+      def clafamatt_macro_module
+        MacroModule.find_or_create_for(self)
+      end
+
+      def next_ancestor_responding_to(method)
+        ancestors.slice(1..-1).detect{|a| a.respond_to?(method)}
+      end
+
+      def can_pass?(method)
+        next_ancestor_responding_to(method)
+      end
+
+      def pass(method, *args, &block)
+        next_ancestor_responding_to(method).send(method, *args, &block)
+      end
+    end
+  end
+end  # module Clafamatt
+
+Clafamatt.require_all_libs_relative_to(__FILE__)
+
+# EOF