ruby script/plugin install http://svn.jcoglan.com/flagger/tags/0.9.5/flagger/

Boolean finders
=====================

Flagger allows you to use dynamic finders on boolean attributes without using "find_all_by_". So, using the above example, you can happily call Order.paid to get all your paid orders, without defining the method yourself. In addition, you can call Order.unpaid, and you will get back all the orders for which paid == false. The full list of allowed prefixes is:

"in", "im", "un", "non", "dis", "de", "ir", and "not_"

If your model has an attribute whose name already begins with one of these, Flagger will take this into account. For example, TallStory.implausible returns all the TallStory records for which implausible == true. You can chop off the prefix as well: TallStory.plausible does what you'd expect.

Only one prefix will be added to or removed from the attribute name you use to try and find matching attribute names. Fact.undeniable works if the "Fact" model has an attribute called "undeniable", "deniable", "inundeniable", "imundeniable" ... or "not_undeniable". Attribute names are always checked in this order, and Flagger will use the first one that exists. If no attribute match can be found, the exception raised by ActiveRecord::Base's built-in method_missing code is reraised.

Attribute names can be chained together in a similar fashion to that allowed by "find_by_" and friends. You can use "and" and "but" to separate names, so you could write:

  orders = Order.paid_and_delivered
  orders.first.paid?
  #=> true
  orders.first.delivered?
  #=> true

  martinis = Cocktail.shaken_but_not_stirred
  martinis.first.shaken?
  #=> true
  martinis.first.stirred?
  #=> false

Dynamic markers
====================

Attribute-based markers perform the converse task to boolean finders - they set boolean attributes rather than retrieving based on them. They mark (flag) records as having certain properties. Their syntax is very similar to that for finders:

  order = Order.find(:all).first
  order.mark_as_paid
  order.paid?
  #=> true
  order.mark_as_delivered_but_not_signed_for
  order.delivered?
  #=> true
  order.signed_for?
  #=> false

These methods do not save the attributes to the database. If you want to save the attributes, end the method call with a !.

"mark_as_" methods detect the column type for each attribute and set values accordingly. "true"/"false" are used for :boolean fields, 1/0 for numeric fields, and "1"/"0" for :string/:text fields.

To perform tasks related to flagging, you can define "after_mark_as_" methods on your models. Each callback can include one attribute name (with or without prefixes as appropriate) and can end with a ! to denote whether it should be called on database saves or not. For example, Order#after_mark_as_unpaid! will be called after mark_as_unpaid!, mark_as_not_paid! and mark_as_accepted_but_not_paid!, but not after mark_as_unpaid (no exclamation mark). All the existing callbacks that apply to a "mark_as_" call will be called, but only if a change has been made to the relevant attribute.

There is currently no advanced documentation for this plugin.