The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
DateTime-Fiscal-Retail454-0.02
River stage zero No dependents
++
/ DateTime::Fiscal::Retail454

NAME

DateTime::Fiscal::Retail454 - create 4-5-4 Calendar data from DateTime objects.

SYNOPSIS

 use DateTime::Fiscal::Retail454;
 
 my $r454 = DateTime::Fiscal::Retail454->new( year => 2006 );
 
 my $fiscalyear = $r454->r454_year; # Might NOT be what you expect!
 
 if ( $r454->is_r454_leap_year ) {
   # do something here
 }

 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 date

See 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/modules.php?name=Pages&sp_id=391

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
 DateTime

CONSTRUCTORS

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 RETAIL year. The r454year parameter is mandatory and an exception will result if it is missing.

The returned object will have a date in the range 'YYYY-01-29' - 'YYYY-02-04' depending on what day of the week Jan 31 of the specified year YYYY falls on.

The algorythm for selecting the starting date can be stated as follows:

Obtain the day of the week for Jan 31 of the specified year as a number in the range 1 - 7 where Monday = 1, Tuesday = 2, etc.

If the day of the week is < 3, then subtract that number of days from Jan 31 to obtain the date of the preceding Sunday as the starting date.

If the day of the week is < 7, then first substract that number from 7, and then add the resulting number of days to Jan 31 to obtain the date of the following Sunday as the starting date.

If the day of the week is 7 (or Sunday) then no further changes are needed and the starting date is in fact YYYY-01-31 for that year.

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.

r454_period_month

 my $fp_month = $r454->r454_period_month;
 my $fp_month = $r454->r454_period_month( period => 5 );

Returns the nominal name of the month for the current 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! I'm human, 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/modules.php?name=Pages&sp_id=391

SUPPORT

Support is provided by the author. Please report bugs or make feature requests to the email address below.

IMPORTANT NOTE

This module sub-classes DateTime and pokes around under the hood in some cases. That is the beauty (and curse) of perl.

A significant change in the internal structure of DateTime around version 0.64 required corresponding changes to this module. Be advised that this can happen again in the future.

This module was developed using versions 0.36 and 0.76 of DateTime on two different platforms.

Please let me know of any problems you encounter. Be sure to include the version number of DateTime you are using.

AUTHOR

Jim Bacon, <jim@nortx.com>

COPYRIGHT AND LICENSE

Copyright (C) 2012 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.