Provided by: librose-object-perl_0.860-2_all bug

NAME

       Rose::Object::MakeMethods::DateTime - Create methods that store DateTime objects.

SYNOPSIS

         package MyObject;

         use Rose::Object::MakeMethods::DateTime
         (
           datetime =>
           [
             'birthday',
             'arrival' => { tz => 'UTC' }
           ],
         );

         ...

         $obj = MyObject->new(birthday => '1/24/1984 1am');

         $dt = $obj->birthday; # DateTime object

         $bday = $obj->birthday(format => '%B %E'); # 'January 24th'

         # Shortcut for $obj->birthday->clone->truncate(to => 'month');
         $month = $obj->birthday(truncate => 'month');

         $obj->birthday('blah');       # croaks - invalid date!
         $obj->birthday('1999-04-31'); # croaks - invalid date!

DESCRIPTION

       Rose::Object::MakeMethods::DateTime is a method maker that 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 methods
       work only with hash-based objects.

METHODS TYPES

       datetime
           Create get/set methods for scalar attributes that store DateTime objects.

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

               "init_method"
                   The name of the method to call when initializing the value of an undefined
                   attribute.  This option is only applicable when using the "get_set_init"
                   interface. Defaults to the method name with the prefix "init_" added.

                   This method should return a value that can be parsed by Rose::DateTime::Util's
                   the parse_date() function. If the return value is a DateTime object, it will
                   have its time zone set (see the "tz" option below) using DateTime's
                   set_time_zone() method.

               "interface"
                   Chooses one of the two possible interfaces.  Defaults to "get_set".

               "tz"
                   The time zone of the DateTime object to be stored.  If present, this value
                   will be passed as the second argument to Rose::DateTime::Util's the
                   parse_date() function when creating DateTime objects for storage. If absent,
                   DateTime objects will use the default time zone of the Rose::DateTime::Util
                   class, which is set by Rose::DateTime::Util's time_zone() class method.  See
                   the Rose::DateTime::Util documentation for more information.

           Interfaces
               "get_set"
                   Creates a get/set accessor method for an object attribute that stores a
                   DateTime object.

                   When called with a single argument, the argument is passed through
                   Rose::DateTime::Util's parse_date() function in order to create the DateTime
                   object that is stored.  The current value of the attribute is returned.
                   Passing a value that is not understood by Rose::DateTime::Util's parse_date()
                   function causes a fatal error.

                   When called with two arguments and the first argument is the string 'format',
                   then the second argument is taken as a format specifier which is passed to
                   Rose::DateTime::Util's format_date() function.  The formatted string is
                   returned.  In other words, this:

                       $obj->birthday(format => '%m/%d/%Y');

                   Is just a shortcut for this:

                       Rose::DateTime::Util::format_date($obj->birthday,
                                                         '%m/%d/%Y');

                   When called with two arguments and the first argument is the string
                   'truncate', then the second argument is taken as a truncation specifier which
                   is passed to DateTime's truncate() method called on a clone of the existing
                   DateTime object.  The cloned, truncated DateTime object is returned.  In other
                   words, this:

                       $obj->birthday(truncate => 'month');

                   Is just a shortcut for this:

                       $obj->birthday->clone->truncate(to => 'month');

                   Passing more than two arguments or passing two arguments where the first
                   argument is not 'format' or 'truncate' will cause a fatal error.

               "get_set_init"
                   Behaves like the "get_set" interface unless the value of the attribute is
                   undefined.  In that case, the method specified by the "init_method" option is
                   called, the return value is passed through Rose::DateTime::Util's parse_date()
                   function, and the attribute is set to the return value.  An init method that
                   returns a value that is not understood by Rose::DateTime::Util's parse_date()
                   function will cause a fatal error.

           Example:

               package MyObject;

               use Rose::Object::MakeMethods::DateTime
               (
                 datetime =>
                 [
                   'birthday',
                   'arrival' => { tz => 'UTC' }
                 ],

                 'datetime --get_set_init' =>
                 [
                   'departure' => { tz => 'UTC' }
                 ],
               );

               sub init_departure
               {
                 DateTime->new(month => 1,
                               day   => 10,
                               year  => 2000,
                               time_zone => 'America/Chicago');
               }

               ...

               $obj = MyObject->new(birthday => '1/24/1984 1am');

               $dt = $obj->birthday; # DateTime object

               $bday = $obj->birthday(format => '%B %E'); # 'January 24th'

               # Shortcut for $obj->birthday->clone->truncate(to => 'month');
               $month = $obj->birthday(truncate => 'month');

               $obj->birthday('blah');       # croaks - invalid date!
               $obj->birthday('1999-04-31'); # croaks - invalid date!

               # DateTime object with time zone set to UTC
               $dt = $obj->arrival('2005-21-01 4pm');

               # DateTime object with time zone set to UTC, not America/Chicago!
               #   Start with 2000-01-10T00:00:00 America/Chicago,
               #   then set_time_zone('UTC'),
               #   which results in: 2000-01-10T06:00:00 UTC
               $dt = $obj->departure;

               print $dt; # "2000-01-10T06:00:00"

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.