can_be 0.1.0 → 0.2.0

data/.travis.yml

@@ -1,4 +1,9 @@
 language: ruby
+
 rvm:
   - 1.9.3
   - 1.9.2
+
+gemfile:
+  - gemfiles/3.1.gemfile
+  - gemfiles/3.2.gemfile

data/.yardopts

@@ -0,0 +1,4 @@
+LICENSE.txt
+README.md
+CHANGELOG.md
+lib/**/*.rb

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## Version 0.1.0
+
+Initial release.
+
+## Version 0.2.0
+
+Added details functionality for storing custom fields per type.

data/README.md

@@ -1,6 +1,6 @@
-# CanBe [![Build Status](https://secure.travis-ci.org/mstarkman/can_be.png?branch=master)](https://travis-ci.org/mstarkman/can_be)
+# CanBe [![Build Status](https://secure.travis-ci.org/mstarkman/can_be.png?branch=master)](https://travis-ci.org/mstarkman/can_be) [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/mstarkman/can_be)
 
-Adds helper methods to your Active Record models to control the type of record.
+CanBe allows you to track the type of your ActiveRecord model in a consistent simple manner.  With just a little configuration on your part, each type of record can contain different attributes that are specifc to that type of record.  From a data modelling perspective this is preferred over [ActiveRecord STI](http://api.rubyonrails.org/classes/ActiveRecord/Base.html#label-Single+table+inheritance) since you will not have many columns in your database that have null values.  Under the hood, CanBe uses one-to-one [Polymorphic Associations](http://guides.rubyonrails.org/association_basics.html#polymorphic-associations) to accomplish the different attributes per type.
 
 ## Installation
 
@@ -16,11 +16,11 @@ Or install it yourself as:
 
     $ gem install can_be
 
-## Usage
+## Database Configuration (via migrations)
+
+In its simplest form, you only need to add a string attribute (column) to the model can be different types.  By default, this attribute must be named `can_be_type`.  However, you can have the attribute be named anything that you would like, you just need to tell CanBe what it is.  Indexing this column is your choice.
 
-Before adding it to your model, you will need to add a database field to
-your model.  By default, the `can_be` gem expects your field to be
-called `can_be_type`.  However, this can be changed.
+Example migration:
 
 ```ruby
 class AddCanBeTypeToAddresses < ActiveRecord::Migration
@@ -31,51 +31,117 @@ class AddCanBeTypeToAddresses < ActiveRecord::Migration
 end
 ```
 
-Once you've installed the gem, you will have access to the `can_be` method in your models.  The `can_be` method will take a list of types (as symbols) that your model can be represented as.
+### Details Configuration
+
+If you want to store different attributes (columns), there are some more columns that you will need to add to your model, `details_id` and `details_type`.  These fields will be used to store the relationships to the details information.  Indexing these columns is your choice.
+
+Example migration:
 
 ```ruby
-class Address < ActiveRecord::Base
-  can_be :home_address, :work_address, :vacation_address
+class AddCanBeDetailsToAddresses < ActiveRecord::Migration
+  def change
+    add_column :addresses, :details_id, :integer
+    add_column :addresses, :details_type, :string
+    add_index :addresses, [:details_id, :details_type]
+  end
 end
 ```
 
-### Methods Added to your model
+You will also need to create the models that will be used to represent the details attributes for each type.  You will need to configure the model to be a details model be calling the `can_be_detail` method in your model.  You do not need to specify a details model for each CanBe type if there are not any extra attributes required for that type.
 
-The following methods will then be added to your model for each of the types based on the example above.
+## Model Configuration
 
-#### Class Methods
+To add CanBe to your model, you simply need to call the `can_be` method
+on your model.
 
-* `create_home_address` - Creates a new address model in the database with the type of `home_address`
-* `find_by_can_be_types` - Accepts a list of types and returns the results of the database query (note: this is only added once, not for each type)
-* `home_addresses` - Returns a list of the records with a type of `home_address`
-* `new_home_address` - Instantiates a new address model instance with the type of `home_address`
+```ruby
+class Address < ActiveRecord::Base
+  can_be :home_address, :work_address, :vacation_address
+end
+```
 
-#### Instance Methods
+The `can_be` method will take in a list of valid types that will be used by CanBe.  There is an optional last parameter that is a hash of the options.  This is a list of valid options.
 
-* `change_to_home_address` - Changes the record to a `home_address` type (does not save it to the database)
-* `change_to_home_address!` - Changes the record to a `home_address` type and saves it to the database
-* `home_address?` - Returns true if the record is a `home_address` type
+* `:default_type` - Sets the default value for when a new record is instantiated or created (it is the first value in the list by default)
+* `:field_name` - Sets the ActiveRecord field name that is to be used (if not specified, CanBe expects a `can_be_type` attribute to be present)
 
-### Options
+Here is an example of the options.
 
-The following options can be added to the `can_be` method call.
+```ruby
+class Person < ActiveRecord::Base
+  can_be :male, :female, field_name: :gender, default_type: :female
+end
+```
 
-* `default_type` - Sets the default value for when a new record is instantiated (it is the first value in the list by default)
-* `field_name` - Sets the ActiveRecord field name that is to be used (by default it expects a `can_be_type` field to be present)
+### Details Model Configuration
 
-Here is an example.
+In order to wire up a model to be a CanBe details model, you will need
+to call the `can_be_detail` method on that model.
 
 ```ruby
-class Person < ActiveRecord::Base
-  can_be :male, :female, field_name: :gender, default_type: :female
+class HomeAddressDetail < ActiveRecord::Base
+  can_be_detail :address, :home_address
 end
 ```
+The `can_be_detail` method take in two parameters.
+
+The first is the link to the CanBe model.  This must be a symbol that will reference the CanBe model.  In order to create the proper symbol, you can execute the following into your Rails console: `<ModelName>.name.underscore.to_sym`.  Here is an example: `Address.name.underscore.to_sym`.  In the above example, this will be used for the `Address` CanBe model.
+
+The second parameter is the CanBe type that this model is to be used for.  In the example above, the `HomeAddressDetail` model will used for the `:home_address` CanBe type.
+
+## Usage
+
+The CanBe gem will provide you a lot methods to handle your type processing in an easy and consistent manner.
+
+### Instantiating New Models
+
+You can continue to instantiate your CanBe models by using the `new` method.  When you do, CanBe will ensure that the type of the record is assigned the detault CanBe type for your model.
+
+There are also some helper methods put on your model to make it easier to instantiate the type of model that you want.  These methods will take the form of `new_<CanBe type>`.  For example, you can call `Address.new_home_address`.  These methods will take the same parameters as the base `new` method provided by ActiveRecord.
+
+### Creating New Models
+
+You can continue to create your CanBe models by using the `create` method.  When you do, CanBe will ensure that the type of the record is assigned the detault CanBe type for your model.
+
+There are also some helper methods put on your model to make it easier to create the type of model that you want.  These methods will take the form of `create_<CanBe type>`.  For example, you can call `Address.create_home_address`.  These methods will take the same parameters as the base `create` method provided by ActiveRecord.
+
+### Changing CanBe Types
+
+There are several ways to change the type of record that you are working with.  You can access the `can_be_type` attribute (or other attribute if you specified the field to be used) and change the value directly.
+
+There are also instance methods provided on your model that allow for changing to a specific CanBe type.
+
+You can change the type of record and not persist it immediately to the database by calling the appropriate `change_to_<CanBe type>` method.  For example, you can call `Address.new.change_to_work_address` method to change the record to be of CanBe type `:work_address`.
+
+If you want to change the type of the record and persist it to the database immediately, you can call the appropriate `change_to_<CanBe type>!` method.  For example, this method call will change the type of record to `:work_address` and persist the change to the database: `Address.create.change_to_work_address!`
+
+There is a validator for the CanBe field, that will unsure that the CanBe field is set to one of the CanBe types before persisting the record. 
+
+NOTE: that when you are changing the type of record the details record will be changed to the correct CanBe details record.  New records will only be persisted to the database when the CanBe model is persisted.  If you change the CanBe model to a type that does not have a corresponding details model, `nil` will be stored for the details.
+
+### Boolean Evaluation
+
+With CanBe, it is easy to determine the type of record that you are working with.  This is accomplished by calling the `<CanBe type>?` on the instance of your model.  For example if you wanted to see if the `Address` instance you are working with, you would call `Address.first.home_address?` and it would return `true` or `false` depending on the CanBe type of the record.
+
+### Finding Records
+
+There are two ways to find specific types of records.  You can use the `find_by_can_be_types` method, which takes in a list of the CanBe types that you want to find.  For example, if you wanted to find all of the home and work addresses you would call `Address.find_by_can_be_types :home_address, :work_address`.
+
+Methods are also defined on your CanBe model that will find all of the records for a specific CanBe type.  These methods take the form of `<pluralized CanBe type>`.  For example, `Address.home_addresses` would return all of the records with a type of `:home_address`.
+
+### Accessing the Details
+
+If you want to access the details model, you can call the `details` method on your instance and the instance of your model will be returned.  If the type of model that you are using does not have a details model, `nil` will be returned.
+
+When you persist your CanBe model to the database, your details model will automatically be persisted.
 
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
+    * Make sure to include the appropriate specs
+    * Specs can be run by executing the `rake` command in the terminal
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
 

data/can_be.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |gem|
   gem.version       = CanBe::VERSION
   gem.authors       = ["Mark Starkman"]
   gem.email         = ["mrstarkman@gmail.com"]
-  gem.description   = %q{Adds helper methods to your Active Record models to control the type of record.}
-  gem.summary       = %q{Adds helper methods to your Active Record models to control the type of record.}
+  gem.description   = %q{CanBe allows you to track the type of your ActiveRecord model in a consistent simple manner.  With just a little configuration on your part, each type of record can contain different attributes that are specifc to that type of record.}
+  gem.summary       = %q{CanBe allows you to track the type of your ActiveRecord model in a consistent simple manner.  With just a little configuration on your part, each type of record can contain different attributes that are specifc to that type of record.  From a data modelling perspective this is preferred over ActiveRecord STI since you will not have many columns in your database that have null values.  Under the hood, CanBe uses one-to-one Polymorphic Associations to accomplish the different attributes per type.}
   gem.homepage      = ""
 
   gem.files         = `git ls-files`.split($/)

data/gemfiles/3.1.gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gem "activerecord", "~> 3.1.0"
+gem "activesupport", "~> 3.1.0"
+
+gemspec :path=>"../"
+

data/gemfiles/3.2.gemfile

@@ -0,0 +1,7 @@
+source "http://rubygems.org"
+
+gem "activerecord", "~> 3.2.0"
+gem "activesupport", "~> 3.2.0"
+
+gemspec :path=>"../"
+

data/lib/can_be.rb

@@ -1,5 +1,7 @@
 require "can_be/version"
-require "can_be/initializer"
+require "can_be/config"
+require "can_be/processor"
+require "can_be/builder"
 require "can_be/model_extensions"
 require "can_be/railtie" if defined? Rails
 

data/lib/can_be/builder.rb

@@ -0,0 +1,7 @@
+require 'can_be/builder/can_be'
+require 'can_be/builder/can_be_detail'
+
+module CanBe
+  module Builder
+  end
+end

data/lib/can_be/builder/can_be.rb

@@ -0,0 +1,106 @@
+module CanBe
+  module Builder
+    class CanBe
+      def self.build(klass)
+        new(klass).define_methods
+      end
+
+      def initialize(klass)
+        @klass = klass
+      end
+
+      def define_methods
+        define_processor
+        define_instance_methods
+        define_class_methods
+        define_validations
+        define_details
+      end
+
+      private
+      def define_processor
+        @klass.instance_eval do
+          define_method :can_be_processor do
+            @can_be_processor ||= Processor::Instance.new self
+          end
+        end
+
+        @klass.class_eval do
+          define_singleton_method :can_be_processor do
+            @can_be_processor ||= Processor::Klass.new self
+          end
+        end
+      end
+
+      def define_instance_methods
+        klass = @klass
+
+        klass.instance_eval do
+          define_method "#{klass.can_be_config.field_name}=" do |value|
+            can_be_processor.field_value = value
+          end
+        end
+
+        klass.can_be_config.types.each do |t|
+          klass.instance_eval do
+            define_method "#{t}?" do
+              can_be_processor.boolean_eval(t)
+            end
+
+            define_method "change_to_#{t}" do
+              can_be_processor.update_field(t)
+            end
+
+            define_method "change_to_#{t}!" do
+              can_be_processor.update_field(t, true)
+            end
+          end
+        end
+      end
+
+      def define_class_methods
+        @klass.class_eval do
+          define_singleton_method :find_by_can_be_types do |*types|
+            can_be_processor.find_by_types(*types)
+          end
+        end
+
+        @klass.can_be_config.types.each do |t|
+          @klass.class_eval do
+            define_singleton_method "create_#{t}" do |*args, &block|
+              can_be_processor.create(t, *args, &block)
+            end
+
+            define_singleton_method "new_#{t}" do |*args, &block|
+              can_be_processor.instantiate(t, *args, &block)
+            end
+
+            define_singleton_method t.pluralize.to_sym do
+              can_be_processor.find_by_types t
+            end
+
+            after_initialize do |model|
+              model.can_be_processor.set_default_field_value
+            end
+          end
+        end
+      end
+
+      def define_validations
+        @klass.class_eval do
+          validates_inclusion_of self.can_be_config.field_name.to_sym, in: self.can_be_config.types
+        end
+      end
+
+      def define_details
+        @klass.class_eval do
+          belongs_to :details, polymorphic: true, autosave: true, dependent: :destroy
+
+          after_initialize do |model|
+            model.can_be_processor.initialize_details
+          end
+        end
+      end
+    end
+  end
+end

data/lib/can_be/builder/can_be_detail.rb

@@ -0,0 +1,22 @@
+module CanBe
+  module Builder
+    class CanBeDetail
+      def self.build(klass, can_be_model)
+        new(klass, can_be_model).define_association
+      end
+
+      def initialize(klass, can_be_model)
+        @klass = klass
+        @can_be_model = can_be_model
+      end
+
+      def define_association
+        can_be_model = @can_be_model
+
+        @klass.class_eval do
+          has_one can_be_model, as: :details, dependent: :destroy
+        end
+      end
+    end
+  end
+end

data/lib/can_be/config.rb

@@ -0,0 +1,33 @@
+module CanBe
+  class Config
+    DEFAULT_CAN_BE_FIELD = :can_be_type
+
+    attr_reader :types
+
+    def field_name
+      @field_name || CanBe::Config::DEFAULT_CAN_BE_FIELD
+    end
+
+    def types=(types)
+      @types = types.map(&:to_s)
+    end
+
+    def default_type
+      @default_type || @types.first
+    end
+
+    def parse_options(options = {})
+      @default_type = options[:default_type].to_s
+      @field_name = options[:field_name]
+    end
+
+    def details
+      @details ||= {}
+    end
+
+    def self.add_detail_model(klass, can_be_class, can_be_type)
+      config = can_be_class.to_s.camelize.constantize.can_be_config
+      config.details[can_be_type] = klass.name
+    end
+  end
+end

data/lib/can_be/model_extensions.rb

@@ -5,13 +5,25 @@ module CanBe
     extend ActiveSupport::Concern
 
     module ClassMethods
+      def can_be_config
+        @can_be_config ||= CanBe::Config.new
+      end
+
       def can_be(*types)
         if types.last.is_a?(Hash)
           options = types.last
           types.delete types.last
         end
 
-        CanBe::Initializer.new(self, types.map(&:to_s), options).define_methods
+        can_be_config.types = types
+        can_be_config.parse_options options if options
+
+        CanBe::Builder::CanBe.build(self)
+      end
+
+      def can_be_detail(can_be_model, can_be_type)
+        CanBe::Config.add_detail_model self, can_be_model, can_be_type
+        CanBe::Builder::CanBeDetail.build(self, can_be_model)
       end
     end
   end

data/lib/can_be/processor.rb

@@ -0,0 +1,7 @@
+require 'can_be/processor/klass'
+require 'can_be/processor/instance'
+
+module CanBe
+  module Processor
+  end
+end

data/lib/can_be/processor/instance.rb

@@ -0,0 +1,61 @@
+module CanBe
+  module Processor
+    class Instance
+      def initialize(model)
+        @model = model
+        @config = model.class.can_be_config
+        @field_name = @config.field_name
+      end
+
+      def boolean_eval(t)
+        field_value == t
+      end
+
+      def update_field(t, save = false)
+        if save
+          original_details = @model.details
+          @model.update_attributes(@field_name => t)
+          original_details.destroy unless original_details.class == @model.details.class
+        else
+          self.field_value = t
+        end
+      end
+
+      def field_value=(t)
+        set_details(t)
+        @model.send(:write_attribute, @field_name, t)
+      end
+
+      def field_value
+        @model.read_attribute(@field_name)
+      end
+
+      def set_default_field_value
+        self.field_value = @config.default_type if self.field_value.nil?
+      end
+
+      def initialize_details
+        set_details(field_value.to_sym) if has_details? && !@model.details_id
+      end
+
+      private
+      def has_details?
+        @model.respond_to?(:details) && @model.respond_to?(:details_id) && @model.respond_to?(:details_type)
+      end
+
+      def set_details(t)
+        return unless has_details?
+
+        classname = @config.details[t.to_sym]
+
+        if classname
+          @model.details = classname.constantize.new
+        else
+          @model.details_id = nil
+          @model.details_type = nil
+        end
+      end
+    end
+  end
+end
+