Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::DB::Object::MakeUseroContributed PRose::DB::Object::MakeMethods::Date(3)

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.

perl v5.24.1			  2015-0Rose::DB::Object::MakeMethods::Date(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS TYPES | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::DB::Object::MakeMethods::Date&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help