1Rose::DB::Object::MakeMUestehrodCso:n:tDraitbeu(t3e)d PeRrolseD:o:cDuBm:e:nOtbajteicotn::MakeMethods::Date(3)
2
3
4

NAME

6       Rose::DB::Object::MakeMethods::Date - Create date-related methods for
7       Rose::DB::Object-derived objects.
8

SYNOPSIS

10           package MyDBObject;
11
12           use base 'Rose::DB::Object';
13
14           use Rose::DB::Object::MakeMethods::Date
15           (
16             date =>
17             [
18               'start_date',
19               'end_date' => { default => '2005-01-30' }
20             ],
21
22             datetime =>
23             [
24               'date_created',
25               'other_date' => { type => 'datetime year to minute' },
26             ],
27
28             timestamp =>
29             [
30               'last_modified' => { default => '2005-01-30 12:34:56.123' }
31             ],
32
33             epoch =>
34             [
35               due_date    => { default => '2003-01-02 12:34:56' },
36               event_start => { hires => 1 },
37             ],
38           );
39
40           ...
41
42           $o->start_date('2/3/2004 8am');
43           $dt = $o->start_date(truncate => 'day');
44
45           print $o->end_date(format => '%m/%d/%Y'); # 2005-01-30
46
47           $o->date_created('now');
48
49           $o->other_date('2001-02-20 12:34:56');
50
51           # 02/20/2001 12:34:00
52           print $o->other_date(format => '%m/%d/%Y %H:%M:%S');
53
54           print $o->last_modified(format => '%S.%5N'); # 56.12300
55
56           print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003
57
58           $o->event_start('1980-10-11 6:00.123456');
59

DESCRIPTION

61       "Rose::DB::Object::MakeMethods::Date" creates methods that deal with
62       dates, and inherits from Rose::Object::MakeMethods.  See the
63       Rose::Object::MakeMethods documentation to learn about the interface.
64       The method types provided by this module are described below.
65
66       All method types defined by this module are designed to work with
67       objects that are subclasses of (or otherwise conform to the interface
68       of) Rose::DB::Object.  In particular, the object is expected to have a
69       db method that returns a Rose::DB-derived object.  See the
70       Rose::DB::Object documentation for more details.
71

METHODS TYPES

73       date
74           Create get/set methods for date (year, month, day) attributes.
75
76           Options
77               "default"
78                   Determines the default value of the attribute.
79
80               "hash_key"
81                   The key inside the hash-based object to use for the storage
82                   of this attribute.  Defaults to the name of the method.
83
84               "interface"
85                   Choose the interface.  The default is "get_set".
86
87               "time_zone"
88                   The time zone name, which must be in a format that is
89                   understood by DateTime::TimeZone.
90
91           Interfaces
92               "get_set"
93                   Creates a get/set method for a date (year, month, day)
94                   attribute.  When setting the attribute, the value is passed
95                   through the parse_date method of the object's db attribute.
96                   If that fails, the value is passed to
97                   Rose::DateTime::Util's parse_date() function.  If that
98                   fails, a fatal error will occur.
99
100                   The time zone of the DateTime object that results from a
101                   successful parse is set to the value of the "time_zone"
102                   option, if defined.  Otherwise, it is set to the
103                   server_time_zone value of the  object's db attribute using
104                   DateTime's set_time_zone method.
105
106                   When saving to the database, the method will pass the
107                   attribute value through the format_date method of the
108                   object's db attribute before returning it.  Otherwise, the
109                   value is returned as-is.
110
111                   This method is designed to allow date values to make a
112                   round trip from and back into the database without ever
113                   being "inflated" into DateTime objects.  Any use of the
114                   attribute (get or set) outside the context of loading from
115                   or saving to the database will cause the value to be
116                   "inflated" using the  parse_date method of the object's db
117                   attribute.  If that fails, Rose::DateTime::Util's
118                   parse_date() function is tried.  If that fails, a fatal
119                   error will occur.
120
121                   If passed two arguments and the first argument is "format",
122                   then the second argument is taken as a format string and
123                   passed to Rose::DateTime::Util's format_date function along
124                   with the current value of the date attribute.  Example:
125
126                       $o->start_date('2004-05-22');
127                       print $o->start_date(format => '%A'); # "Saturday"
128
129                   If passed two arguments and the first argument is
130                   "truncate", then the second argument is taken as the value
131                   of the "to" argument to DateTime's truncate method, which
132                   is applied to a clone of the current value of the date
133                   attribute, which is then returned.  Example:
134
135                       $o->start_date('2004-05-22');
136
137                       # Equivalent to:
138                       # $d = $o->start_date->clone->truncate(to => 'month')
139                       $d = $o->start_date(truncate => 'month');
140
141                   If the date attribute is undefined, then undef is returned
142                   (i.e., no clone or call to truncate is made).
143
144                   If a valid date keyword is passed as an argument, the value
145                   will never be "inflated" but rather passed to the database
146                   and returned to other code unmodified.  That means that the
147                   "truncate" and "format" calls described above will also
148                   return the date keyword unmodified.  See the Rose::DB
149                   documentation for more information on date keywords.
150
151               "get"
152                   Creates an accessor method for a date (year, month, day)
153                   attribute.  This method behaves like the "get_set" method,
154                   except that the value cannot be set.
155
156               "set"
157                   Creates a mutator method for a date (year, month, day)
158                   attribute.  This method behaves like the "get_set" method,
159                   except that a fatal error will occur if no arguments are
160                   passed.  It also does not support the "truncate" and
161                   "format" parameters.
162
163           Example:
164
165               package MyDBObject;
166
167               use base 'Rose::DB::Object';
168
169               use Rose::DB::Object::MakeMethods::Date
170               (
171                 date =>
172                 [
173                   'start_date',
174                   'end_date' => { default => '2005-01-30' }
175                 ],
176               );
177
178               ...
179
180               $o->start_date('2/3/2004');
181               $dt = $o->start_date(truncate => 'week');
182
183               print $o->end_date(format => '%m/%d/%Y'); # 01/30/2005
184
185       datetime
186           Create get/set methods for "datetime" (year, month, day, hour,
187           minute, second) attributes.
188
189           Options
190               "default"
191                   Determines the default value of the attribute.
192
193               "hash_key"
194                   The key inside the hash-based object to use for the storage
195                   of this attribute.  Defaults to the name of the method.
196
197               "interface"
198                   Choose the interface.  The default is "get_set".
199
200               "time_zone"
201                   The time zone name, which must be in a format that is
202                   understood by DateTime::TimeZone.
203
204               "type"
205                   The datetime variant as a string.  Each space in the string
206                   is replaced with an underscore "_", then the string is
207                   appended to "format_" and "parse_" in order to form the
208                   names of the methods called on the object's db attribute to
209                   format and parse datetime values.  The default is
210                   "datetime", which means that the "format_datetime()" and
211                   "parse_datetime()" methods will be used.
212
213                   Any string that results in a set of method names that are
214                   supported by the object's db attribute is acceptable.
215                   Check the documentation for the class of the object's db
216                   attribute for a list of valid method names.
217
218           Interfaces
219               "get_set"
220                   Creates a get/set method for a "datetime" attribute.  The
221                   exact granularity of the "datetime" value is determined by
222                   the value of the "type" option (see above).
223
224                   When setting the attribute, the value is passed through the
225                   "parse_TYPE()" method of the object's db attribute, where
226                   "TYPE" is the value of the "type" option.  If that fails,
227                   the value is passed to Rose::DateTime::Util's parse_date()
228                   function.  If that fails, a fatal error will occur.
229
230                   The time zone of the DateTime object that results from a
231                   successful parse is set to the value of the "time_zone"
232                   option, if defined.  Otherwise, it is set to the
233                   server_time_zone value of the  object's db attribute using
234                   DateTime's set_time_zone method.
235
236                   When saving to the database, the method will pass the
237                   attribute value through the "format_TYPE()" method of the
238                   object's db attribute before returning it, where "TYPE" is
239                   the value of the "type" option.  Otherwise, the value is
240                   returned as-is.
241
242                   This method is designed to allow datetime values to make a
243                   round trip from and back into the database without ever
244                   being "inflated" into DateTime objects.  Any use of the
245                   attribute (get or set) outside the context of loading from
246                   or saving to the database will cause the value to be
247                   "inflated" using the  "parse_TYPE()" method of the object's
248                   db attribute, where "TYPE" is the value of the "type"
249                   option.  If that fails, Rose::DateTime::Util's parse_date()
250                   function is tried.  If that fails, a fatal error will
251                   occur.
252
253                   If passed two arguments and the first argument is "format",
254                   then the second argument is taken as a format string and
255                   passed to Rose::DateTime::Util's format_date function along
256                   with the current value of the datetime attribute.  Example:
257
258                       $o->start_date('2004-05-22 12:34:56');
259                       print $o->start_date(format => '%A'); # "Saturday"
260
261                   If passed two arguments and the first argument is
262                   "truncate", then the second argument is taken as the value
263                   of the "to" argument to DateTime's truncate method, which
264                   is applied to a clone of the current value of the datetime
265                   attribute, which is then returned.  Example:
266
267                       $o->start_date('2004-05-22 04:32:01');
268
269                       # Equivalent to:
270                       # $d = $o->start_date->clone->truncate(to => 'month')
271                       $d = $o->start_date(truncate => 'month');
272
273                   If the datetime attribute is undefined, then undef is
274                   returned (i.e., no clone or call to truncate is made).
275
276                   If a valid datetime keyword is passed as an argument, the
277                   value will never be "inflated" but rather passed to the
278                   database and returned to other code unmodified.  That means
279                   that the "truncate" and "format" calls described above will
280                   also return the datetime keyword unmodified.  See the
281                   Rose::DB documentation for more information on datetime
282                   keywords.
283
284               "get"
285                   Creates an accessor method for a "datetime" attribute.
286                   This method behaves like the "get_set" method, except that
287                   the value cannot be set.
288
289               "set"
290                   Creates a mutator method for a "datetime" attribute.  This
291                   method behaves like the "get_set" method, except that a
292                   fatal error will occur if no arguments are passed.  It also
293                   does not support the "truncate" and "format" parameters.
294
295           Example:
296
297               package MyDBObject;
298
299               use base 'Rose::DB::Object';
300
301               use Rose::DB::Object::MakeMethods::Date
302               (
303                 datetime =>
304                 [
305                   'start_date',
306                   'end_date'   => { default => '2005-01-30 12:34:56' }
307                   'other_date' => { type => 'datetime year to minute' },
308                 ],
309               );
310
311               ...
312
313               $o->start_date('2/3/2004 8am');
314               $dt = $o->start_date(truncate => 'day');
315
316               # 01/30/2005 12:34:56
317               print $o->end_date(format => '%m/%d/%Y %H:%M:%S');
318
319               $o->other_date('2001-02-20 12:34:56');
320
321               # 02/20/2001 12:34:00
322               print $o->other_date(format => '%m/%d/%Y %H:%M:%S');
323
324       epoch
325           Create get/set methods for an attribute that stores seconds since
326           the Unix epoch.
327
328           Options
329               "default"
330                   Determines the default value of the attribute.
331
332               "hash_key"
333                   The key inside the hash-based object to use for the storage
334                   of this attribute.  Defaults to the name of the method.
335
336               "hires"
337                   A boolean flag that indicates whether or not epoch values
338                   should be stored with fractional seconds.  If true, then up
339                   to six (6) digits past the decimal point are preserved.
340                   The default is false.
341
342               "interface"
343                   Choose the interface.  The default is "get_set".
344
345               "time_zone"
346                   The time zone name, which must be in a format that is
347                   understood by DateTime::TimeZone.
348
349           Interfaces
350               "get_set"
351                   Creates a get/set method for an attribute that stores
352                   seconds since the Unix epoch.  When setting the attribute,
353                   the value is passed through Rose::DateTime::Util's
354                   parse_date() function.  If that fails, a fatal error will
355                   occur.
356
357                   The time zone of the DateTime object that results from a
358                   successful parse is set to the value of the "time_zone"
359                   option, if defined.  Otherwise, it is set to the
360                   server_time_zone value of the  object's db attribute using
361                   DateTime's set_time_zone method.
362
363                   When saving to the database, the epoch or hires_epoch
364                   method will be called on the DateTime object, depending on
365                   the value of the "hires" option.  (See above.)
366
367                   This method is designed to allow values to make a round
368                   trip from and back into the database without ever being
369                   "inflated" into DateTime objects.  Any use of the attribute
370                   (get or set) outside the context of loading from or saving
371                   to the database will cause the value to be "inflated" using
372                   Rose::DateTime::Util's parse_date() function.  If that
373                   fails, a fatal error will occur.
374
375                   If passed two arguments and the first argument is "format",
376                   then the second argument is taken as a format string and
377                   passed to Rose::DateTime::Util's format_date function along
378                   with the current value of the attribute.  Example:
379
380                       $o->due_date('2004-05-22');
381                       print $o->due_date(format => '%A'); # "Saturday"
382
383                   If passed two arguments and the first argument is
384                   "truncate", then the second argument is taken as the value
385                   of the "to" argument to DateTime's truncate method, which
386                   is applied to a clone of the current value of the
387                   attribute, which is then returned.  Example:
388
389                       $o->due_date('2004-05-22');
390
391                       # Equivalent to:
392                       # $d = $o->due_date->clone->truncate(to => 'month')
393                       $d = $o->due_date(truncate => 'month');
394
395                   If the attribute is undefined, then undef is returned
396                   (i.e., no clone or call to truncate is made).
397
398               "get"
399                   Creates an accessor method an attribute that stores seconds
400                   since the Unix epoch.  This method behaves like the
401                   "get_set" method, except that the value cannot be set.
402
403               "set"
404                   Creates a mutator method for an attribute that stores
405                   seconds since the Unix epoch.  This method behaves like the
406                   "get_set" method, except that a fatal error will occur if
407                   no arguments are passed.  It also does not support the
408                   "truncate" and "format" parameters.
409
410           Example:
411
412               package MyDBObject;
413
414               use base 'Rose::DB::Object';
415
416               use Rose::DB::Object::MakeMethods::Date
417               (
418                 epoch =>
419                 [
420                   due_date    => { default => '2003-01-02 12:34:56' },
421                   event_start => { hires => 1 },
422                 ],
423               );
424
425               ...
426
427               print $o->due_date(format => '%m/%d/%Y'); # 01/02/2003
428               $dt = $o->due_date(truncate => 'week');
429
430               $o->event_start('1980-10-11 6:00.123456');
431               print $o->event_start(format => '%6N'); # 123456
432
433       timestamp
434           Create get/set methods for "timestamp" (year, month, day, hour,
435           minute, second, fractional seconds) attributes.
436
437           Options
438               "default"
439                   Determines the default value of the attribute.
440
441               "hash_key"
442                   The key inside the hash-based object to use for the storage
443                   of this attribute.  Defaults to the name of the method.
444
445               "interface"
446                   Choose the interface.  The default interface is "get_set".
447
448               "time_zone"
449                   A time zone name, which must be in a format that is
450                   understood by DateTime::TimeZone.
451
452           Interfaces
453               "get_set"
454                   Creates a get/set method for a "timestamp" (year, month,
455                   day, hour, minute, second, fractional seconds) attribute.
456                   When setting the attribute, the value is passed through the
457                   "parse_timestamp()" method of the object's db attribute.
458                   If that fails, the value is passed to
459                   Rose::DateTime::Util's parse_date() function.  If that
460                   fails, a fatal error will occur.
461
462                   The time zone of the DateTime object that results from a
463                   successful parse is set to the value of the "time_zone"
464                   option, if defined.  Otherwise, it is set to the
465                   server_time_zone value of the  object's db attribute using
466                   DateTime's set_time_zone method.
467
468                   When saving to the database, the method will pass the
469                   attribute value through the format_timestamp method of the
470                   object's db attribute before returning it.  Otherwise, the
471                   value is returned as-is.
472
473                   This method is designed to allow timestamp values to make a
474                   round trip from and back into the database without ever
475                   being "inflated" into DateTime objects.  Any use of the
476                   attribute (get or set) outside the context of loading from
477                   or saving to the database will cause the value to be
478                   "inflated" using the  "parse_timestamp()" method of the
479                   object's db attribute.  If that fails,
480                   Rose::DateTime::Util's parse_date() function is tried.  If
481                   that fails, a fatal error will occur.
482
483                   If passed two arguments and the first argument is "format",
484                   then the second argument is taken as a format string and
485                   passed to Rose::DateTime::Util's format_date function along
486                   with the current value of the timestamp attribute.
487                   Example:
488
489                       $o->start_date('2004-05-22 12:34:56.123');
490                       print $o->start_date(format => '%A'); # "Saturday"
491
492                   If passed two arguments and the first argument is
493                   "truncate", then the second argument is taken as the value
494                   of the "to" argument to DateTime's truncate method, which
495                   is applied to a clone of the current value of the timestamp
496                   attribute, which is then returned.  Example:
497
498                       $o->start_date('2004-05-22 04:32:01.456');
499
500                       # Equivalent to:
501                       # $d = $o->start_date->clone->truncate(to => 'month')
502                       $d = $o->start_date(truncate => 'month');
503
504                   If the timestamp attribute is undefined, then undef is
505                   returned (i.e., no clone or call to truncate is made).
506
507                   If a valid timestamp keyword is passed as an argument, the
508                   value will never be "inflated" but rather passed to the
509                   database and returned to other code unmodified.  That means
510                   that the "truncate" and "format" calls described above will
511                   also return the timestamp keyword unmodified.  See the
512                   Rose::DB documentation for more information on timestamp
513                   keywords.
514
515               "get"
516                   Creates an accessor method for a "timestamp" (year, month,
517                   day, hour, minute, second, fractional seconds) attribute.
518                   This method behaves like the "get_set" method, except that
519                   the value cannot be set.
520
521               "set"
522                   Creates a mutator method for a "timestamp" (year, month,
523                   day, hour, minute, second, fractional seconds) attribute.
524                   This method behaves like the "get_set" method, except that
525                   a fatal error will occur if no arguments are passed.  It
526                   also does not support the "truncate" and "format"
527                   parameters.
528
529           Example:
530
531               package MyDBObject;
532
533               use base 'Rose::DB::Object';
534
535               use Rose::DB::Object::MakeMethods::Date
536               (
537                 timestamp =>
538                 [
539                   'start_date',
540                   'end_date' => { default => '2005-01-30 12:34:56.123' }
541                 ],
542               );
543
544               ...
545
546               $o->start_date('2/3/2004 8am');
547               $dt = $o->start_date(truncate => 'day');
548
549               # 01/30/2005 12:34:56.12300
550               print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');
551
552       timestamp_without_time_zone
553           This is identical to the timestamp method described above, but with
554           the "time_zone" parameter always set to the value "floating".  Any
555           attempt to set the "time_zone" parameter explicitly will cause a
556           fatal error.
557
558       timestamp_with_time_zone
559           Create get/set methods for "timestamp with time zone" (year, month,
560           day, hour, minute, second, fractional seconds, time zone)
561           attributes.
562
563           Options
564               "default"
565                   Determines the default value of the attribute.
566
567               "hash_key"
568                   The key inside the hash-based object to use for the storage
569                   of this attribute.  Defaults to the name of the method.
570
571               "interface"
572                   Choose the interface.  The default interface is "get_set".
573
574               "time_zone"
575                   A time zone name, which must be in a format that is
576                   understood by DateTime::TimeZone.
577
578           Interfaces
579               "get_set"
580                   Creates a get/set method for a "timestamp with time zone"
581                   (year, month, day, hour, minute, second, fractional
582                   seconds, time zone) attribute.  When setting the attribute,
583                   the value is passed through the
584                   "parse_timestamp_with_timezone()" method of the object's db
585                   attribute.  If that fails, the value is passed to
586                   Rose::DateTime::Util's parse_date() function.  If that
587                   fails, a fatal error will occur.
588
589                   The time zone of the DateTime object will be set according
590                   to the successful parse of the "timestamp with time zone"
591                   value.  If the "time_zone" option is set, then the time
592                   zone of the DateTime object is set to this value.  Note
593                   that this happens after the successful parse, which means
594                   that this operation may change the time and/or date
595                   according to the difference between the time zone of the
596                   value as originally parsed and the new time zone set
597                   according to the "time_zone" option.
598
599                   When saving to the database, the method will pass the
600                   attribute value through the format_timestamp_with_timezone
601                   method of the object's db attribute before returning it.
602                   Otherwise, the value is returned as-is.
603
604                   This method is designed to allow timestamp values to make a
605                   round trip from and back into the database without ever
606                   being "inflated" into DateTime objects.  Any use of the
607                   attribute (get or set) outside the context of loading from
608                   or saving to the database will cause the value to be
609                   "inflated" using the  "parse_timestamp_with_time_zone()"
610                   method of the object's db attribute.  If that fails,
611                   Rose::DateTime::Util's parse_date() function is tried.  If
612                   that fails, a fatal error will occur.
613
614                   If passed two arguments and the first argument is "format",
615                   then the second argument is taken as a format string and
616                   passed to Rose::DateTime::Util's format_date function along
617                   with the current value of the timestamp attribute.
618                   Example:
619
620                       $o->start_date('2004-05-22 12:34:56.123');
621                       print $o->start_date(format => '%A'); # "Saturday"
622
623                   If passed two arguments and the first argument is
624                   "truncate", then the second argument is taken as the value
625                   of the "to" argument to DateTime's truncate method, which
626                   is applied to a clone of the current value of the timestamp
627                   attribute, which is then returned.  Example:
628
629                       $o->start_date('2004-05-22 04:32:01.456');
630
631                       # Equivalent to:
632                       # $d = $o->start_date->clone->truncate(to => 'month')
633                       $d = $o->start_date(truncate => 'month');
634
635                   If the timestamp attribute is undefined, then undef is
636                   returned (i.e., no clone or call to truncate is made).
637
638                   If a valid timestamp keyword is passed as an argument, the
639                   value will never be "inflated" but rather passed to the
640                   database and returned to other code unmodified.  That means
641                   that the "truncate" and "format" calls described above will
642                   also return the timestamp keyword unmodified.  See the
643                   Rose::DB documentation for more information on timestamp
644                   keywords.
645
646               "get"
647                   Creates an accessor method for a "timestamp with time zone"
648                   (year, month, day, hour, minute, second, fractional
649                   seconds, time zone) attribute.  This method behaves like
650                   the "get_set" method, except that the value cannot be set.
651
652               "set"
653                   Creates a mutator method for a "timestamp with time zone"
654                   (year, month, day, hour, minute, second, fractional
655                   seconds, time zone) attribute.  This method behaves like
656                   the "get_set" method, except that a fatal error will occur
657                   if no arguments are passed.  It also does not support the
658                   "truncate" and "format" parameters.
659
660           Example:
661
662               package MyDBObject;
663
664               use base 'Rose::DB::Object';
665
666               use Rose::DB::Object::MakeMethods::Date
667               (
668                 timestamp_with_timezone =>
669                 [
670                   'start_date',
671                   'end_date' => { default => '2005-01-30 12:34:56.123' }
672                 ],
673               );
674
675               ...
676
677               $o->start_date('2/3/2004 8am');
678               $dt = $o->start_date(truncate => 'day');
679
680               # 01/30/2005 12:34:56.12300
681               print $o->end_date(format => '%m/%d/%Y %H:%M:%S.%5N');
682

AUTHOR

684       John C. Siracusa (siracusa@gmail.com)
685

LICENSE

687       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
688       program is free software; you can redistribute it and/or modify it
689       under the same terms as Perl itself.
690
691
692
693perl v5.34.0                      2021-07R-o2s2e::DB::Object::MakeMethods::Date(3)
Impressum