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.

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.

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

$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.

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.

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

$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.

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.

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

$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.

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

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

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

To install Rose::DB::Object, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Rose::DB::Object

CPAN shell

perl -MCPAN -e shell
install Rose::DB::Object

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS TYPES

AUTHOR

LICENSE

Module Install Instructions