Provided by: librose-db-object-perl_0.797-1_all bug

NAME

       Rose::DB::Object::MakeMethods::Date - Create date-related methods for
       Rose::DB::Object-derived objects.

SYNOPSIS

           package MyDBObject;

           use base 'Rose::DB::Object';

           use Rose::DB::Object::MakeMethods::Date
           (
             date =>
             [
               'start_date',
               'end_date' => { default => '2005-01-30' }
             ],

             datetime =>
             [
               'date_created',
               'other_date' => { type => 'datetime year to minute' },
             ],

             timestamp =>
             [
               'last_modified' => { default => '2005-01-30 12:34:56.123' }
             ],

             epoch =>
             [
               due_date    => { default => '2003-01-02 12:34:56' },
               event_start => { hires => 1 },
             ],
           );

           ...

           $o->start_date('2/3/2004 8am');
           $dt = $o->start_date(truncate => 'day');

           print $o->end_date(format => '%m/%d/%Y'); # 2005-01-30

           $o->date_created('now');

           $o->other_date('2001-02-20 12:34:56');

           # 02/20/2001 12:34:00
           print $o->other_date(format => '%m/%d/%Y %H:%M:%S');

           print $o->last_modified(format => '%S.%5N'); # 56.12300

           print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003

           $o->event_start('1980-10-11 6:00.123456');

DESCRIPTION

       "Rose::DB::Object::MakeMethods::Date" creates methods that deal with dates, and inherits
       from Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods documentation to learn
       about the interface.  The method types provided by this module are described below.

       All method types defined by this module are designed to work with objects that are
       subclasses of (or otherwise conform to the interface of) Rose::DB::Object.  In particular,
       the object is expected to have a db method that returns a Rose::DB-derived object.  See
       the Rose::DB::Object documentation for more details.

METHODS TYPES

       date
           Create get/set methods for date (year, month, day) attributes.

           Options
               "default"
                   Determines the default value of the attribute.

               "hash_key"
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               "interface"
                   Choose the interface.  The default is "get_set".

               "time_zone"
                   The time zone name, which must be in a format that is understood by
                   DateTime::TimeZone.

           Interfaces
               "get_set"
                   Creates a get/set method for a date (year, month, day) attribute.  When
                   setting the attribute, the value is passed through the parse_date method of
                   the object's db attribute.  If that fails, the value is passed to
                   Rose::DateTime::Util's parse_date() function.  If that fails, a fatal error
                   will occur.

                   The time zone of the DateTime object that results from a successful parse is
                   set to the value of the "time_zone" option, if defined.  Otherwise, it is set
                   to the server_time_zone value of the  object's db attribute using DateTime's
                   set_time_zone method.

                   When saving to the database, the method will pass the attribute value through
                   the format_date method of the object's db attribute before returning it.
                   Otherwise, the value is returned as-is.

                   This method is designed to allow date values to make a round trip from and
                   back into the database without ever being "inflated" into DateTime objects.
                   Any use of the attribute (get or set) outside the context of loading from or
                   saving to the database will cause the value to be "inflated" using the
                   parse_date method of the object's db attribute.  If that fails,
                   Rose::DateTime::Util's parse_date() function is tried.  If that fails, a fatal
                   error will occur.

                   If passed two arguments and the first argument is "format", then the second
                   argument is taken as a format string and passed to Rose::DateTime::Util's
                   format_date function along with the current value of the date attribute.
                   Example:

                       $o->start_date('2004-05-22');
                       print $o->start_date(format => '%A'); # "Saturday"

                   If passed two arguments and the first argument is "truncate", then the second
                   argument is taken as the value of the "to" argument to DateTime's truncate
                   method, which is applied to a clone of the current value of the date
                   attribute, which is then returned.  Example:

                       $o->start_date('2004-05-22');

                       # Equivalent to:
                       # $d = $o->start_date->clone->truncate(to => 'month')
                       $d = $o->start_date(truncate => 'month');

                   If the date attribute is undefined, then undef is returned (i.e., no clone or
                   call to truncate is made).

                   If a valid date keyword is passed as an argument, the value will never be
                   "inflated" but rather passed to the database and returned to other code
                   unmodified.  That means that the "truncate" and "format" calls described above
                   will also return the date keyword unmodified.  See the Rose::DB documentation
                   for more information on date keywords.

               "get"
                   Creates an accessor method for a date (year, month, day) attribute.  This
                   method behaves like the "get_set" method, except that the value cannot be set.

               "set"
                   Creates a mutator method for a date (year, month, day) attribute.  This method
                   behaves like the "get_set" method, except that a fatal error will occur if no
                   arguments are passed.  It also does not support the "truncate" and "format"
                   parameters.

           Example:

               package MyDBObject;

               use base 'Rose::DB::Object';

               use Rose::DB::Object::MakeMethods::Date
               (
                 date =>
                 [
                   'start_date',
                   'end_date' => { default => '2005-01-30' }
                 ],
               );

               ...

               $o->start_date('2/3/2004');
               $dt = $o->start_date(truncate => 'week');

               print $o->end_date(format => '%m/%d/%Y'); # 01/30/2005

       datetime
           Create get/set methods for "datetime" (year, month, day, hour, minute, second)
           attributes.

           Options
               "default"
                   Determines the default value of the attribute.

               "hash_key"
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               "interface"
                   Choose the interface.  The default is "get_set".

               "time_zone"
                   The time zone name, which must be in a format that is understood by
                   DateTime::TimeZone.

               "type"
                   The datetime variant as a string.  Each space in the string is replaced with
                   an underscore "_", then the string is appended to "format_" and "parse_" in
                   order to form the names of the methods called on the object's db attribute to
                   format and parse datetime values.  The default is "datetime", which means that
                   the "format_datetime()" and "parse_datetime()" methods will be used.

                   Any string that results in a set of method names that are supported by the
                   object's db attribute is acceptable.  Check the documentation for the class of
                   the object's db attribute for a list of valid method names.

           Interfaces
               "get_set"
                   Creates a get/set method for a "datetime" attribute.  The exact granularity of
                   the "datetime" value is determined by the value of the "type" option (see
                   above).

                   When setting the attribute, the value is passed through the "parse_TYPE()"
                   method of the object's db attribute, where "TYPE" is the value of the "type"
                   option.  If that fails, the value is passed to Rose::DateTime::Util's
                   parse_date() function.  If that fails, a fatal error will occur.

                   The time zone of the DateTime object that results from a successful parse is
                   set to the value of the "time_zone" option, if defined.  Otherwise, it is set
                   to the server_time_zone value of the  object's db attribute using DateTime's
                   set_time_zone method.

                   When saving to the database, the method will pass the attribute value through
                   the "format_TYPE()" method of the object's db attribute before returning it,
                   where "TYPE" is the value of the "type" option.  Otherwise, the value is
                   returned as-is.

                   This method is designed to allow datetime values to make a round trip from and
                   back into the database without ever being "inflated" into DateTime objects.
                   Any use of the attribute (get or set) outside the context of loading from or
                   saving to the database will cause the value to be "inflated" using the
                   "parse_TYPE()" method of the object's db attribute, where "TYPE" is the value
                   of the "type" option.  If that fails, Rose::DateTime::Util's parse_date()
                   function is tried.  If that fails, a fatal error will occur.

                   If passed two arguments and the first argument is "format", then the second
                   argument is taken as a format string and passed to Rose::DateTime::Util's
                   format_date function along with the current value of the datetime attribute.
                   Example:

                       $o->start_date('2004-05-22 12:34:56');
                       print $o->start_date(format => '%A'); # "Saturday"

                   If passed two arguments and the first argument is "truncate", then the second
                   argument is taken as the value of the "to" argument to DateTime's truncate
                   method, which is applied to a clone of the current value of the datetime
                   attribute, which is then returned.  Example:

                       $o->start_date('2004-05-22 04:32:01');

                       # Equivalent to:
                       # $d = $o->start_date->clone->truncate(to => 'month')
                       $d = $o->start_date(truncate => 'month');

                   If the datetime attribute is undefined, then undef is returned (i.e., no clone
                   or call to truncate is made).

                   If a valid datetime keyword is passed as an argument, the value will never be
                   "inflated" but rather passed to the database and returned to other code
                   unmodified.  That means that the "truncate" and "format" calls described above
                   will also return the datetime keyword unmodified.  See the Rose::DB
                   documentation for more information on datetime keywords.

               "get"
                   Creates an accessor method for a "datetime" attribute.  This method behaves
                   like the "get_set" method, except that the value cannot be set.

               "set"
                   Creates a mutator method for a "datetime" attribute.  This method behaves like
                   the "get_set" method, except that a fatal error will occur if no arguments are
                   passed.  It also does not support the "truncate" and "format" parameters.

           Example:

               package MyDBObject;

               use base 'Rose::DB::Object';

               use Rose::DB::Object::MakeMethods::Date
               (
                 datetime =>
                 [
                   'start_date',
                   'end_date'   => { default => '2005-01-30 12:34:56' }
                   'other_date' => { type => 'datetime year to minute' },
                 ],
               );

               ...

               $o->start_date('2/3/2004 8am');
               $dt = $o->start_date(truncate => 'day');

               # 01/30/2005 12:34:56
               print $o->end_date(format => '%m/%d/%Y %H:%M:%S');

               $o->other_date('2001-02-20 12:34:56');

               # 02/20/2001 12:34:00
               print $o->other_date(format => '%m/%d/%Y %H:%M:%S');

       epoch
           Create get/set methods for an attribute that stores seconds since the Unix epoch.

           Options
               "default"
                   Determines the default value of the attribute.

               "hash_key"
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               "hires"
                   A boolean flag that indicates whether or not epoch values should be stored
                   with fractional seconds.  If true, then up to six (6) digits past the decimal
                   point are preserved.  The default is false.

               "interface"
                   Choose the interface.  The default is "get_set".

               "time_zone"
                   The time zone name, which must be in a format that is understood by
                   DateTime::TimeZone.

           Interfaces
               "get_set"
                   Creates a get/set method for an attribute that stores seconds since the Unix
                   epoch.  When setting the attribute, the value is passed through
                   Rose::DateTime::Util's parse_date() function.  If that fails, a fatal error
                   will occur.

                   The time zone of the DateTime object that results from a successful parse is
                   set to the value of the "time_zone" option, if defined.  Otherwise, it is set
                   to the server_time_zone value of the  object's db attribute using DateTime's
                   set_time_zone method.

                   When saving to the database, the epoch or hires_epoch method will be called on
                   the DateTime object, depending on the value of the "hires" option.  (See
                   above.)

                   This method is designed to allow values to make a round trip from and back
                   into the database without ever being "inflated" into DateTime objects.  Any
                   use of the attribute (get or set) outside the context of loading from or
                   saving to the database will cause the value to be "inflated" using
                   Rose::DateTime::Util's parse_date() function.  If that fails, a fatal error
                   will occur.

                   If passed two arguments and the first argument is "format", then the second
                   argument is taken as a format string and passed to Rose::DateTime::Util's
                   format_date function along with the current value of the attribute.  Example:

                       $o->due_date('2004-05-22');
                       print $o->due_date(format => '%A'); # "Saturday"

                   If passed two arguments and the first argument is "truncate", then the second
                   argument is taken as the value of the "to" argument to DateTime's truncate
                   method, which is applied to a clone of the current value of the attribute,
                   which is then returned.  Example:

                       $o->due_date('2004-05-22');

                       # Equivalent to:
                       # $d = $o->due_date->clone->truncate(to => 'month')
                       $d = $o->due_date(truncate => 'month');

                   If the attribute is undefined, then undef is returned (i.e., no clone or call
                   to truncate is made).

               "get"
                   Creates an accessor method an attribute that stores seconds since the Unix
                   epoch.  This method behaves like the "get_set" method, except that the value
                   cannot be set.

               "set"
                   Creates a mutator method for an attribute that stores seconds since the Unix
                   epoch.  This method behaves like the "get_set" method, except that a fatal
                   error will occur if no arguments are passed.  It also does not support the
                   "truncate" and "format" parameters.

           Example:

               package MyDBObject;

               use base 'Rose::DB::Object';

               use Rose::DB::Object::MakeMethods::Date
               (
                 epoch =>
                 [
                   due_date    => { default => '2003-01-02 12:34:56' },
                   event_start => { hires => 1 },
                 ],
               );

               ...

               print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003
               $dt = $o->due_date(truncate => 'week');

               $o->event_start('1980-10-11 6:00.123456');
               print $o->event_start(format => '%6N'); # 123456

       timestamp
           Create get/set methods for "timestamp" (year, month, day, hour, minute, second,
           fractional seconds) attributes.

           Options
               "default"
                   Determines the default value of the attribute.

               "hash_key"
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               "interface"
                   Choose the interface.  The default interface is "get_set".

               "time_zone"
                   A time zone name, which must be in a format that is understood by
                   DateTime::TimeZone.

           Interfaces
               "get_set"
                   Creates a get/set method for a "timestamp" (year, month, day, hour, minute,
                   second, fractional seconds) attribute.  When setting the attribute, the value
                   is passed through the "parse_timestamp()" method of the object's db attribute.
                   If that fails, the value is passed to Rose::DateTime::Util's parse_date()
                   function.  If that fails, a fatal error will occur.

                   The time zone of the DateTime object that results from a successful parse is
                   set to the value of the "time_zone" option, if defined.  Otherwise, it is set
                   to the server_time_zone value of the  object's db attribute using DateTime's
                   set_time_zone method.

                   When saving to the database, the method will pass the attribute value through
                   the format_timestamp method of the object's db attribute before returning it.
                   Otherwise, the value is returned as-is.

                   This method is designed to allow timestamp values to make a round trip from
                   and back into the database without ever being "inflated" into DateTime
                   objects.  Any use of the attribute (get or set) outside the context of loading
                   from or saving to the database will cause the value to be "inflated" using the
                   "parse_timestamp()" method of the object's db attribute.  If that fails,
                   Rose::DateTime::Util's parse_date() function is tried.  If that fails, a fatal
                   error will occur.

                   If passed two arguments and the first argument is "format", then the second
                   argument is taken as a format string and passed to Rose::DateTime::Util's
                   format_date function along with the current value of the timestamp attribute.
                   Example:

                       $o->start_date('2004-05-22 12:34:56.123');
                       print $o->start_date(format => '%A'); # "Saturday"

                   If passed two arguments and the first argument is "truncate", then the second
                   argument is taken as the value of the "to" argument to DateTime's truncate
                   method, which is applied to a clone of the current value of the timestamp
                   attribute, which is then returned.  Example:

                       $o->start_date('2004-05-22 04:32:01.456');

                       # Equivalent to:
                       # $d = $o->start_date->clone->truncate(to => 'month')
                       $d = $o->start_date(truncate => 'month');

                   If the timestamp attribute is undefined, then undef is returned (i.e., no
                   clone or call to truncate is made).

                   If a valid timestamp keyword is passed as an argument, the value will never be
                   "inflated" but rather passed to the database and returned to other code
                   unmodified.  That means that the "truncate" and "format" calls described above
                   will also return the timestamp keyword unmodified.  See the Rose::DB
                   documentation for more information on timestamp keywords.

               "get"
                   Creates an accessor method for a "timestamp" (year, month, day, hour, minute,
                   second, fractional seconds) attribute.  This method behaves like the "get_set"
                   method, except that the value cannot be set.

               "set"
                   Creates a mutator method for a "timestamp" (year, month, day, hour, minute,
                   second, fractional seconds) attribute.  This method behaves like the "get_set"
                   method, except that a fatal error will occur if no arguments are passed.  It
                   also does not support the "truncate" and "format" parameters.

           Example:

               package MyDBObject;

               use base 'Rose::DB::Object';

               use Rose::DB::Object::MakeMethods::Date
               (
                 timestamp =>
                 [
                   'start_date',
                   'end_date' => { default => '2005-01-30 12:34:56.123' }
                 ],
               );

               ...

               $o->start_date('2/3/2004 8am');
               $dt = $o->start_date(truncate => 'day');

               # 01/30/2005 12:34:56.12300
               print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');

       timestamp_without_time_zone
           This is identical to the timestamp method described above, but with the "time_zone"
           parameter always set to the value "floating".  Any attempt to set the "time_zone"
           parameter explicitly will cause a fatal error.

       timestamp_with_time_zone
           Create get/set methods for "timestamp with time zone" (year, month, day, hour, minute,
           second, fractional seconds, time zone) attributes.

           Options
               "default"
                   Determines the default value of the attribute.

               "hash_key"
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               "interface"
                   Choose the interface.  The default interface is "get_set".

               "time_zone"
                   A time zone name, which must be in a format that is understood by
                   DateTime::TimeZone.

           Interfaces
               "get_set"
                   Creates a get/set method for a "timestamp with time zone" (year, month, day,
                   hour, minute, second, fractional seconds, time zone) attribute.  When setting
                   the attribute, the value is passed through the
                   "parse_timestamp_with_timezone()" method of the object's db attribute.  If
                   that fails, the value is passed to Rose::DateTime::Util's parse_date()
                   function.  If that fails, a fatal error will occur.

                   The time zone of the DateTime object will be set according to the successful
                   parse of the "timestamp with time zone" value.  If the "time_zone" option is
                   set, then the time zone of the DateTime object is set to this value.  Note
                   that this happens after the successful parse, which means that this operation
                   may change the time and/or date according to the difference between the time
                   zone of the value as originally parsed and the new time zone set according to
                   the "time_zone" option.

                   When saving to the database, the method will pass the attribute value through
                   the format_timestamp_with_timezone method of the object's db attribute before
                   returning it.  Otherwise, the value is returned as-is.

                   This method is designed to allow timestamp values to make a round trip from
                   and back into the database without ever being "inflated" into DateTime
                   objects.  Any use of the attribute (get or set) outside the context of loading
                   from or saving to the database will cause the value to be "inflated" using the
                   "parse_timestamp_with_time_zone()" method of the object's db attribute.  If
                   that fails, Rose::DateTime::Util's parse_date() function is tried.  If that
                   fails, a fatal error will occur.

                   If passed two arguments and the first argument is "format", then the second
                   argument is taken as a format string and passed to Rose::DateTime::Util's
                   format_date function along with the current value of the timestamp attribute.
                   Example:

                       $o->start_date('2004-05-22 12:34:56.123');
                       print $o->start_date(format => '%A'); # "Saturday"

                   If passed two arguments and the first argument is "truncate", then the second
                   argument is taken as the value of the "to" argument to DateTime's truncate
                   method, which is applied to a clone of the current value of the timestamp
                   attribute, which is then returned.  Example:

                       $o->start_date('2004-05-22 04:32:01.456');

                       # Equivalent to:
                       # $d = $o->start_date->clone->truncate(to => 'month')
                       $d = $o->start_date(truncate => 'month');

                   If the timestamp attribute is undefined, then undef is returned (i.e., no
                   clone or call to truncate is made).

                   If a valid timestamp keyword is passed as an argument, the value will never be
                   "inflated" but rather passed to the database and returned to other code
                   unmodified.  That means that the "truncate" and "format" calls described above
                   will also return the timestamp keyword unmodified.  See the Rose::DB
                   documentation for more information on timestamp keywords.

               "get"
                   Creates an accessor method for a "timestamp with time zone" (year, month, day,
                   hour, minute, second, fractional seconds, time zone) attribute.  This method
                   behaves like the "get_set" method, except that the value cannot be set.

               "set"
                   Creates a mutator method for a "timestamp with time zone" (year, month, day,
                   hour, minute, second, fractional seconds, time zone) attribute.  This method
                   behaves like the "get_set" method, except that a fatal error will occur if no
                   arguments are passed.  It also does not support the "truncate" and "format"
                   parameters.

           Example:

               package MyDBObject;

               use base 'Rose::DB::Object';

               use Rose::DB::Object::MakeMethods::Date
               (
                 timestamp_with_timezone =>
                 [
                   'start_date',
                   'end_date' => { default => '2005-01-30 12:34:56.123' }
                 ],
               );

               ...

               $o->start_date('2/3/2004 8am');
               $dt = $o->start_date(truncate => 'day');

               # 01/30/2005 12:34:56.12300
               print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');

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.