Rose::Object::MakeMethods::DateTime(3pm)		User Contributed Perl Documentation		  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) 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.

perl v5.10.1							    2010-10-17				  Rose::Object::MakeMethods::DateTime(3pm)