=pod =head1 NAME DateTimeX::Mashup::Shiras - A Moose role with date attributes =begin html Build Status perl version Coverage Status kwalitee =end html =head1 SYNOPSIS package MyPackage; use Moose; with 'DateTimeX::Mashup::Shiras' =>{ date_attributes =>[ qw( start_date end_date ) ], }; no Moose; __PACKAGE__->meta->make_immutable; #!env perl my $firstinst = MyPackage->new( 'start_date' => '8/26/00', ); print $firstinst->get_start_date->format_cldr( "yyyy-MMMM-d" ) . "\n"; print $firstinst->get_start_date_wkend->ymd( '' ) . "\n"; print $firstinst->get_start_date_wkstart->ymd( '' ) . "\n"; print $firstinst->set_end_date( '11-September-2001' ) . "\n"; print $firstinst->get_end_date_wkstart->dmy( '' ) . "\n"; print $firstinst->set_start_date( -1299767400 ) . "\n"; print $firstinst->set_start_date( 36764.54167 ) . "\n"; print $firstinst->set_start_date( 0 ) . "\n"; print $firstinst->set_start_date( 60 ) . "\n"; ####################################### # Output of SYNOPSIS # 01:2000-August-26 # 02:20000901 # 03:20000826 # 04:2001-09-11T00:00:00 # 05:08092001 # 06:1928-10-24T09:30:00 # 07:2000-08-26T13:00:00 # 09:1970-01-01T00:00:00 # 09:1970-01-01T00:01:00 ####################################### =head1 DESCRIPTION L - A small subspecies of Moose found in the western United States. This is a Moose Role (L) that can add date based attributes with some built in date converions to your Moose class. It also provides the traditional today, now, and weekend date calculation for the executed day. The date conversion functionality comes from three different DateTime::Format packages using L coersion. The three modules are; L, L, and L. The choice between them is managed by L as a type coersion. As a general rule all input strings are parsed by ::Format::Flexible. All numbers are parsed either by ::Format::Excel or by ::Format::Epoch. See the type package for the details and corner cases. Since all the succesful date 'getters' return DateTime objects, all the L methods can be applied directly. ex. $inst-Eget_today_wkend-Eymd( "/" ). =head2 Parameters This is a L role. The following parameters are passed as keys to a hash_ref when calling B{ %args }>. =head3 date_attributes =over B This is any array ref of the requested date attributes for the target class consuming this role. To review the behavior of each named attribute review the documentation for L<$named_attribute|/$named_attribute> below. B if this key is not called the role will set up the following four attributes; [ qw( date_one date_two date_three date_four )] (Yes the count four is arbitrary) B any string that can be treated as an attribute name. =back =head2 Attributes Data passed to new when creating an instance of the consuming class. For modification of these attributes see the listed L of the instance. =head3 $named_attribute =over B these are date attributes set to the type 'DateTimeDate'. See the L Class for more details. B empty B epoch numbers, DateTime definition HashRefs, Date Epoch ArrayRefs, and human readable strings =back =head3 week_end =over B This holds the definition of the last day of the week B 'Friday' B This will accept either day names, day abbreviations (no periods), or day integers (1 = Monday, 7 = Sunday ) =back =head2 Methods Methods are used to manipulate both the public and private attributes of this role. All attributes are set as 'ro' so other than ->new( ) these methods are the only way to change or clear attributes. See L for generic implementation instructions. =head3 set_${named_attribute}( $date ) =over B This is the way to change (or set) the various dates. B Any $date data that can be coerced by L modules. B the equivalent DateTime object =back =head3 get_(${named_attribute}|today|now)->format_command( 'format' ) =over B This is how you can call various dates and format their output. example $self->get_today->ymd( "-" ). B 'today' and 'now' are special attribute cases and do not need to be defined to be retrieved. B a DateTime object =back =head3 get_(${named_attribute}|today)_(wkend|wkstart) =over B This is a way to call the equivalent start and end of the week definded by the given 'week_end' attribute value. 'now' is not included in this list. B a DateTime object =back =head1 GLOBAL VARIABLES =head2 $ENV{Smart_Comments} The module uses L if the '-ENV' option is set. The 'use' is encapsulated in an if block triggered by an environmental variable to comfort non-believers. Setting the variable $ENV{Smart_Comments} in a BEGIN block will load and turn on smart comment reporting. There are three levels of 'Smartness' available in this module '###', '####', and '#####'. =head1 BUILD / INSTALL from Source B<1.> Download a compressed file with this package code from your favorite source =over L L L =back B<3.> Extract the code from the compressed file. =over If you are using tar on a .tar.gz file this should work: tar -zxvf DateTimeX-Mashup-Shiras-v0.xx.tar.gz =back B<4.> Change (cd) into the extracted directory B<5.> Run the following =over (for Windows find what version of make was used to compile your perl) perl -V:make (then for Windows substitute the correct make function (s/make/dmake/g)? below) =back >perl Makefile.PL >make >make test >make install # As sudo/root >make clean =head1 SUPPORT L =head1 TODO =over B<1.> Add L debugging in exchange for L =back =head1 AUTHOR =over Jed Lund jandrew@cpan.org =back =head1 CONTRIBUTORS This is the (likely incomplete) list of people who have helped make this distribution what it is, either via code contributions, patches, bug reports, help with troubleshooting, etc. A huge 'thank you' to all of them. =over L =back =head1 COPYRIGHT This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. This software is copyrighted (c) 2013, 2014 by Jed Lund. =head1 DEPENDENCIES =over B<5.010> - (L) L L L L L L L L =back =head1 SEE ALSO =over L L L L L =back =cut