The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
PTools-0.01
/ PTools::Date::Format

NAME

PTools::Date::Format - An OO interface to Date::Format, with additions

VERSION

This document describes version 0.05, released July, 2004, and is designed to be compatible with Date::Format 2.22.

SYNOPSIS

Procedural Interface

        use PTools::Date::Format qw( :orig );
        use PTools::Date::Format qw( :orig date1 );
        use PTools::Date::Format qw( time2str strftime ctime asctime );
        use PTools::Date::Format qw( time2str strftime date1 );

	print time2str( "%c is day %u in week %U%n", time() );

Object Oriented Interface

use PTools::Date::Format;
use PTools::Date::Format qw( date1 );

$date = new PTools::Date::Format;
$date = "PTools::Date::Format";

print $date->time2str( "%c is day %u in week %U%n", time() );

Modified Conversion Specification

use PTools::Date::Format qw( :orig date1 );
use PTools::Date::Format qw( date1 );

DESCRIPTION

This module provides routines identical to the Date::Format class. When 'used', this module can be configured to behave as follows.

. configured for procedural function calls, just as the parent class
. configured for object oriented syntax not supported by the parent

. configured to use the same conversion specifications as the parent
. configured to use modified conversion specifications similar to date(1)

For this class to act in an identical manner to the original, make sure to include either the ':orig' directive or all four of the original function names 'time2str', 'strftime', 'ctime' and 'asctime'. Also make sure to omit the 'date1' directive to achieve identical behavior with the conversion specification defined in the parent class.

Once 'used,' the invoking class should not attempt to modify the configuration by reissuing the 'use' function. This is not yet supported by this module, and the results are unpredictable.

MODIFIED CONVERSION SPECIFICATION

If the 'date1' configuration argument is passed when using this class, the original conversion specifications are modified to be 'more compatible' with the Unix date(1) formatting directives.

Additions and modifications to the original conversion specification includes the following characters.

%c	Current date and time (eg Fri Jul  9 19:04:05 2004)
%C 	Century as a two-digit decimal number (eg 20)
%u      weekday as a one-digit number (Monday == 1, Sunday == 7)

ERRORS

This class attempts to notify the user of configuration errors. However, not all errors can be detected by the script but are caught by the Perl interpreter. The following list includes possible problems, their causes and suggested solutions.

Error: Undefined subroutine _subroutine_name_

The calling script is attempting to invoke a procedural function that was not imported when this module was 'used.' Make sure that the invoked function name (or the special tag ':orig') was included in the list of configuration parameters.

use PTools::Date::Format qw( :orig );

use PTools::Date::Format qw( time2str asctime );

When used as the first example shows, this module will act in an identical manner to the original Date::Format class. Note that it is not necessary to import all of the function names into the calling program, only the functions that will be invoked.

Formatting directives don't work as expected

Adding the 'date1' configuration parameter when this class is 'used' causes modifications to the conversion specifications as noted, above.

use PTools::Date::Format qw( :orig date1 );

use PTools::Date::Format qw( date1 );

If the resulting formatted date string is always 'PTools::Date::Format' the calling stript is attempting to invoke conversion functions as 'class methods' when the module was configured for procedural usage.

The following example of incorrect usage demonstrates this last error condition.

        use PTools::Date::Format qw( :orig );

	$date = "PTools::Date::Format";

	print $date->time2str("%c is day %u in week %U%n", time());

The solution is to match the configuration arguments with the usage. Either omit the ':orig' configuration argument, or invoke conversion as subroutine functions and not as class/object methods.

The following is an example of correct Procedural usage.

        use PTools::Date::Format qw( :orig );

	print time2str( "%c is day %w in week %U%n", time() );

Error: OO Interface must be configured during 'use'

The calling script is attempting to invoke the 'new' method when this module was configured for Procedural usage.

The following is an example of correct Object Oriented usage.

        use PTools::Date::Format;

	$date = new PTools::Date::Format;
    or  $date = "PTools::Date::Format";

	print $date->time2str("%c is day %w in week %U%n", time());

Note that in this last example, as in the one just above, the '%w' formatting directive is used (instead of '%u' as was used in other examples). This is because, without specifying the 'date1' configuration directive when using this class, the '%u' directive is not recognized.

SEE ALSO

See Date::Format.

AUTHOR

Chris Cobb, <nospamplease@ccobb.net>

COPYRIGHT

Copyright (c) 2004-2007 by Chris Cobb. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.