.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Rose::DB::Object::Util 3pm"
.TH Rose::DB::Object::Util 3pm "2012-04-15" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Rose::DB::Object::Util \- Utility functions for use in Rose::DB::Object subclasses and method makers.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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);
\&    }
\&    ...
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
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 \*(L"inflate\*(R" the values.  The is_loading function will tell you when these steps can safely be skipped.
.PP
Similarly, it may be useful to set these state characteristics in your code.  The \f(CW\*(C`set_sate_*\*(C'\fR functions provide that ability.
.SH "EXPORTS"
.IX Header "EXPORTS"
\&\f(CW\*(C`Rose::DB::Object::Util\*(C'\fR does not export any function names by default.
.PP
The 'get_state' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:get_state);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 3
\&    is_in_db()
\&    is_loading()
\&    is_saving()
.Ve
.PP
The 'set_state' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:set_state);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 3
\&    set_state_in_db()
\&    set_state_loading()
\&    set_state_saving()
.Ve
.PP
The 'unset_state' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:unset_state);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 3
\&    unset_state_in_db()
\&    unset_state_loading()
\&    unset_state_saving()
.Ve
.PP
the 'state' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:unset_state);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 9
\&    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()
.Ve
.PP
The 'columns' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:columns);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 5
\&    get_column_value_modified()
\&    set_column_value_modified()
\&    unset_column_value_modified()
\&    modified_column_names()
\&    has_modified_columns()
.Ve
.PP
The 'children' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:children);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 2
\&    has_loaded_related()
\&    has_modified_children()
.Ve
.PP
The 'all' tag:
.PP
.Vb 1
\&    use Rose::DB::Object::Util qw(:all);
.Ve
.PP
will cause the following function names to be imported:
.PP
.Vb 3
\&    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()
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBget_column_value_modified \s-1OBJECT\s0, \s-1COLUMN\s0\fR" 4
.IX Item "get_column_value_modified OBJECT, COLUMN"
Returns true if the column named \s-1COLUMN\s0 in \s-1OBJECT\s0 is modified, false otherwise.
.IP "\fBhas_loaded_related [ \s-1OBJECT\s0, \s-1NAME\s0 | \s-1PARAMS\s0 ]\fR" 4
.IX Item "has_loaded_related [ OBJECT, NAME | PARAMS ]"
Given an \s-1OBJECT\s0 and a foreign key or relationship name, return true if one or more related objects have been loaded into \s-1OBJECT\s0, false otherwise.
.Sp
If the name is passed as a plain string \s-1NAME\s0, 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:
.Sp
.Vb 1
\&    has_loaded_related($object, \*(Aqbar\*(Aq);
.Ve
.Sp
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 \f(CW\*(C`foreign_key\*(C'\fR or \f(CW\*(C`relationship\*(C'\fR parameter.  You must also pass the object as the value of the \f(CW\*(C`object\*(C'\fR parameter.  Example:
.Sp
.Vb 2
\&    has_loaded_related(object => $object, foreign_key => \*(Aqbar\*(Aq);
\&    has_loaded_related(object => $object, relationship => \*(Aqbar\*(Aq);
.Ve
.IP "\fBhas_modified_children \s-1OBJECT\s0\fR" 4
.IX Item "has_modified_children OBJECT"
Returns true if \s-1OBJECT\s0 has_loaded_related objects, at least one of which has_modified_columns or has_modified_children, false otherwise.
.IP "\fBhas_modified_columns \s-1OBJECT\s0\fR" 4
.IX Item "has_modified_columns OBJECT"
Returns true if \s-1OBJECT\s0 has any modified columns, false otherwise.
.IP "\fBis_in_db \s-1OBJECT\s0\fR" 4
.IX Item "is_in_db OBJECT"
Given the Rose::DB::Object\-derived object \s-1OBJECT\s0, returns true if the object was loaded from, or has ever been saved into, the database, or false if it has not.
.IP "\fBis_loading \s-1OBJECT\s0\fR" 4
.IX Item "is_loading OBJECT"
Given the Rose::DB::Object\-derived object \s-1OBJECT\s0, returns true if the object is currently being loaded, false otherwise.
.IP "\fBis_saving \s-1OBJECT\s0\fR" 4
.IX Item "is_saving OBJECT"
Given the Rose::DB::Object\-derived object \s-1OBJECT\s0, returns true if the object is currently being saved, false otherwise.
.IP "\fBmodified_column_names \s-1OBJECT\s0\fR" 4
.IX Item "modified_column_names OBJECT"
Returns a list containing the names of all the modified columns in \s-1OBJECT\s0.
.IP "\fBset_column_value_modified \s-1OBJECT\s0, \s-1COLUMN\s0\fR" 4
.IX Item "set_column_value_modified OBJECT, COLUMN"
Mark the column named \s-1COLUMN\s0 in \s-1OBJECT\s0 as modified.
.IP "\fBunset_column_value_modified \s-1OBJECT\s0, \s-1COLUMN\s0\fR" 4
.IX Item "unset_column_value_modified OBJECT, COLUMN"
Clear the modified mark, if any, on the column named \s-1COLUMN\s0 in \s-1OBJECT\s0.
.IP "\fBset_state_in_db \s-1OBJECT\s0\fR" 4
.IX Item "set_state_in_db OBJECT"
Mark the Rose::DB::Object\-derived object \s-1OBJECT\s0 as having been loaded from or saved into the database at some point in the past.
.IP "\fBset_state_loading \s-1OBJECT\s0\fR" 4
.IX Item "set_state_loading OBJECT"
Indicate that the Rose::DB::Object\-derived object \s-1OBJECT\s0 is currently being loaded from the database.
.IP "\fBset_state_saving \s-1OBJECT\s0\fR" 4
.IX Item "set_state_saving OBJECT"
Indicate that the Rose::DB::Object\-derived object \s-1OBJECT\s0 is currently being saved into the database.
.IP "\fBunset_state_in_db \s-1OBJECT\s0\fR" 4
.IX Item "unset_state_in_db OBJECT"
Mark the Rose::DB::Object\-derived object \s-1OBJECT\s0 as \fBnot\fR having been loaded from or saved into the database at some point in the past.
.IP "\fBunset_state_loading \s-1OBJECT\s0\fR" 4
.IX Item "unset_state_loading OBJECT"
Indicate that the Rose::DB::Object\-derived object \s-1OBJECT\s0 is \fBnot\fR currently being loaded from the database.
.IP "\fBunset_state_saving \s-1OBJECT\s0\fR" 4
.IX Item "unset_state_saving OBJECT"
Indicate that the Rose::DB::Object\-derived object \s-1OBJECT\s0 is \fBnot\fR currently being saved into the database.
.SH "AUTHOR"
.IX Header "AUTHOR"
John C. Siracusa (siracusa@gmail.com)
.SH "LICENSE"
.IX Header "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.