classy 1.1.1 → 1.2.0

data/README.rdoc

@@ -11,6 +11,10 @@ sub-subclasses, etc), and Aliasable lets you refer to classes via symbols
   class Parent
     extend Aliasable
     extend SubclassAware
+    extend Templatable
+
+    templatable_attr :awesomeness, :temperature
+    awesomeness :fairly
 
     aka :pop
   end
@@ -23,8 +27,9 @@ sub-subclasses, etc), and Aliasable lets you refer to classes via symbols
     aka :kid2
   end
 
-  Parent.find(:kid1)  # => ChildA
-  Parent.subclasses   # => [ ChildA, ChildB ]
+  Parent.find(:kid1)      # => ChildA
+  Parent.subclasses       # => [ ChildA, ChildB ]
+  Parent.new.awesomeness  # => :fairly
 
 More extensive documentation and example code can be found in the RDoc for each
 module (available online at http://rdoc.info/projects/djspinmonkey/classy) or

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

data/lib/classy/aliasable.rb

@@ -4,17 +4,10 @@
 # a given class hierarchy.  Possible uses for this include friendlier DSLs or
 # additional layers of dynamic abstraction when specifying classes.
 #
-# Note: As mentioned, this module keeps its identity map in a class variable,
-# @@classy_aliases, on the extending class.  This could concievably lead to
-# namespace conflicts and strange bugs in the unlikely event that this variable
-# is used for anything else.  Later versions may implement a hash of identity
-# maps as a class variable on the Aliasable module itself, but for reasons of
-# complexity and performance, that has not been done at this time.
-#
 # ==Example
 #
 #   class ParentClass
-#     extend Aliasable
+#     include Aliasable
 #     aka :pop
 #   end
 #   
@@ -25,54 +18,124 @@
 #   Parent.find(:pop)   # => ParentClass
 #   Parent.find(:kid)   # => AliasedSubclass
 #
-# More complex usage examples can be found in the aliasable_spec.rb file.
+# It is also possible to include Aliasable from a model, which will then track
+# aliases of classes which include that module.
+#
+# == Example
+#
+#   module Meta
+#     include Aliasable
+#   end
+#
+#   class AliasedClass
+#     include Meta
+#
+#     aka :klass
+#   end
+#
+#   Meta.find(:klass)  # => AliasedClass
+#
+# More complex usage examples can be found in the spec file.
+#
+# NOTE: This defines a class variable, @@classy_aliases, on any class or module
+# that includes Aliasable (or any class that includes a module including
+# Aliasable).
+#
+# ANOTHER NOTE: As always, if you define your own .included methods, be sure to
+# call super.
 #
 module Aliasable
-
-  def self.extended (klass) #:nodoc:
-    klass.class_exec do
-      class_variable_set(:@@classy_aliases, {})
-    end
-  end
-
-  # When passed a class, just returns it.  When passed a symbol that is an
-  # alias for a class, returns that class.
+  # Handle a module or class including Aliasable.
   #
-  #   ParentClass.find(AliasedSubclass)   # => AliasedSubclass
-  #   ParentClass.find(:kid)              # => AliasedSubclass
+  # :nodoc:
   #
-  def find (klass)
-    return klass if klass.kind_of? Class
-    class_variable_get(:@@classy_aliases)[klass] or raise ArgumentError, "Could not find alias #{klass}"
+  def self.included( mod )
+    mod.extend ControllingClassMethods
+    mod.extend UniversalClassMethods
+    mod.extend AliasingClassMethods if mod.kind_of? Class       # If mod is a Class, the aliased classes get the class methods via inheritance.
+    mod.send :class_variable_set, :@@classy_aliases, Hash.new
+    super
   end
 
-  # Forget all known aliases.  Mainly useful for testing purposes.
+  # Methods for the class or module that directly includes Aliasable.  
   #
-  def forget_aliases
-    class_variable_get(:@@classy_aliases).clear
+  module ControllingClassMethods
+    # Handle a class including a module that has included Aliasable.  Since the
+    # contolling module has extended this module, this method ends up being
+    # called when the controlling module is included.
+    # 
+    # As a minor side effect, an instance method named #included ends up on any
+    # class that directly includes Aliasable.  If you know an elegant way to
+    # avoid this, I welcome pull requests.  :-)
+    #
+    # :nodoc:
+    #
+    def included( klass )
+      klass.extend AliasingClassMethods
+      klass.extend UniversalClassMethods
+
+      # Hoo boy.  We need to set the @@classy_aliases class variable in the
+      # including class to point to the same actual hash object that the
+      # @@classy_aliases variable on the controlling module points to.  When
+      # everything is class based, this is done automatically, since
+      # sub-classes share class variables.
+      #
+      klass.send(:class_variable_set, :@@classy_aliases, self.send(:class_variable_get, :@@classy_aliases))
+
+      super
+    end
+
+    # When passed a class, just returns it.  When passed a symbol that is an
+    # alias for a class, returns that class.
+    #
+    #   ParentClass.find(AliasedSubclass)   # => AliasedSubclass
+    #   ParentClass.find(:kid)              # => AliasedSubclass
+    #
+    def find( nick )
+      return nick if nick.kind_of? Class
+      aliases[nick]
+    end
+
+    # Forget all known aliases.  Mainly useful for testing purposes.
+    #
+    def forget_aliases
+      aliases.clear
+    end
+
   end
 
-  # Specifies a symbol (or several) that a given framework might be known
-  # by.  
-  #
-  #   class AnotherClass
-  #     aka :kid2, :chunky_bacon
-  #     ...
-  #   end
+  # Methods for the classes that get aliased.
   #
-  def aka (*names)
-    names.each do |name| 
-      raise ArgumentError, "Called aka with an alias that is already taken." if class_variable_get(:@@classy_aliases).include? name
-      class_variable_get(:@@classy_aliases)[name] = self
+  module AliasingClassMethods
+    # Specifies a symbol (or several) that a given framework might be known
+    # by.  
+    #
+    #   class AnotherClass
+    #     aka :kid2, :chunky_bacon
+    #     ...
+    #   end
+    #
+    def aka( *nicks )
+      nicks.each do |nick| 
+        raise ArgumentError, "Called aka with an alias that is already taken." if aliases.include? nick
+        aliases[nick] = self
+      end
     end
   end
 
-  # Return a hash of known aliases to Class objects
+  # Methods for both the controlling class/module and the aliased classes.
   #
-  #   ParentClass.aliases   # => { :pop => ParentClass, :kid => AliasedSubclass, :kid2 => AnotherClass, :chunky_bacon => AnotherClass }
-  #
-  def aliases
-    class_variable_get(:@@classy_aliases).dup
+  module UniversalClassMethods
+    # Return a hash of known aliases to Class objects.
+    #
+    # DANGER DANGER: This is the actual hash used internally by Aliasable, not a
+    # dup. If you mess with it, you might asplode things.
+    #
+    #   ParentClass.aliases                     # => { :pop => ParentClass, :kid => AliasedSubclass, :kid2 => AnotherClass, :chunky_bacon => AnotherClass }
+    #   ParentClass.aliases[:thing] = "BOOM"    # This will end in tears.
+    #
+    def aliases
+      send :class_variable_get, :@@classy_aliases
+    end
   end
-
 end

data/lib/classy/subclass_aware.rb

@@ -28,23 +28,19 @@ require 'set'
 #
 # == Warning 
 #
-# This module defines an inherited() class method on the extending class to
-# keep track of subclasses.  Unfortunately, if this method is later re-defined,
-# this inherited() method is lost and subclass tracking will break.  In order
-# to work around this, constructions like the following might be necessary:
-#
-#   class ChildC < Parent
-#
-#     class << self; alias :old_inherited :inherited end
-#     def self.inherited(sub)
-#       old_inherited(sub)
-#       # ...your inherited() code...
-#     end
+# This module defines an inherited() class method.  If the extending class
+# defines its own inherited() method without calling super, this inherited()
+# method is lost and subclass tracking will break.  In order to work around
+# this, make sure your inherited() method calls super.  Like this:
 #
+# class YourAwesomeClass
+#   
+#   def self.inherited
+#     # ...your awesome logic
+#     super  # <-- This is important.
 #   end
 #
-# This is not considered an acceptable long-term state of affairs - hopefully
-# in future versions of this module, this work around will not be necessary.
+# end
 #
 module SubclassAware
 
@@ -57,12 +53,9 @@ module SubclassAware
   # Add the inheriting class to the list of subclasses.  Not intended to be
   # called directly.
   #
-  # TODO: Find a way for self.inherited on the extended class not to blow
-  # this away without requiring a bunch of alias chain hoops to be jumped
-  # through, as described above.
-  #
   def inherited(sub)
     class_exec { class_variable_get(:@@classy_subclasses).add sub }
+    super
   end
 
   # Return an array of all known subclasses (and sub-subclasses, etc) of this

data/lib/classy/templatable.rb

@@ -24,6 +24,8 @@
 #   # Instances can override the defaults.
 #   doodad.awesomeness = nil
 #   doodad.temperature = :cool
+#   doodad.awesomeness    # => nil
+#   doodad.temperature    # => :cool
 #
 # == Note
 #
@@ -37,6 +39,9 @@ module Templatable
   # (Required to distinguish between variables explicitly set to nil and those
   # left as nil by default.)
   #
+  # @private
+  # :nodoc:
+  #
   @@ever_been_set = Hash.new { |hash, key| hash[key] = {} }
 
   # Defines one or more templatable attrs, which will add instance methods

data/spec/aliasable_spec.rb

@@ -2,11 +2,10 @@ require File.join(File.dirname(__FILE__), 'spec_helper')
 
 describe "Aliasable" do
 
-  # TODO: It would be better to tear these down and rebuild them before each
-  # test, since some of the tests add or remove aliases.
   before :all do
+    Base.forget_aliases if Object.const_defined? "Base"
     class Base
-      extend Aliasable
+      include Aliasable
       aka :base
     end
 
@@ -18,6 +17,21 @@ describe "Aliasable" do
       aka :childB
     end
 
+    Meta.forget_aliases if Object.const_defined? "Meta"
+    module Meta
+      include Aliasable
+    end
+
+    class IncluderA
+      include Meta
+      aka :incA
+    end
+
+    class IncluderB
+      include Meta
+      aka :incB
+    end
+
   end
 
   describe ".aliases" do
@@ -29,6 +43,13 @@ describe "Aliasable" do
         :childB => ChildB
       })
     end
+
+    it "should work on modules as well as classes" do
+      Meta.aliases.should eql({
+        :incA => IncluderA,
+        :incB => IncluderB
+      })
+    end
   end
 
   describe ".aka" do
@@ -46,11 +67,15 @@ describe "Aliasable" do
       Base.find(:first_child).should equal ChildA
       Base.find(:childB).should equal ChildB
     end
+
+    it "should work on modules as well as bases" do
+      Meta.find(:incA).should equal IncluderA
+    end
   end
 
   it "should keep aliases of different class hierarchies separate" do
     class AnotherBase
-      extend Aliasable
+      include Aliasable
     end
 
     lambda {
@@ -76,6 +101,11 @@ describe "Aliasable" do
       Base.forget_aliases
       Base.aliases.should be_empty
     end
+
+    it "should work for modules as well as classes" do
+      Meta.forget_aliases
+      Meta.aliases.should be_empty
+    end
   end
 
 end

data/spec/subclass_aware_spec.rb

@@ -8,13 +8,10 @@ describe "SubclassAware" do
     class ParentA
       extend SubclassAware
 
-      # This is kind of a pain in the butt, but it's what you need to do if you
-      # define your own self.inherited to keep from blowing away the one
-      # SubclassAware sets up.  There's a todo in subclass_aware.rb about this.
-      class << self; alias :old_inherited :inherited end
+      # Make sure you call super in any self.inherited() methods!
       def self.inherited(sub)
-        old_inherited(sub)
-        # do your stuff here
+        # ...your stuff...
+        super  # <-- This is important
       end
     end
 

metadata

@@ -1,7 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: classy
 version: !ruby/object:Gem::Version 
-  version: 1.1.1
+  hash: 31
+  prerelease: 
+  segments: 
+  - 1
+  - 2
+  - 0
+  version: 1.2.0
 platform: ruby
 authors: 
 - John Hyland
@@ -9,19 +15,25 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-12 00:00:00 -05:00
+date: 2011-10-27 00:00:00 -04:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
+        hash: 13
+        segments: 
+        - 1
+        - 2
+        - 9
         version: 1.2.9
-    version: 
+  type: :development
+  version_requirements: *id001
 description: Classy is a collection of metaprogramming-heavy modules which you can extend in order to give various capabilities to your Ruby classes.  For example, SubclassAware lets a class know about all of its subclasses (and sub-subclasses, etc), and Aliasable lets you refer to classes via symbols (useful for creating friendly DSLs).
 email: github@djspinmonkey.com
 executables: []
@@ -57,21 +69,27 @@ rdoc_options:
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
       version: "0"
-  version: 
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.5
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: A collection of modules to enhance the capabilities of Ruby classes in various ways.