Rose::...ateTime(3pm)

💖 Rose::Object::MakeMethods::DateTime — the whole vibe 💖

okay bestie, gather round, because this is the Rose::Object::MakeMethods::DateTime page from the User Contributed Perl Documentation, and it's genuinely iconic. it's a method maker that spins up methods which store DateTime objects for you. no cap. 🕰️✨

---

✨ NAME ✨

Rose::Object::MakeMethods::DateTime — create methods that store DateTime objects. that's it. that's the whole job. and it slays at it. 💅

---

🌸 SYNOPSIS 🌸

here's the lil taste test, verbatim, don't touch a character:

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!

see how $obj->birthday just hands you a whole DateTime object like it's nothing? main character energy fr fr. 🎀

---

🦋 DESCRIPTION 🦋

so Rose::Object::MakeMethods::DateTime is a method maker that inherits from Rose::Object::MakeMethods. if you wanna learn about the interface itself, go read the Rose::Object::MakeMethods documentation — that's where the whole system lives. this page is just here to describe the method types this module provides. 💖

⚠️ and this part matters: all methods work only with hash-based objects. hash-based or it's not happening. 💀

---

👑 METHODS TYPES 👑

🌟 datetime

creates get/set methods for scalar attributes that store DateTime objects. so cute, so useful.

🍓 Options

• hash_key — the key inside the hash-based object where this attribute actually gets stored. defaults to the name of the method. (so if your method is birthday, the key is birthday unless you say otherwise.)
• init_method — the name of the method to call when initializing the value of an undefined attribute. heads up: 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. and 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 — picks one of the two possible interfaces. defaults to get_set. choose your fighter. 🥊
• tz — the time zone of the DateTime object to be stored. if it's present, this value gets passed as the second argument to Rose::DateTime::Util's the parse_date() function when creating DateTime objects for storage. if it's 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 info. 🌍

💜 Interfaces

get_set

creates a get/set accessor method for an object attribute that stores a DateTime object. the classic. the blueprint. 🫶

when called with a single argument, that argument gets 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 Rose::DateTime::Util's parse_date() function doesn't understand causes a fatal error. so don't do that. 😭

when called with two arguments and the first argument is the string 'format', then the second argument is taken as a format specifier, which gets 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 gets 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. periodt.

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 gets called, the return value gets 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 Rose::DateTime::Util's parse_date() function doesn't understand will cause a fatal error. no notes. 💅

🌈 Example:

okay here's the full flex, copy it exactly:

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"

the way that departure starts as 2000-01-10T00:00:00 in America/Chicago and then gets set_time_zone('UTC')'d into 2000-01-10T06:00:00 UTC... that's the plot twist, bestie. 🧚✨

---

🎀 AUTHOR 🎀

John C. Siracusa (siracusa@gmail.com) — the icon who built this. 👑

---

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

---

and that's the whole page, babe. 🫶

this was Rose::...ateTime(3pm) from perl v5.34.0, dated 2022-05-28 — shoutout to the version and the date, they're doing great. now go make some DateTime objects, you absolute legend. slay 💅✨🌈