1Rose::Object::MakeMethoUdsse:r:DCaotnetTriimbeu(t3e)d PeRrolseD:o:cOubmjeenctta:t:iMoankeMethods::DateTime(3)
2
6 Rose::Object::MakeMethods::DateTime - Create methods that store
7 DateTime objects.
8
10 package MyObject;
11 use Rose::Object::MakeMethods::DateTime
13 (
14 datetime =>
15 [
16 'birthday',
17 'arrival' => { tz => 'UTC' }
18 ],
19 );
20 ...
22 $obj = MyObject->new(birthday => '1/24/1984 1am');
24 $dt = $obj->birthday; # DateTime object
26 $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
28 # Shortcut for $obj->birthday->clone->truncate(to => 'month');
30 $month = $obj->birthday(truncate => 'month');
31 $obj->birthday('blah'); # croaks - invalid date!
33 $obj->birthday('1999-04-31'); # croaks - invalid date!
34
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
43 datetime
44 Create get/set methods for scalar attributes that store DateTime
45 objects.
46 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 "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 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 "interface"
65 Chooses one of the two possible interfaces. Defaults to
66 "get_set".
67 "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 Interfaces
79 "get_set"
80 Creates a get/set accessor method for an object attribute
81 that stores a DateTime object.
82 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 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 $obj->birthday(format => '%m/%d/%Y');
97 Is just a shortcut for this:
99 Rose::DateTime::Util::format_date($obj->birthday,
101 '%m/%d/%Y');
102 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 $obj->birthday(truncate => 'month');
111 Is just a shortcut for this:
113 $obj->birthday->clone->truncate(to => 'month');
115 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 "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 Example:
131 package MyObject;
133 use Rose::Object::MakeMethods::DateTime
135 (
136 datetime =>
137 [
138 'birthday',
139 'arrival' => { tz => 'UTC' }
140 ],
141 'datetime --get_set_init' =>
143 [
144 'departure' => { tz => 'UTC' }
145 ],
146 );
147 sub init_departure
149 {
150 DateTime->new(month => 1,
151 day => 10,
152 year => 2000,
153 time_zone => 'America/Chicago');
154 }
155 ...
157 $obj = MyObject->new(birthday => '1/24/1984 1am');
159 $dt = $obj->birthday; # DateTime object
161 $bday = $obj->birthday(format => '%B %E'); # 'January 24th'
163 # Shortcut for $obj->birthday->clone->truncate(to => 'month');
165 $month = $obj->birthday(truncate => 'month');
166 $obj->birthday('blah'); # croaks - invalid date!
168 $obj->birthday('1999-04-31'); # croaks - invalid date!
169 # DateTime object with time zone set to UTC
171 $dt = $obj->arrival('2005-21-01 4pm');
172 # 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 print $dt; # "2000-01-10T06:00:00"
180
182 John C. Siracusa (siracusa@gmail.com)
183
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.
188perl v5.38.0 2023-07R-o2s1e::Object::MakeMethods::DateTime(3)