module_creation_helper 0.0.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2005-2006 Aaron Pfeifer & Neil Abraham
+
+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/README

@@ -0,0 +1,97 @@
+= module_creation_helper
+
+module_creation_helper adds a helper method for creating new modules and classes
+at runtime.
+
+== Resources
+
+Wiki
+
+* http://wiki.pluginaweek.org/Module_creation_helper
+
+Announcement
+
+* http://www.pluginaweek.org/2007/01/04/10-from-anonymous-to-named-and-back-again-a-tale-of-modules-and-classes/
+
+Source
+
+* http://svn.pluginaweek.org/trunk/plugins/ruby/module/module_creation_helper
+
+Development
+
+* http://dev.pluginaweek.org/browser/trunk/plugins/ruby/module/module_creation_helper
+
+== Description
+
+Creating modules and classes at runtime isn't the easiest and most intuitive
+process that Ruby could have provided.  Although often used for anonymous
+classes, there are many times where you will want to associate a runtime class
+with an actual name.
+
+Normally, you would create new classes and associate them with a name like so:
+
+  >> c = Class.new
+  => #<Class:0x480e388>
+  >> Object.const_set('Foo', c)
+  => Foo
+
+Although this isn't very hard, there are two problems:
+(1) It's a repetitive process that should be DRYed in the same way that chaining
+methods has been dried.
+(2) Callbacks that are invoked while the class is being created do not have
+access to the name of the class.
+
+To understand the second problem, consider the following:
+
+  class Foo
+    def self.inherited(base)
+      puts "inherited class: #{base}, name: #{base.name}"
+    end
+  end
+
+When a class inherits from Foo, Ruby will invoke the +inherited+ callback.  For
+example,
+
+  >> c = Class.new(Foo)
+  inherited class: #<Class:0x47fb92c>, name:
+  => #<Class:0x47fb92c>
+
+As you can see from output in this example, since the class has not yet been
+assigned to a constant, it is anonymous and does not yet have a name.
+
+To address these two issues, the functionality is encapsulated into a new method,
+Module#create.  Since the method is defined in Module, it is also available to
+Class since Class inherits from Module.
+
+Rather than defining new modules/classes using Module#new/Class#new, this plugin
+uses class_eval on the object's parent.  This allows names to be immediately
+associated with the class/module regardless of whether it is currently being
+evaluated or has already been evaluated.
+
+Using the same example as before,
+
+  >> c = Class.create('Bar', :superclass => Foo)
+  inherited class: Bar, name: Bar
+  => Bar
+
+As you can see, the name of the class is now available during the +inherited+
+callback and is automatically assigned to the 'Bar' constant in Object.  In
+addition to specifying the superclass, you can also specify the parent
+module/class like so:
+
+  >> c = Class.create('Bar', :superclass => Foo, :parent => MyModule)
+  inherited class: MyModule::Bar, name: MyModule::Bar
+  => MyModule::Bar
+
+Finally, as you normally could when creating a new class, you can provide an
+additional block that defines the body of the class.  For example,
+
+  >> c = Class.create('Bar', :superclass => Foo, :parent => MyModule) do
+  ?>   def say_hello
+  ?>     'hello'
+  ?>   end
+  ?> end
+  inherited class: MyModule::Bar, name: MyModule::Bar
+  => Bar
+  >> Bar.new.say_hello
+  => "hello"

data/Rakefile

@@ -0,0 +1,79 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+PKG_NAME           = 'module_creation_helper'
+PKG_VERSION        = '0.0.2'
+PKG_FILE_NAME      = "#{PKG_NAME}-#{PKG_VERSION}"
+RUBY_FORGE_PROJECT = 'pluginaweek'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the module_creation_helper plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the module_creation_helper plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'ModuleCreationHelper'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s|
+  s.name            = PKG_NAME
+  s.version         = PKG_VERSION
+  s.platform        = Gem::Platform::RUBY
+  s.summary         = 'Adds a helper method for creating new modules and classes at runtime.'
+  
+  s.files           = FileList['{lib,tasks,test}/**/*'].to_a + %w(init.rb MIT-LICENSE Rakefile README)
+  s.require_path    = 'lib'
+  s.autorequire     = 'module_creation_helper'
+  s.has_rdoc        = true
+  s.test_files      = Dir['test/**/*_test.rb']
+  
+  s.author          = 'Aaron Pfeifer and Neil Abraham'
+  s.email           = 'info@pluginaweek.org'
+  s.homepage        = 'http://www.pluginaweek.org'
+end
+  
+Rake::GemPackageTask.new(spec) do |p|
+  p.gem_spec = spec
+  p.need_tar = true
+  p.need_zip = true
+end
+
+desc 'Publish the beta gem'
+task :pgem => [:package] do
+  Rake::SshFilePublisher.new('pluginaweek@pluginaweek.org', '/home/pluginaweek/gems.pluginaweek.org/gems', 'pkg', "#{PKG_FILE_NAME}.gem").upload
+end
+
+desc 'Publish the API documentation'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('pluginaweek@pluginaweek.org', "/home/pluginaweek/api.pluginaweek.org/#{PKG_NAME}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new
+  ruby_forge.login
+  
+  %w( gem tgz zip ).each do |ext|
+    file = "pkg/#{PKG_FILE_NAME}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(RUBY_FORGE_PROJECT, PKG_NAME, PKG_VERSION, file)
+  end
+end

data/init.rb

@@ -0,0 +1 @@
+require 'module_creation_helper'

data/lib/module_creation_helper.rb

@@ -0,0 +1,64 @@
+module PluginAWeek #:nodoc:
+  module CoreExtensions #:nodoc:
+    module Module #:nodoc:
+      module ModuleCreationHelper
+        # Creates a new module with the specified name.  This is essentially the
+        # same as actually defining the module like so:
+        # 
+        #   module NewModule
+        #   end
+        # 
+        # or as a class:
+        # 
+        #   class NewClass < SuperKlass
+        #   end
+        # 
+        # Configuration options:
+        # <tt>superclass</tt> - The class to inherit from.  This only applies when using Class#create.  Default is Object.
+        # <tt>parent</tt> - The class/module that contains this module.  Default is Object.
+        # 
+        # Examples:
+        # 
+        #   Module.create('Foo')                                                      # => Foo
+        #   Module.create('Bar', :parent => Foo)                                      # => Foo::Bar
+        #   Class.create('Waddle')                                                    # => Waddle
+        #   Class.create('Widdle', :parent => Waddle)                                 # => Waddle::Widdle
+        #   Class.create('Woddle', :superclass => Waddle::Widdle, :parent => Waddle)  # => Waddle::Woddle
+        #   Waddle::Woddle.superclass                                                 # => Waddle::Widdle
+        def create(name, options = {}, &block)
+          options.assert_valid_keys(
+            :superclass,
+            :parent
+          )
+          raise ArgumentError, 'Modules cannot have superclasses' if options[:superclass] && self.to_s == 'Module'
+          
+          options.reverse_merge!(
+            :superclass => ::Object,
+            :parent => ::Object
+          )
+          parent = options[:parent]
+          superclass = options[:superclass]
+          
+          if superclass != ::Object
+            superclass = " < ::#{superclass}"
+          else
+            superclass = ''
+          end
+          
+          parent.class_eval <<-end_eval
+            #{self.to_s.downcase} #{name}#{superclass}
+            end
+          end_eval
+          
+          mod = parent.const_get(name)
+          mod.class_eval(&block) if block_given?
+          mod
+        end
+      end
+    end
+  end
+end
+
+class ::Module #:nodoc:
+  extend PluginAWeek::CoreExtensions::Module::ModuleCreationHelper
+end

data/test/module_creation_helper_test.rb

@@ -0,0 +1,132 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+module TestParent
+end
+
+class TestSuperclass
+  cattr_accessor :test_name
+  cattr_accessor :test_inspect
+  cattr_accessor :test_to_s
+  
+  def self.inherited(base)
+    self.test_name = base.name
+    self.test_inspect = base.inspect
+    self.test_to_s = base.to_s
+  end
+end
+
+class ModuleCreationHelperTest < Test::Unit::TestCase
+  def setup
+    TestSuperclass.test_name = nil
+    TestSuperclass.test_inspect = nil
+    TestSuperclass.test_to_s = nil
+  end
+  
+  def test_no_options_for_class
+    klass = Class.create('Foo')
+    assert_equal Object, klass.superclass
+    assert_equal Object, klass.parent
+    assert Object.const_defined?('Foo')
+  end
+  
+  def test_no_options_for_module
+    mod = Module.create('FooMod')
+    assert_equal Object, mod.parent
+    assert Object.const_defined?('FooMod')
+  end
+  
+  def test_invalid_option
+    assert_raise(ArgumentError) {Class.create(nil, :invalid => true)}
+  end
+  
+  def test_superclass_for_module
+    assert_raise(ArgumentError) {Module.create(nil, :superclass => Object)}
+  end
+  
+  def test_superclass
+    klass = Class.create('Bar', :superclass => TestSuperclass)
+    assert_equal TestSuperclass, klass.superclass
+    assert_equal Object, klass.parent
+    assert Object.const_defined?('Bar')
+  end
+  
+  def test_parent_for_class
+    klass = Class.create('Baz', :parent => TestParent)
+    assert_equal Object, klass.superclass
+    assert_equal TestParent, klass.parent
+    assert TestParent.const_defined?('Baz')
+  end
+  
+  def test_parent_for_module
+    mod = Module.create('BazMod', :parent => TestParent)
+    assert_equal TestParent, mod.parent
+    assert TestParent.const_defined?('BazMod')
+  end
+  
+  def test_superclass_and_parent
+    klass = Class.create('Biz', :superclass => TestSuperclass, :parent => TestParent)
+    assert_equal TestSuperclass, klass.superclass
+    assert_equal TestParent, klass.parent
+    assert TestParent.const_defined?('Biz')
+  end
+  
+  def test_name_before_evaluated
+    klass = Class.create('Waddle', :superclass => TestSuperclass)
+    assert_equal 'Waddle', TestSuperclass.test_name
+  end
+  
+  def test_inspect_before_evaluated
+    klass = Class.create('Widdle', :superclass => TestSuperclass)
+    assert_equal 'Widdle', TestSuperclass.test_inspect
+  end
+  
+  def test_to_s_before_evaluated
+    klass = Class.create('Wuddle', :superclass => TestSuperclass)
+    assert_equal 'Wuddle', TestSuperclass.test_to_s
+  end
+  
+  def test_name_before_evaluated_with_parent
+    klass = Class.create('Waddle', :superclass => TestSuperclass, :parent => TestParent)
+    assert_equal 'TestParent::Waddle', TestSuperclass.test_name
+  end
+  
+  def test_inspect_before_evaluated_with_parent
+    klass = Class.create('Widdle', :superclass => TestSuperclass, :parent => TestParent)
+    assert_equal 'TestParent::Widdle', TestSuperclass.test_inspect
+  end
+  
+  def test_to_s_before_evaluated_with_parent
+    klass = klass = Class.create('Wuddle', :superclass => TestSuperclass, :parent => TestParent)
+    assert_equal 'TestParent::Wuddle', TestSuperclass.test_to_s
+  end
+  
+  def test_subclass_of_dynamic_class
+    klass = Class.create('Foobar')
+    subclass = Class.create('Foobaz', :superclass => klass)
+    
+    assert_equal klass, subclass.superclass
+    assert_equal 'Foobaz', subclass.name
+    assert_equal 'Foobaz', subclass.inspect
+    assert_equal 'Foobaz', subclass.to_s
+  end
+  
+  def test_with_block
+    klass = Class.create('ClassWithBlock', :superclass => TestSuperclass) do
+      def self.say_hello
+        'hello'
+      end
+    end
+    assert_equal 'hello', ClassWithBlock.say_hello
+  end
+  
+  def test_nested_class_with_superclass_with_same_name
+    klass = Class.create('Employee')
+    nested_class = Class.create('Employee', :superclass => klass, :parent => TestParent)
+    assert_equal klass, nested_class.superclass
+  end
+  
+  private
+  def klass_with_id(klass)
+    "#<Class:0x#{(klass.object_id * 2).to_s(16)}>"
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,6 @@
+require 'test/unit'
+require 'rubygems'
+require 'active_support'
+
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require File.dirname(__FILE__) + '/../init'

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: module_creation_helper
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+date: 2007-02-02 00:00:00 -05:00
+summary: Adds a helper method for creating new modules and classes at runtime.
+require_paths: 
+- lib
+email: info@pluginaweek.org
+homepage: http://www.pluginaweek.org
+rubyforge_project: 
+description: 
+autorequire: module_creation_helper
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Aaron Pfeifer and Neil Abraham
+files: 
+- lib/module_creation_helper.rb
+- test/test_helper.rb
+- test/module_creation_helper_test.rb
+- init.rb
+- MIT-LICENSE
+- Rakefile
+- README
+test_files: 
+- test/module_creation_helper_test.rb
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+