Booleanize

Booleanize is a Ruby on Rails plugin that adds new methods to help you work with your models’ boolean attributes. Basically, it creates two new instance methods and two named scopes for each specified boolean attribute.

Instance Methods

Suppose you have a boolean attribute called active inside a User model. If you pass the name of this attribute to the booleanize method, two new methods will be created:

• active? - Returns if the attribute’s value is true or false
• active_humanize - Returns a string representing each of the true or false values.

Examples

  class User < ActiveRecord::Base
    booleanize :active
  end

  u = User.new(:active => true)
  u.active? #=> true
  u.active_humanize #=> "True"
  u.active = false
  u.active? #=> false
  u.active_humanize #=> "False"

You can also specify which strings Booleanize should use for each of the true and false values, by passing an array with the format [:attr_name, "string for true", "string for false"].

  class User < ActiveRecord::Base
    booleanize [:active, "Yes", "No"]
  end

  u = User.new(:active => true)
  u.active_humanize #=> "Yes"

Named scopes

Booleanize will create two new named_scopes for each received attribute. Using the example given above, we’ll have:

• active - Will return all the objects for which the active boolean attribute is true. It’s equivalent to

  named_scope :active, :conditions => {:active => true}

• not_active - Will return all the objects for which the active boolean attribute is false. It’s equivalent to

  named_scope :not-active, :conditions => {:active => false}

Booleanizing your booleans

The booleanize method can receive several parameters. Each parameter can be:

• A Symbol
• A Hash like {:attr_name => [‘str_for_true’, ‘str_for_false’]}
• An Array with three elements, like [:attr_name, ‘str_for_true’, ‘str_for_false’]

    class User < ActiveRecord::Base
      booleanize :active, [:smart, "Yes!", "No, very dumb"], :deleted => ["Yes, I'm gone", "No, I'm still here!"]
    end
  

You must pay attention to the fact that the Hash parameter must be the last one (or the only one), otherwise you must enclose it with {…}

  class User < ActiveRecord::Base
    booleanize {:deleted => ["Yes, I'm gone", "No, I'm still here!"]}, :active, [:smart, "Yes!", "No, very dumb"]
  end

But obviously you can pass several key/value pairs in a single Hash

  class User < ActiveRecord::Base
    booleanize :active => ["Yes, use me!", "No, I'm disabled"], :deleted => ["Yes, I'm gone", "No, I'm still here!"]
  end

Resume

It’s simple: Instead of writing this:

  class User < ActiveRecord::Base
    named_scope :active, :conditions => {:active => true}
    named_scope :not_active, :conditions => {:active => false}

    def active_humanize
      active ? "Yes" : "No"
    end

    def active?
      active ? true : false  #=> because we'll always want it to return true or false, and never nil.
    end
  end

You can simply write

  class User < ActiveRecord::Base
    booleanize :active => ["Yes", "No"]
  end

Installation

Just clone the plugin inside RAILS_ROOT/vendor/plugins

  git clone git://github.com/cassiomarques/booleanize.git

Running the tests

Booleanize is a fully tested plugin. If you’d like to run the tests, you’ll need:

• RSpec installed as a gem
• SQlite3
• SQlite3 Ruby adapter

Just enter the plugin’s folder and run

  rake spec

And happilly watch all the tests pass (if everything needed for the tests is installed in your computer).

LICENSE

Copyright © 2008 Cassio Marques

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.