NAME

       Rose::DB::Object::Util - Utility functions for use in Rose::DB::Object subclasses and
       method makers.

SYNOPSIS

         package MyDBObject;

         use Rose::DB::Object::Util qw(:all);

         use Rose::DB::Object;
         our @ISA = qw(Rose::DB::Object);
         ...
         sub whatever
         {
           my($self) = shift;
           ...
           if(is_loading($self))
           {
             ...
             set_state_in_db($self);
           }
           ...
         }

DESCRIPTION

       Rose::DB::Object::Util provides functions that are useful for developers who are
       subclassing Rose::DB::Object or otherwise extending or modifying its behavior.

       Rose::DB::Objects have some awareness of their current situation.  Certain optimizations
       rely on this awareness.  For example, when loading column values directly from the
       database, there's no reason to validate the format of the data or immediately "inflate"
       the values.  The is_loading function will tell you when these steps can safely be skipped.

       Similarly, it may be useful to set these state characteristics in your code.  The
       "set_sate_*" functions provide that ability.

EXPORTS

       "Rose::DB::Object::Util" does not export any function names by default.

       The 'get_state' tag:

           use Rose::DB::Object::Util qw(:get_state);

       will cause the following function names to be imported:

           is_in_db()
           is_loading()
           is_saving()

       The 'set_state' tag:

           use Rose::DB::Object::Util qw(:set_state);

       will cause the following function names to be imported:

           set_state_in_db()
           set_state_loading()
           set_state_saving()

       The 'unset_state' tag:

           use Rose::DB::Object::Util qw(:unset_state);

       will cause the following function names to be imported:

           unset_state_in_db()
           unset_state_loading()
           unset_state_saving()

       the 'state' tag:

           use Rose::DB::Object::Util qw(:unset_state);

       will cause the following function names to be imported:

           is_in_db()
           is_loading()
           is_saving()
           set_state_in_db()
           set_state_loading()
           set_state_saving()
           unset_state_in_db()
           unset_state_loading()
           unset_state_saving()

       The 'columns' tag:

           use Rose::DB::Object::Util qw(:columns);

       will cause the following function names to be imported:

           get_column_value_modified()
           set_column_value_modified()
           unset_column_value_modified()
           modified_column_names()
           has_modified_columns()

       The 'children' tag:

           use Rose::DB::Object::Util qw(:children);

       will cause the following function names to be imported:

           has_loaded_related()
           has_modified_children()

       The 'all' tag:

           use Rose::DB::Object::Util qw(:all);

       will cause the following function names to be imported:

           is_in_db()
           is_loading()
           is_saving()

           set_state_in_db()
           set_state_loading()
           set_state_saving()

           unset_state_in_db()
           unset_state_loading()
           unset_state_saving()

           get_column_value_modified()
           set_column_value_modified()
           unset_column_value_modified()
           modified_column_names()
           has_modified_columns()

           has_loaded_related()
           has_modified_children()

FUNCTIONS

       get_column_value_modified OBJECT, COLUMN
           Returns true if the column named COLUMN in OBJECT is modified, false otherwise.

       has_loaded_related [ OBJECT, NAME | PARAMS ]
           Given an OBJECT and a foreign key or relationship name, return true if one or more
           related objects have been loaded into OBJECT, false otherwise.

           If the name is passed as a plain string NAME, then a foreign key with that name is
           looked up.  If no such foreign key exists, then a relationship with that name is
           looked up.  If no such relationship or foreign key exists, a fatal error will occur.
           Example:

               has_loaded_related($object, 'bar');

           It's generally not a good idea to add a foreign key and a relationship with the same
           name, but it is technically possible.  To specify the domain of the name, pass the
           name as the value of a "foreign_key" or "relationship" parameter.  You must also pass
           the object as the value of the "object" parameter.  Example:

               has_loaded_related(object => $object, foreign_key => 'bar');
               has_loaded_related(object => $object, relationship => 'bar');

       has_modified_children OBJECT
           Returns true if OBJECT has_loaded_related objects, at least one of which
           has_modified_columns or has_modified_children, false otherwise.

       has_modified_columns OBJECT
           Returns true if OBJECT has any modified columns, false otherwise.

       is_in_db OBJECT
           Given the Rose::DB::Object-derived object OBJECT, returns true if the object was
           loaded from, or has ever been saved into, the database, or false if it has not.

       is_loading OBJECT
           Given the Rose::DB::Object-derived object OBJECT, returns true if the object is
           currently being loaded, false otherwise.

       is_saving OBJECT
           Given the Rose::DB::Object-derived object OBJECT, returns true if the object is
           currently being saved, false otherwise.

       modified_column_names OBJECT
           Returns a list containing the names of all the modified columns in OBJECT.

       set_column_value_modified OBJECT, COLUMN
           Mark the column named COLUMN in OBJECT as modified.

       unset_column_value_modified OBJECT, COLUMN
           Clear the modified mark, if any, on the column named COLUMN in OBJECT.

       set_state_in_db OBJECT
           Mark the Rose::DB::Object-derived object OBJECT as having been loaded from or saved
           into the database at some point in the past.

       set_state_loading OBJECT
           Indicate that the Rose::DB::Object-derived object OBJECT is currently being loaded
           from the database.

       set_state_saving OBJECT
           Indicate that the Rose::DB::Object-derived object OBJECT is currently being saved into
           the database.

       unset_state_in_db OBJECT
           Mark the Rose::DB::Object-derived object OBJECT as not having been loaded from or
           saved into the database at some point in the past.

       unset_state_loading OBJECT
           Indicate that the Rose::DB::Object-derived object OBJECT is not currently being loaded
           from the database.

       unset_state_saving OBJECT
           Indicate that the Rose::DB::Object-derived object OBJECT is not currently being saved
           into the database.

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

LICENSE

       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.