= 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

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.  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

This plugin does not depend on the presence of any other plugins.