classy 1.0.1 → 1.0.2

data/README.rdoc

@@ -6,6 +6,29 @@ 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).
 
+== Examples
+
+  class Parent
+    extend Aliasable
+    extend SubclassAware
+
+    aka :pop
+  end
+
+  class ChildA
+    aka :kid1
+  end
+
+  class ChildB
+    aka :kid2
+  end
+
+  Parent.find(:kid1)  # => ChildA
+  Parent.subclasses   # => [ ChildA, ChildB ]
+
+More extensive documentation and example code can be found in the RDoc for each
+module, or in the spec files.
+
 == Note on Patches/Pull Requests
  
 * Fork the project.

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

data/lib/classy/aliasable.rb

@@ -8,27 +8,28 @@
 # @@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 Aliasble module itself, but for reasons of
+# 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 Parent
+#   class ParentClass
 #     extend Aliasable
 #     aka :pop
 #   end
 #   
-#   class Child < Parent
+#   class AliasedSubclass < ParentClass
 #     aka :kid
 #   end
 #
-#   Parent.find(:pop)   # => Parent
-#   Parent.find(:kid)   # => Child
+#   Parent.find(:pop)   # => ParentClass
+#   Parent.find(:kid)   # => AliasedSubclass
 #
 # More complex usage examples can be found in the aliasable_spec.rb file.
 #
 module Aliasable
-  def self.extended (klass) #nodoc;
+
+  def self.extended (klass) #:nodoc:
     klass.class_exec do
       class_variable_set(:@@classy_aliases, {})
     end
@@ -37,25 +38,25 @@ module Aliasable
   # When passed a class, just returns it.  When passed a symbol that is an
   # alias for a class, returns that class.
   #
-  #   Testify::Framework::Base.find(:rspec)  # => Testify::Framework::RSpec
+  #   ParentClass.find(AliasedSubclass)   # => AliasedSubclass
+  #   ParentClass.find(:kid)              # => AliasedSubclass
   #
   def find (klass)
     return klass if klass.kind_of? Class
     class_variable_get(:@@classy_aliases)[klass] or raise ArgumentError, "Could not find alias #{klass}"
   end
 
-  # Forget all known aliases.
+  # Forget all known aliases.  Mainly useful for testing purposes.
   #
   def forget_aliases
     class_variable_get(:@@classy_aliases).clear
   end
 
   # Specifies a symbol (or several) that a given framework might be known
-  # by.  For example, if you wanted to refer to RSpec by :rspec or :spec,
-  # you might do this:
+  # by.  
   #
-  #   class RSpec
-  #     aka :rspec, spec
+  #   class AnotherClass
+  #     aka :kid2, :chunky_bacon
   #     ...
   #   end
   #
@@ -68,6 +69,8 @@ module Aliasable
 
   # Return a hash of known aliases to Class objects
   #
+  #   ParentClass.aliases   # => { :pop => ParentClass, :kid => AliasedSubclass, :kid2 => AnotherClass, :chunky_bacon => AnotherClass }
+  #
   def aliases
     class_variable_get(:@@classy_aliases).dup
   end

data/lib/classy/subclass_aware.rb

@@ -1,15 +1,55 @@
 require 'set'
 
+# SubclassAware allows a class to know about all of the subclasses that descend
+# from it in the inheritance tree.
+#
+# Example:
+#
+#   class Parent
+#     extend SubclassAware
+#   end
+#
+#   class ChildA < Parent
+#   end
+#
+#   class ChildB < Parent
+#   end
+#
+#   Class ChildB1 < ChildB
+#   end
+#
+#   Parent.subclasses   # => [ ChildA, ChildB, ChildB1 ]
+#
+# 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
+#
+#   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.
+#
 module SubclassAware
 
-  def self.extended (klass) #nodoc;
+  def self.extended (klass) #:nodoc:
     klass.class_exec { class_variable_set(:@@subclasses, Set.new) }
   end
 
   # 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.
-  def inherited(sub) #nodoc;
+  #
+  def inherited(sub) #:nodoc:
     class_exec { class_variable_get(:@@subclasses).add sub }
   end
 
@@ -20,8 +60,8 @@ module SubclassAware
     class_exec { class_variable_get(:@@subclasses).to_a }
   end
 
-  # Clear all info about known subclasses.  Usefull for testing, but it is
-  # unlikely you would use it for much else.
+  # Clear all info about known subclasses.  This method is probably mainly
+  # useful for testing.
   #
   def forget_subclasses
     class_exec { class_variable_get(:@@subclasses).clear }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: classy
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors: 
 - John Hyland