NAME

DateTimeX::Mashup::Shiras - a mashup for consuming multiple date formats

SYNOPSIS

	package MyPackage;
	use Moose;
	with 'DateTimeX::Mashup::Shiras' => { -VERSION =>  0.014 };
	no Moose;
	__PACKAGE__->meta->make_immutable;

	#!perl
	my  $firstinst = MyPackage->new( 
			'date_one' => '8/26/00',
		);
	print $firstinst->get_date_one->format_cldr( "yyyy-MMMM-d" ) . "\n";
	print $firstinst->get_date_one_wkend->ymd( '' ) . "\n";
	print $firstinst->get_date_one_wkstart->ymd( '' ) . "\n";
	print $firstinst->set_date_three( '11-September-2001' ) . "\n";
	print $firstinst->get_date_three_wkstart->dmy( '' ) . "\n";
	print $firstinst->set_date_one( -1299767400 ) . "\n";
	print $firstinst->set_date_one( 36764.54167 ) . "\n";
	print $firstinst->set_date_one( 0 ) . "\n";
	print $firstinst->set_date_one( [0, 'epoch'] ) . "\n";
    
	#######################################
	#     Output of SYNOPSIS
	# 01:2000-August-26
	# 02:20000901
	# 03:20000826
	# 04:2001-09-14T00:00:00
	# 05:08092001
	# 06:1928-10-26T09:30:00
	# 07:2000-09-01T13:00:00
	# 08:1900-01-05T00:00:00
	# 09:1970-01-02T00:00:00
	#######################################

DESCRIPTION

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

This is a Moose Role that provides combined functionality from three different DateTime::Format packages. The three modules are; DateTime::Format::DateManip , DateTime::Format::Epoch, and DateTime::Format::Excel. It then uses the Moose type coersion system to choose the correct way to format the date. This means that all input strings are parsed by ::Format::DateManip. All numbers are parsed either by ::Format::Excel or ::Format::Epoch. Since the numbers of each overlap, the rule is all positive numbers under 7 positions left of the decimal are given to ::Excel and negative integers and integers of 7 or greater positions are given to ::Epoch. Numbers outside of this range fail the type constraints. See the Attribute section below for a way to force the numerical values to be parsed by the non-preffered formatter in the overlap. Currently the Epoch is fixed at midnight 1-January-1970. Since all the succesful date 'getters' return DateTime objects, all the DateTime methods can be applied directly. ex. $inst->get_today_wkend->ymd( "/" ).

I learned the magic for the input coersion from The Moose is Flying (part 2) by Merlyn / Randal L. Schwartz++. Any goodness found here should be attributed there, while I accept the responsibility for any errors.

Attributes

Attributes listed here can be passed to ->new as listed below.

(date_one|date_two|date_three)

Definition: these are date attributes that can be accept data that can be formatted via any of the supported DateTime::Format modules. All positive real numbers with 6 or fewer positions left of the decimal will be treated as Excel dates. All integers over 7 digits will be treated as epoch seconds from 1-January-1970. Negative decimals will fail! To force an integer with less than 7 digits into an epoch format send the value as an array ref with the number in the first position and 'epoch' in the second position. ex. [ 60, 'epoch' ] To force a number into excel formatting do the same with 'excel' in the second position.

Default empty

Range See DateTime::Format::Excel, DateTime::Format::Epoch, and DateTime::Format::DateManip for specific input range issues. The results will all be coerced to a DateTime instance. Currently input of Time Zones is not supported.

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, read, or clear attributes. See Moose::Manual::Roles for generic implementation instructions.

set_(date_one|date_two|date_three)( $date )

Definition: This is another way to set (or change) the various dates if additional input is required after the initial declaration of ->new( 'attribute' => 'value', ) command.

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

Returns: a DateTime object

get_(date_one|date_two|date_three|today)( 'DateTime->formatcommand' )

Definition: This is how you can call various dates and format their output. example $self->get_date_two( 'ymd( "-" )' ). For this example the date_two attribute had been previously set. Note: 'today' and 'now' are special attribute cases and do not need to be defined to be retrieved.

Accepts: This returns a DateTime object which will stringify to scalar data by default. However, if you want to format the output then call the '->get_$attribute_name' method with the additional DateTime formatting tagged on the end. ex. ->get_today->format_cldr( "yyyy-MMMM-d" ).

Returns: a DateTime object. If the object is passed DateTime methods then the format determined by that method will be applied.

get_$attribute_name_(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. All dates listed above including 'today' can be substitued for $attributename. 'now' does not provide a weekend extrapolation.

Returns: a DateTime object. If the object is passed DateTime formatting then that formatting will be applied.