Linux Certif

Toute la documentation sur la certification Linux LPI

Rose::Object::MakeMethods::DateTime.3pm

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) 2006 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.