pluginaweek / attribute_predicates

= boolean_attributes

+boolean_attributes+ adds automatic generation of predicate methods (truth
accessors) when defining attributes using +attr+, +attr_reader+, +attr_writer+, and
+attr_accessor+.

== Resources

Wiki

* http://wiki.pluginaweek.org/Boolean_attributes

API

* http://api.pluginaweek.org/boolean_attributes

Development

* http://dev.pluginaweek.org/browser/trunk/boolean_attributes

Source

* http://svn.pluginaweek.org/trunk/boolean_attributes

== Description

If you use boolean attributes within your classes, and want to use the
predicate-style methods (i.e. "def foo?; end"), then you have to define these
yourself.  This is a repetitive task especially if you want to query attributes
that may not necessarily contain just true/false.  For example, an attribute
may contain 0, or the string "false".  In this case, you would need to do
special checks to see whether or not the value is really false.

+boolean_attributes+ makes it easy by automatically generating predicate-style
methods for all attributes that are created using +attr+, +attr_reader+, +attr_writer+,
and +attr_accessor+.  In addition, there is support for ActiveRecord's
non-standard truth accessor implementation (see below).

All of these shortcuts have the same interface and meaning as you would normally
find.

== Usage

=== Ruby Attributes

==== attr

This method takes a symbol (the name of the attribute) and an optional argument
for whether or not the attribute is writeable.  For example,

  module Mod
    attr :is_okay, true
  end

is equivalent to:

  module Mod
    def is_okay
      @is_okay
    end
    
    def is_okay=(val)
      @is_okay = value
    end
    
    def is_okay?
      !is_okay.blank?
    end
  end

==== attr_reader

This method is equivalent to calling <tt>battr(symbol, false)</tt> on each symbol in
turn.  For example,

  module Mod
    attr_reader :is_good, :is_bad
  end
  
  Mod.instance_methods.sort   #=> ["is_bad", "is_bad?", "is_good", "is_good?"]

==== attr_writer

This method creates an accessor and predicate method for each symbol in turn.
For example,

  module Mod
    attr_writer :is_good, :is_bad
  end
  
  Mod.instance_methods.sort   #=> ["is_bad=", "is_bad?", "is_good=", "is_good?"]

==== attr_accessor

This method is equivalent to calling <tt>attr(symbol, true)</tt> on each symbol in
turn.  For example,

  module Mod
    attr_accessor :is_good, :is_bad
  end
  
  Mod.instance_methods.sort   #=> ["is_bad", "is_bad=", "is_bad?", "is_good", "is_good=", "is_good?"]

=== ActiveRecord Attributes

The predicate method has a slightly more complex implementation for subclasses
of ActiveRecord::Base.  It is built from how ActiveRecord implemented querying
attributes.  The following lists show which values will return false/true:

For String, the following values return true:
* "true"
* "t"

For Integer, the following values return true:
* 1

For all other types, the predicate will return false.

== Testing

Before you can run any tests, the following gem must be installed:
* plugin_test_helper[http://wiki.pluginaweek.org/Plugin_test_helper]

To run against a specific version of Rails:

  rake test RAILS_FRAMEWORK_ROOT=/path/to/rails

== Dependencies

* Rails 2.0 or later

== References

* Yurii Rashkovskii - {Boolean Attributes in 
Ruby}[http://rashkovskii.com/articles/2007/01/04/boolean-attributes-in-ruby]
* Evan Weaver - {truth accessors in rails}[http://blog.evanweaver.com/articles/2007/01/05/truth-accessors-in-rails]