1Rose::Object::MakeMethoUdsse:r:DCaotnetTriimbeu(t3e)d PeRrolseD:o:cOubmjeenctta:t:iMoankeMethods::DateTime(3)
2
3
4

NAME

6       Rose::Object::MakeMethods::DateTime - Create methods that store
7       DateTime objects.
8

SYNOPSIS

10         package MyObject;
11
12         use Rose::Object::MakeMethods::DateTime
13         (
14           datetime =>
15           [
16             'birthday',
17             'arrival' => { tz => 'UTC' }
18           ],
19         );
20
21         ...
22
23         $obj = MyObject->new(birthday => '1/24/1984 1am');
24
25         $dt = $obj->birthday; # DateTime object
26
27         $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
28
29         # Shortcut for $obj->birthday->clone->truncate(to => 'month');
30         $month = $obj->birthday(truncate => 'month');
31
32         $obj->birthday('blah');       # croaks - invalid date!
33         $obj->birthday('1999-04-31'); # croaks - invalid date!
34

DESCRIPTION

36       Rose::Object::MakeMethods::DateTime is a method maker that inherits
37       from Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods
38       documentation to learn about the interface.  The method types provided
39       by this module are described below.  All methods work only with hash-
40       based objects.
41

METHODS TYPES

43       datetime
44           Create get/set methods for scalar attributes that store DateTime
45           objects.
46
47           Options
48               "hash_key"
49                   The key inside the hash-based object to use for the storage
50                   of this attribute. Defaults to the name of the method.
51
52               "init_method"
53                   The name of the method to call when initializing the value
54                   of an undefined attribute.  This option is only applicable
55                   when using the "get_set_init" interface. Defaults to the
56                   method name with the prefix "init_" added.
57
58                   This method should return a value that can be parsed by
59                   Rose::DateTime::Util's the parse_date() function. If the
60                   return value is a DateTime object, it will have its time
61                   zone set (see the "tz" option below) using DateTime's
62                   set_time_zone() method.
63
64               "interface"
65                   Chooses one of the two possible interfaces.  Defaults to
66                   "get_set".
67
68               "tz"
69                   The time zone of the DateTime object to be stored.  If
70                   present, this value will be passed as the second argument
71                   to Rose::DateTime::Util's the parse_date() function when
72                   creating DateTime objects for storage. If absent, DateTime
73                   objects will use the default time zone of the
74                   Rose::DateTime::Util class, which is set by
75                   Rose::DateTime::Util's time_zone() class method.  See the
76                   Rose::DateTime::Util documentation for more information.
77
78           Interfaces
79               "get_set"
80                   Creates a get/set accessor method for an object attribute
81                   that stores a DateTime object.
82
83                   When called with a single argument, the argument is passed
84                   through Rose::DateTime::Util's parse_date() function in
85                   order to create the DateTime object that is stored.  The
86                   current value of the attribute is returned.  Passing a
87                   value that is not understood by Rose::DateTime::Util's
88                   parse_date() function causes a fatal error.
89
90                   When called with two arguments and the first argument is
91                   the string 'format', then the second argument is taken as a
92                   format specifier which is passed to Rose::DateTime::Util's
93                   format_date() function.  The formatted string is returned.
94                   In other words, this:
95
96                       $obj->birthday(format => '%m/%d/%Y');
97
98                   Is just a shortcut for this:
99
100                       Rose::DateTime::Util::format_date($obj->birthday,
101                                                         '%m/%d/%Y');
102
103                   When called with two arguments and the first argument is
104                   the string 'truncate', then the second argument is taken as
105                   a truncation specifier which is passed to DateTime's
106                   truncate() method called on a clone of the existing
107                   DateTime object.  The cloned, truncated DateTime object is
108                   returned.  In other words, this:
109
110                       $obj->birthday(truncate => 'month');
111
112                   Is just a shortcut for this:
113
114                       $obj->birthday->clone->truncate(to => 'month');
115
116                   Passing more than two arguments or passing two arguments
117                   where the first argument is not 'format' or 'truncate' will
118                   cause a fatal error.
119
120               "get_set_init"
121                   Behaves like the "get_set" interface unless the value of
122                   the attribute is undefined.  In that case, the method
123                   specified by the "init_method" option is called, the return
124                   value is passed through Rose::DateTime::Util's parse_date()
125                   function, and the attribute is set to the return value.  An
126                   init method that returns a value that is not understood by
127                   Rose::DateTime::Util's parse_date() function will cause a
128                   fatal error.
129
130           Example:
131
132               package MyObject;
133
134               use Rose::Object::MakeMethods::DateTime
135               (
136                 datetime =>
137                 [
138                   'birthday',
139                   'arrival' => { tz => 'UTC' }
140                 ],
141
142                 'datetime --get_set_init' =>
143                 [
144                   'departure' => { tz => 'UTC' }
145                 ],
146               );
147
148               sub init_departure
149               {
150                 DateTime->new(month => 1,
151                               day   => 10,
152                               year  => 2000,
153                               time_zone => 'America/Chicago');
154               }
155
156               ...
157
158               $obj = MyObject->new(birthday => '1/24/1984 1am');
159
160               $dt = $obj->birthday; # DateTime object
161
162               $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
163
164               # Shortcut for $obj->birthday->clone->truncate(to => 'month');
165               $month = $obj->birthday(truncate => 'month');
166
167               $obj->birthday('blah');       # croaks - invalid date!
168               $obj->birthday('1999-04-31'); # croaks - invalid date!
169
170               # DateTime object with time zone set to UTC
171               $dt = $obj->arrival('2005-21-01 4pm');
172
173               # DateTime object with time zone set to UTC, not America/Chicago!
174               #   Start with 2000-01-10T00:00:00 America/Chicago,
175               #   then set_time_zone('UTC'),
176               #   which results in: 2000-01-10T06:00:00 UTC
177               $dt = $obj->departure;
178
179               print $dt; # "2000-01-10T06:00:00"
180

AUTHOR

182       John C. Siracusa (siracusa@gmail.com)
183

LICENSE

185       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
186       program is free software; you can redistribute it and/or modify it
187       under the same terms as Perl itself.
188
189
190
191perl v5.38.0                      2023-07R-o2s1e::Object::MakeMethods::DateTime(3)
Impressum