NAME
DateTime::Fiscal::Retail454 - create 4-5-4 Calendar data from DateTime objects.
SYNOPSIS
use DateTime::Fiscal::Retail454;
my $r454 = DateTime::Fiscal::Nrg454->new( r454year => 2006 );
if ( $r454->is_r454_leap_year ) {
# do something here
}
my $fiscalyear = $r454->r454_year;
my $startdate = $r454->r454_start; # start of fiscal year
my $enddate = $r454->r454_end; # end of fiscal year
my @fiscalperiod_data = $r454->r454_period; # returns all period data
my $fp_number = $r454->r454_period; # returns period number
my $fp_weeks = $r454->r454_period_weeks; # number of weeks in period
my $fp_start = $r454->r454_period_start; # period start date
my $fp_end = $r454->r454_period_end; # period end date
my $fp_end = $r454->r454_period_publish; # period publish dateSee the details below for each method for options.
DESCRIPTION
This module is a sub-class of DateTime and inherits all methods and capabilities, including constructors, of that module.
The purpose of this module is to make it easy to work with the 4-5-4 calendar that is common among merchandisers. Details of the calendar itself can be found at the National Retail Federation (NRF) website. http://www.nrf.com/content/default.asp?folder=services&file=finance_454.htm
All objects returned by any of the methods in this module or of the class DateTime::Fiscal::Retail454 unless otherwise specified.
EXPORTS
None.
DEPENDENCIES
Carp
DateTimeCONSTRUCTORS
All of the constructors from the parent DateTime class can be used to obtain a new object.
In addition, an additional constructor named from_r454year has been added.
from_r454year
my $r454 = DateTime::Fiscal::Retail454->from_r454year( r454year => 2000 );Returns an object of type DateTime::Fiscal::Retail454 with a value of the first day in the specified FISCAL year.
The r454year parameter is mandatory.
METHODS
r454_year
my $r454 = DateTime::Fiscal::Retail454->new( year => 2006, month = 4 );
print $r454->r454_year; # print "2006"
my $r454_2 = DateTime::Fiscal::Retail454->new( year => 2006, month = 1 );
print $r454->r454_year; # print "2005"Returns a scalar containing the Fiscal Year that the object is in. This is not always the same as the calendar year, especially for dates in January and occasionally in February. This is because the start of the Fiscal Year is tied to what day of the week Jan 31 of any given year falls on.
is_r454_leap_year
my $r454 = DateTime::Fiscal::Retail454->new( r454year => 2006 );
print "This is a Fiscal Leap Year" if $r454->is_r454_leap_year;Returns a Boolean value indicating whether or not the Fiscal Year for the object has 53 weeks instead of the standard 52 weeks.
r454_start
my $startdate = $r454->r454_start;
my $startobj = $r454->r454_start( as_obj => 1 );Returns the starting date for the object's Fiscal Year as either a string or an object as specified by the as_obj parameter (default is string).
r454_end
my $enddate = $r454->r454_end;
my $endobj = $r454->r454_end( as_obj => 1 );Returns the ending date for the object's Fiscal Year as either a string or an object as specified by the as_obj parameter (default is string).
r454_period
This is the workhorse method and can be called in several ways.
# Return the current R454 period number
my $fp_number = $r454->r454_period;
# Return a list containing all data for the current period.
# The array is
# ( fp_number, fp_weeks, fp_start, fp_end, fp_publish, fp_year ).
my @fp_data = $r454->r454_period;
# As above but with objects for fp_start and fp_end instead of strings
my @fp_data = $r454->r454_period( as_obj => 1 );
# Specify the period for which data is returned.
my @fp_data = $r454->r454_period( period => 5 );
my @fp_data = $r454->r454_period( period => 5, as_obj => 1 );As can be seen above, the calling context affects the return values. When called in scalar context it defaults to returning a scalar containing the current period number for the calling object. When called in list context it returns a list containing all avaiable data for a period. The list is structured as follows:
( fp_number, fp_weeks, fp_start, fp_end, fp_publish, fp_year )If the as_obj parameter is specified the values for fp_start and fp_end will objects of class DateTime::Fiscal::Retail454.
A specific period may be requested by using the period parameter. Using this parameter with no others will result in that period number being returned, probably not what you wanted.
Objects instead of strings may be specified by the as_obj parameter.
The individual components for the number of weeks, starting date, ending date and publish date may be obtained with the methods below if desired. The R454 year may be obtained separately by using the r454_year method.
r454_period_weeks
my $fp_weeks = $r454->r454_period_weeks;
my $fp_weeks = $r454->r454_period_weeks( period => 5 );Returns a salar with the number of weeks in either the current or specified period.
r454_period_start
my $fp_start = $r454->r454_period_start;
my $fp_startobj = $r454->r454_period_start( as_obj => 1);
my $fp_start = $r454->r454_period_start( period => 5 );
my $fp_startobj = $r454->r454_period_start( as_obj => 1, period => 5 );Returns either a string (default) or object representing the start of the current (default) or specified period.
r454_period_end
my $fp_end = $r454->r454_period_end;
my $fp_endobj = $r454->r454_period_end( as_obj => 1);
my $fp_end = $r454->r454_period_end( period => 5 );
my $fp_endobj = $r454->r454_period_end( as_obj => 1, period => 5 );Returns either a string (default) or object representing the end of the current (default) or specified period.
r454_period_publish
my $fp_publish = $r454->r454_period_publish;
my $fp_publishobj = $r454->r454_period_publish( as_obj => 1);
my $fp_publish = $r454->r454_period_publish( period => 5 );
my $fp_publishobj = $r454->r454_period_publish( as_obj => 1, period => 5 );Returns either a string (default) or object representing the publish date for the current (default) or specified period.
truncate
$r454->truncate( to => 'r454year' );
$r454->truncate( to => 'period' );The truncate method has been overloaded to add two new parameters as shown. The new parameters set the object value to either r454_start or r454_period as appropriate.
Any other parameters will result in a call to the parent class.
BUGS
You gotta be kidding! This is an alpha release, of course there will be some.
TODO
Method(s) to return the R454 week_of_year data for an object.
Method(s) need to be added that generate comparison tables with R454 leap years restated or not as desired.
Method(s) to return the R454 period or week_of_year for various holidays.
SEE ALSO
DateTime
The Retail 4-5-4 Calendar as descibed by the National Retail Federation http://www.nrf.com/content/default.asp?folder=services&file=finance_454.htm
SUPPORT
Support is provided by the author on a "as time permits" basis. Please report bugs or make feature requests to the email address below.
AUTHOR
Jim Bacon, <jim@nortx.com>
COPYRIGHT AND LICENSE
Copyright (C) 2006 by Jim Bacon
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The full text of the license can be found in the LICENSE file included with this module.