NAME

DateTimeX::Mashup::Shiras - A Moose role with date attributes

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
	#######################################

DESCRIPTION

Shiras - A small subspecies of Moose found in the western United States.

This is a Moose Role (Moose::Manual::Roles) 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 Type::Tiny coersion. The three modules are; DateTime::Format::Flexible, DateTime::Format::Epoch, and DateTimeX::Format::Excel. The choice between them is managed by DateTimeX::Mashup::Shiras::Types 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 DateTime methods can be applied directly. ex. $inst->get_today_wkend->ymd( "/" ).

Warnings

1. Double digit years in some date text strings are problematic. This package assumes that all double digit dates are no more than 20 years in the future of processing time (or more than 80 years before processing time)

Parameters

This is a MooseX::Role::Parameterized role. The following parameters are passed as keys to a hash_ref when calling with 'DateTimeX::Mashup::Shiras' =>{ %args }.

date_attributes

Definition: 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 $named_attribute below.

Default 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)

Range any string that can be treated as an attribute name.

Attributes

Data passed to new when creating an instance of the consuming class. For modification of these attributes see the listed "Methods" of the instance.

$named_attribute

Definition: these are date attributes set to the type 'DateTimeDate'. See the Type Class for more details.

Default empty

Range epoch numbers, DateTime definition HashRefs, Date Epoch ArrayRefs, and human readable strings

week_end

Definition: This holds the definition of the last day of the week

Default 'Friday'

Range This will accept either day names, day abbreviations (no periods), or day integers (1 = Monday, 7 = Sunday )

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 Moose::Manual::Roles for generic implementation instructions.

set_${named_attribute}( $date )

Definition: This is the way to change (or set) the various dates.

Accepts: Any $date data that can be coerced by supported ::Format modules.

Returns: the equivalent DateTime object

get_(${named_attribute}|today|now)->format_command( 'format' )

Definition: This is how you can call various dates and format their output. example $self->get_today->ymd( "-" ). Note: 'today' and 'now' are special attribute cases and do not need to be defined to be retrieved.

Returns: a DateTime object

get_(${named_attribute}|today)_(wkend|wkstart)

Definition: 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.

Returns: a DateTime object

GLOBAL VARIABLES

$ENV{Smart_Comments}

The module uses Smart::Comments 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 '#####'.

BUILD / INSTALL from Source

1. Download a compressed file with this package code from your favorite source

Meta::CPAN

github

CPAN

3. Extract the code from the compressed file.

If you are using tar on a .tar.gz file this should work:

tar -zxvf DateTimeX-Mashup-Shiras-v0.xx.tar.gz

4. Change (cd) into the extracted directory

5. Run the following

(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)

>perl Makefile.PL

>make

>make test

>make install # As sudo/root

>make clean

SUPPORT

github DateTimeX-Mashup-Shiras/issues

TODO

1. Add Log::Shiras debugging in exchange for Smart::Comments

AUTHOR

Jed Lund

jandrew@cpan.org

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.

Toby Inkster