modularity 0.4.0 → 0.4.1

data/README.rdoc

@@ -1 +1,98 @@
 = modularity - Traits and partial classes for Ruby
+
+Modularity provides traits and partial classes for Ruby.
+This lets you organize large models into multiple source files.
+It also allows very simple definition of meta-programming macros,
+as you might now from <tt>acts_as_something</tt> type of plugins,
+or the macros Rails provides for your models.
+
+Modularity traits are to your models what partials are for your Rails views.
+
+== Example 1: Splitting a model into multiple source files
+
+Models are often concerned with multiple themes like "authentication", "contact info" or "permissions", each requiring
+a couple of validations and callbacks here, and some method there. Modularity lets you organize your model into multiple
+partial classes, so each file can deal with a single aspect of your model:
+
+  # app/model/user.rb
+  class User < ActiveRecord::Base
+    does "user/authentication"
+    does "user/address"
+  end
+  
+  # app/model/user/authentication.rb
+  module User::Authentication
+    as_trait do
+      # methods, validations, etc. regarding usernames and passwords go here
+    end
+  end
+  
+  # app/model/user/permissions.rb
+  module User::Permissions
+    as_trait do
+      # methods, validations, etc. regarding contact information go here
+    end
+  end
+
+== Example 2: Easy meta-programming macros
+
+Ruby allows you to construct classes using meta-programming macros like <tt>acts_as_tree</tt> or <tt>has_many :items</tt>.
+These macros will add methods, callbacks, etc. to the calling class. Hoever, right now Ruby (and Rails) makes it awkward to define
+such macros in your project as part of your application domain.
+
+Modularity allows you to extract common behaviour into reusable macros by defining traits with parameters. Your macros can live in your
+application, allowing you to express your application domain in both classes and macros.
+
+Here is an example of a <tt>strip_field</tt> macro, which created setter methods that remove leading and trailing whitespace from newly assigned values:
+
+  # app/model/article.rb
+  class Article
+    does "strip_fields", :name, :brand
+  end
+
+  # app/model/shared/strip_fields.rb
+  module StripFields
+    as_trait do |*fields|
+      fields.each do |field|
+        define_method("#{field}=") do |value|
+          self[field] = value.strip
+        end
+      end
+    end
+  end
+  
+We like to add <tt>app/models/shared</tt> and <tt>app/controllers/shared</tt> to the load paths of our Rails projects. These are great places to store macros
+that are re-used from multiple classes.
+
+== Example 3: Mixins with class methods
+
+Using a module to add both instance methods and class methods is {very awkward}[http://redcorundum.blogspot.com/2006/06/mixing-in-class-methods.html].
+Modularity does away with the clutter and lets you say this:
+
+  # app/model/model.rb
+  class Model
+    does "mixin"
+  end
+
+  module Mixins
+    as_trait do
+      def instance_method
+        # ...
+      end
+      def self.class_method
+        # ..
+      end
+  end
+  
+<tt>private</tt> and <tt>protected</tt> will also work as expected when defining a trait.
+
+== Installation
+
+  sudo gem sources -a http://gemcutter.org
+  sudo gem install modularity
+
+== Credits
+
+Henning Koch
+
+{www.makandra.de}[http://www.makandra.de/]

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.4.1

data/modularity.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{modularity}
-  s.version = "0.4.0"
+  s.version = "0.4.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Henning Koch"]
-  s.date = %q{2010-02-13}
+  s.date = %q{2010-02-15}
   s.description = %q{Traits and partial classes for Ruby}
   s.email = %q{github@makandra.de}
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: modularity
 version: !ruby/object:Gem::Version 
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors: 
 - Henning Koch
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-02-13 00:00:00 +01:00
+date: 2010-02-15 00:00:00 +01:00
 default_executable: 
 dependencies: []