<commit_before>= modularity - Traits and partial classes for Ruby

Modularity provides traits and partial classes for Ruby.
This 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. This also lets you organize
large models into multiple source files in a way that is less awkward
than using modules.

Modularity traits are to your models what partials are for your Rails views.

== Example 1: 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. However, 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/models/article.rb
  class Article
    does "strip_fields", :name, :brand
  end

  # app/models/shared/strip_fields_trait.rb
  module StripFieldsTrait
    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 2: 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/models/model.rb
  class Model
    does "mixin"
  end

  # app/models/mixin_trait.rb
  module MixinTrait
    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.

== Example 3: 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/models/user.rb
  class User < ActiveRecord::Base
    does "user/authentication"
    does "user/address"
  end

  # app/models/user/authentication_trait.rb
  module User::AuthenticationTrait
    as_trait do
      # methods, validations, etc. regarding usernames and passwords go here
    end
  end

  # app/models/user/permissions_trait.rb
  module User::PermissionsTrait
    as_trait do
      # methods, validations, etc. regarding contact information go here
    end
  end<commit_msg>just a little detail: missing end<commit_after>= modularity - Traits and partial classes for Ruby

Modularity provides traits and partial classes for Ruby.
This 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. This also lets you organize
large models into multiple source files in a way that is less awkward
than using modules.

Modularity traits are to your models what partials are for your Rails views.

== Example 1: 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. However, 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/models/article.rb
  class Article
    does "strip_fields", :name, :brand
  end

  # app/models/shared/strip_fields_trait.rb
  module StripFieldsTrait
    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 2: 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/models/model.rb
  class Model
    does "mixin"
  end

  # app/models/mixin_trait.rb
  module MixinTrait
    as_trait do
      def instance_method
        # ...
      end
      def self.class_method
        # ..
      end
    end
  end
  
<tt>private</tt> and <tt>protected</tt> will also work as expected when defining a trait.

== Example 3: 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/models/user.rb
  class User < ActiveRecord::Base
    does "user/authentication"
    does "user/address"
  end

  # app/models/user/authentication_trait.rb
  module User::AuthenticationTrait
    as_trait do
      # methods, validations, etc. regarding usernames and passwords go here
    end
  end

  # app/models/user/permissions_trait.rb
  module User::PermissionsTrait
    as_trait do
      # methods, validations, etc. regarding contact information go here
    end
  end
{'fraction_non_alphanumeric': 0.0631367706082124, 'fraction_numerical': 0.002778635381290522, 'mean_word_length': 3.6511127063890885, 'pattern_counts': {'":': 0, '<': 37, '<?xml version=': 0, '>': 35, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '284553', 'n_tokens_mistral': 1802, 'n_tokens_neox': 1743, 'n_words': 795}