pluginaweek-module_creation_helper 0.2.0

data/CHANGELOG.rdoc

@@ -0,0 +1,26 @@
+== master
+
+== 0.2.0 / 2008-12-14
+
+* Remove the PluginAWeek namespace
+
+== 0.1.0 / 2008-07-06
+
+* Add support for specifying the parent class/module in the name of the class/module being created
+* Don't depend on active_support
+
+== 0.0.4 / 2008-05-05
+
+* Updated documentation
+
+== 0.0.3 / 2007-09-18
+
+* Convert dos newlines to unix newlines
+
+== 0.0.2 / 2007-02-02
+
+* Released as a gem
+
+== 0.0.1 / 2007-01-04
+
+* Initial release

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2006-2009 Aaron Pfeifer
+
+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.rdoc

@@ -0,0 +1,101 @@
+= module_creation_helper
+
++module_creation_helper+ adds a helper method for creating new modules and classes
+at runtime.
+
+== Resources
+
+API
+
+* http://api.pluginaweek.org/module_creation_helper
+
+Bugs
+
+* http://pluginaweek.lighthouseapp.com/projects/13281-module_creation_helper
+
+Development
+
+* http://github.com/pluginaweek/module_creation_helper
+
+Source
+
+* git://github.com/pluginaweek/module_creation_helper.git
+
+== Description
+
+Creating modules and classes at runtime isn't the easiest and most intuitive
+process.  Although often used for anonymous classes, there are many times where
+you will want to associate a runtime class with an actual name.
+
+Traditionally, you would create new classes 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.
+(2) Callbacks that are invoked while the class is being created do not know 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 issues, the functionality is encapsulated into a new method,
+<tt>Module#create</tt>.  Since the method is defined in Module, it is also available to
+Class since Class inherits from Module.
+
+== Usage
+
+=== Creating new classes/modules
+
+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.
+
+=== Specifying the parent class/module
+
+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
+
+=== Defining class/module methods
+
+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"
+
+== Dependencies
+
+None.

data/Rakefile

@@ -0,0 +1,96 @@
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'rake/contrib/sshpublisher'
+
+spec = Gem::Specification.new do |s|
+  s.name              = 'module_creation_helper'
+  s.version           = '0.2.0'
+  s.platform          = Gem::Platform::RUBY
+  s.summary           = 'Adds a helper method for creating new modules and classes at runtime'
+  s.description       = s.summary
+  
+  s.files             = FileList['{lib,test}/**/*'] + %w(CHANGELOG.rdoc init.rb LICENSE Rakefile README.rdoc)
+  s.require_path      = 'lib'
+  s.has_rdoc          = true
+  s.test_files        = Dir['test/**/*_test.rb']
+  
+  s.author            = 'Aaron Pfeifer'
+  s.email             = 'aaron@pluginaweek.org'
+  s.homepage          = 'http://www.pluginaweek.org'
+  s.rubyforge_project = 'pluginaweek'
+end
+  
+desc 'Default: run all tests.'
+task :default => :test
+
+desc "Test the #{spec.name} plugin."
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.test_files = spec.test_files
+  t.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  namespace :test do
+    desc "Test the #{spec.name} plugin with Rcov."
+    Rcov::RcovTask.new(:rcov) do |t|
+      t.libs << 'lib'
+      t.test_files = spec.test_files
+      t.rcov_opts << '--exclude="^(?!lib/)"'
+      t.verbose = true
+    end
+  end
+rescue LoadError
+end
+
+desc "Generate documentation for the #{spec.name} plugin."
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = spec.name
+  rdoc.template = '../rdoc_template.rb'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc', 'CHANGELOG.rdoc', 'LICENSE', 'lib/**/*.rb')
+end
+
+desc 'Generate a gemspec file.'
+task :gemspec do
+  File.open("#{spec.name}.gemspec", 'w') do |f|
+    f.write spec.to_ruby
+  end
+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('aaron@pluginaweek.org', '/home/aaron/gems.pluginaweek.org/public/gems', 'pkg', "#{spec.name}-#{spec.version}.gem").upload
+end
+
+desc 'Publish the API documentation.'
+task :pdoc => [:rdoc] do
+  Rake::SshDirPublisher.new('aaron@pluginaweek.org', "/home/aaron/api.pluginaweek.org/public/#{spec.name}", 'rdoc').upload
+end
+
+desc 'Publish the API docs and gem'
+task :publish => [:pgem, :pdoc, :release]
+
+desc 'Publish the release files to RubyForge.'
+task :release => [:gem, :package] do
+  require 'rubyforge'
+  
+  ruby_forge = RubyForge.new.configure
+  ruby_forge.login
+  
+  %w(gem tgz zip).each do |ext|
+    file = "pkg/#{spec.name}-#{spec.version}.#{ext}"
+    puts "Releasing #{File.basename(file)}..."
+    
+    ruby_forge.add_release(spec.rubyforge_project, spec.name, spec.version, file)
+  end
+end

data/init.rb

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

data/lib/module_creation_helper/extensions/module.rb

@@ -0,0 +1,74 @@
+module ModuleCreationHelper
+  module Extensions #:nodoc:
+    # Adds helper methods for easily generating new modules/classes
+    module Module
+      # 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
+      # 
+      # == Setting the parent
+      # 
+      # Rather than setting the parent directly using the +parent+ configuration
+      # option, you can specify it in the actual name of the class like so:
+      # 
+      #   Module.create('Foo::Bar')   # => Foo::Bar
+      # 
+      # This has the same effect as the following:
+      # 
+      #   Module.create('Bar', :parent => Foo)
+      def create(name, options = {}, &block)
+        # Validate the provided options
+        invalid_options = options.keys - [:superclass, :parent]
+        raise ArgumentError, "Unknown key(s): #{invalid_options.join(", ")}" unless invalid_options.empty?
+        
+        # Validate usage of :superclass option
+        raise ArgumentError, 'Modules cannot have superclasses' if options[:superclass] && self.to_s == 'Module'
+        
+        options = {:superclass => Object, :parent => Object}.merge(options)
+        parent = options[:parent]
+        superclass = options[:superclass]
+        
+        if superclass != Object
+          superclass = " < ::#{superclass}"
+        else
+          superclass = ''
+        end
+        
+        mod = parent.class_eval <<-end_eval
+          #{self.to_s.downcase} #{name}#{superclass}
+            self
+          end
+        end_eval
+        
+        mod.class_eval(&block) if block_given?
+        mod
+      end
+    end
+  end
+end
+
+Module.class_eval do
+  extend ModuleCreationHelper::Extensions::Module
+end

data/lib/module_creation_helper.rb

@@ -0,0 +1 @@
+require 'module_creation_helper/extensions/module'

data/test/module_creation_helper_test.rb

@@ -0,0 +1,230 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+module Ford
+end
+
+class Vehicle
+  class << self
+    attr_accessor :test_name
+    attr_accessor :test_inspect
+    attr_accessor :test_to_s
+  end
+  
+  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 test_should_raise_exception_if_invalid_option_specified
+    assert_raise(ArgumentError) {Class.create(nil, :invalid => true)}
+  end
+end
+
+class ClassTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Car')
+  end
+  
+  def test_should_have_object_as_superclass
+    assert_equal Object, @car.superclass
+  end
+  
+  def test_should_have_object_as_parent
+    assert Object.const_defined?('Car')
+  end
+  
+  def teardown
+    Object.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithSuperclassTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Car', :superclass => Vehicle)
+  end
+  
+  def test_should_inherit_from_superclass
+    assert_equal Vehicle, @car.superclass
+  end
+  
+  def test_should_have_object_as_parent
+    assert Object.const_defined?('Car')
+  end
+  
+  def test_should_evaluate_name_as_name
+    assert_equal 'Car', Vehicle.test_name
+  end
+  
+  def test_should_evaluate_inspect_as_name
+    assert_equal 'Car', Vehicle.test_inspect
+  end
+  
+  def test_should_evaluate_to_s_as_name
+    assert_equal 'Car', Vehicle.test_to_s
+  end
+  
+  def teardown
+    Object.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithParentTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Car', :parent => Ford)
+  end
+  
+  def test_should_have_object_as_superclass
+    assert_equal Object, @car.superclass
+  end
+  
+  def test_should_be_nested_within_parent
+    assert Ford.const_defined?('Car')
+  end
+  
+  def teardown
+    Ford.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithInferredParentTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Ford::Car')
+  end
+  
+  def test_should_have_object_as_superclass
+    assert_equal Object, @car.superclass
+  end
+  
+  def test_should_be_nested_within_parent
+    assert Ford.const_defined?('Car')
+  end
+  
+  def teardown
+    Ford.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithInferredParentAndConfiguredParenTest < Test::Unit::TestCase
+  def setup
+    Module.create('Car', :parent => Ford)
+    @part = Class.create('Car::Part', :parent => Ford)
+  end
+  
+  def test_should_have_object_as_superclass
+    assert_equal Object, @part.superclass
+  end
+  
+  def test_should_be_nested_within_parent
+    assert Ford::Car.const_defined?('Part')
+  end
+  
+  def teardown
+    Ford::Car.send(:remove_const, 'Part')
+    Ford.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithSuperclassAndParentTest < Test::Unit::TestCase
+  def setup
+    Vehicle.test_name = nil
+    Vehicle.test_inspect = nil
+    Vehicle.test_to_s = nil
+    
+    @car = Class.create('Car', :superclass => Vehicle, :parent => Ford)
+  end
+  
+  def test_should_inherit_from_superclass
+    assert_equal Vehicle, @car.superclass
+  end
+  
+  def test_should_be_nested_within_parent
+    assert Ford.const_defined?('Car')
+  end
+  
+  def test_should_evaluate_name_as_name
+    assert_equal 'Ford::Car', Vehicle.test_name
+  end
+  
+  def test_should_evaluate_inspect_as_name
+    assert_equal 'Ford::Car', Vehicle.test_inspect
+  end
+  
+  def test_should_evaluate_to_s_as_name
+    assert_equal 'Ford::Car', Vehicle.test_to_s
+  end
+  
+  def teardown
+    Ford.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithDynamicSuperclassTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Car')
+    @convertible = Class.create('Convertible', :superclass => @car)
+  end
+  
+  def test_should_inherit_from_superclass
+    assert_equal @car, @convertible.superclass
+  end
+  
+  def teardown
+    Object.send(:remove_const, 'Convertible')
+    Object.send(:remove_const, 'Car')
+  end
+end
+
+class ClassWithCustomMethodsTest < Test::Unit::TestCase
+  def setup
+    @car = Class.create('Car', :superclass => Vehicle) do
+      def self.color
+        'red'
+      end
+    end
+  end
+  
+  def test_should_evaluate_methods
+    assert_equal 'red', Car.color
+  end
+  
+  def teardown
+    Object.send(:remove_const, 'Car')
+  end
+end
+
+class ModuleTest < Test::Unit::TestCase
+  def setup
+    @autopilot = Module.create('Autopilot')
+  end
+  
+  def test_should_have_object_as_parent
+    assert Object.const_defined?('Autopilot')
+  end
+  
+  def teardown
+    Object.send(:remove_const, 'Autopilot')
+  end
+end
+
+class ModuleWithSuperclassTest < Test::Unit::TestCase
+  def test_should_raise_an_exception
+    assert_raise(ArgumentError) {Module.create(nil, :superclass => Object)}
+  end
+end
+
+class ModuleWithParentTest < Test::Unit::TestCase
+  def setup
+    @autopilot = Module.create('Autopilot', :parent => Ford)
+  end
+  
+  def test_should_be_nested_within_parent
+    assert Ford.const_defined?('Autopilot')
+  end
+  
+  def teardown
+    Ford.send(:remove_const, 'Autopilot')
+  end
+end

data/test/test_helper.rb

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

metadata

@@ -0,0 +1,63 @@
+--- !ruby/object:Gem::Specification 
+name: pluginaweek-module_creation_helper
+version: !ruby/object:Gem::Version 
+  version: 0.2.0
+platform: ruby
+authors: 
+- Aaron Pfeifer
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-08 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: Adds a helper method for creating new modules and classes at runtime
+email: aaron@pluginaweek.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/module_creation_helper
+- lib/module_creation_helper/extensions
+- lib/module_creation_helper/extensions/module.rb
+- lib/module_creation_helper.rb
+- test/module_creation_helper_test.rb
+- test/test_helper.rb
+- CHANGELOG.rdoc
+- init.rb
+- LICENSE
+- Rakefile
+- README.rdoc
+has_rdoc: true
+homepage: http://www.pluginaweek.org
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: pluginaweek
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Adds a helper method for creating new modules and classes at runtime
+test_files: 
+- test/module_creation_helper_test.rb