File Coverage

blib/lib/DateTime/Format/Oracle.pm

Criterion	Covered	Total	%
statement	47	51	92.1
branch	5	10	50.0
condition			n/a
subroutine	17	20	85.0
pod	10	10	100.0
total	79	91	86.8

package DateTime::Format::Oracle;

use strict;

use Carp;
use DateTime;
use DateTime::Format::Builder;
use Convert::NLS_DATE_FORMAT;

our $VERSION = '0.06';
our $nls_date_format = 'YYYY-MM-DD HH24:MI:SS';
our $nls_timestamp_format = 'YYYY-MM-DD HH24:MI:SS';
our $nls_timestamp_tz_format = 'YYYY-MM-DD HH24:MI:SS TZHTZM';

=head1 NAME

DateTime::Format::Oracle - Parse and format Oracle dates and timestamps

=head1 SYNOPSIS

  use DateTime::Format::Oracle;

  $ENV{'NLS_DATE_FORMAT'} = 'YYYY-MM-DD HH24:MI:SS';
  my $dt = DateTime::Format::Oracle->parse_datetime('2003-01-16 23:12:01');
  my $string = DateTime::Format::Oracle->format_datetime($dt);

=head1 DESCRIPTION

This module may be used to convert Oracle date and timestamp values
into C objects.  It also can take a C object and
produce a date string matching the C.

Oracle has flexible date formatting via its C session
variable.  Date values will be returned from Oracle according to the
current value of that variable.  Date values going into Oracle must also
match the current setting of C.

Timestamp values will match either the C or
C session variables.

This module keeps track of these Oracle session variable values by
examining environment variables of the same name.  Each time one of
Oracle's formatting session variables is updated, the C<%ENV> hash
must also be updated.

=head1 METHODS

This class offers the following methods.

=over 4

=item * nls_date_format

This method is used to determine the current value of Oracle's
C.  It currently just reads the value from

  $ENV{'NLS_DATE_FORMAT'}

or if that is not set, from the package variable C<$nls_date_format>,
which has a default value of C.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's NLS_DATE_FORMAT and the value from this method
are not the same.

If you want to use the default from this module, you can do something
like this after you connect to Oracle:

  $dbh->do(
      "alter session set nls_date_format = '" .
      DateTime::Format::Oracle->nls_date_format .
      "'"
  );

=cut

sub nls_date_format { $ENV{NLS_DATE_FORMAT} || $nls_date_format }

=item * nls_timestamp_format

This method is used to determine the current value of Oracle's
C.  It currently just reads the value from

  $ENV{'NLS_TIMESTAMP_FORMAT'}

or if that is not set, from the package variable C<$nls_timestamp_format>,
which has a default value of C.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's NLS_TIMESTAMP_FORMAT and the value from this method
are not the same.

If you want to use the default from this module, you can do something
like this after you connect to Oracle:

  $dbh->do(
      "alter session set nls_timestamp_format = '" .
      DateTime::Format::Oracle->nls_timestamp_format .
      "'"
  );

=cut

sub nls_timestamp_format { $ENV{NLS_TIMESTAMP_FORMAT} || $nls_timestamp_format }

=item * nls_timestamp_tz_format

This method is used to determine the current value of Oracle's
C.  It currently just reads the value from

  $ENV{'NLS_TIMESTAMP_TZ_FORMAT'}

or if that is not set, from the package variable C<$nls_timestamp_tz_format>,
which has a default value of C.  This is
a good default to have, but is not Oracle's default.  Dates will fail
to parse if Oracle's NLS_TIMESTAMP_TZ_FORMAT and the value from this method
are not the same.

If you want to use the default from this module, you can do something
like this after you connect to Oracle:

  $dbh->do(
      "alter session set nls_timestamp_tz_format = '" .
      DateTime::Format::Oracle->nls_timestamp_tz_format .
      "'"
  );

=cut

sub nls_timestamp_tz_format { $ENV{NLS_TIMESTAMP_TZ_FORMAT} || $nls_timestamp_tz_format }

=item * parse_datetime

Given a string containing a date and/or time representation
matching C, this method will return a new
C object.

If given an improperly formatted string, this method may die.

=cut

sub parse_datetime { $_[0]->current_date_parser->(@_); }

=item * parse_date

Alias to C.  Oracle's date datatype also holds
time information.

=cut

*parse_date = \&parse_datetime;

=item * parse_timestamp

Given a string containing a date and/or time representation
matching C, this method will return a new
C object.

If given an improperly formatted string, this method may die.

=cut

sub parse_timestamp { $_[0]->current_timestamp_parser->(@_); }

=item * parse_timestamptz
=item * parse_timestamp_with_time_zone

Given a string containing a date and/or time representation
matching C, this method will return a new
C object.

If given an improperly formatted string, this method may die.

=cut

sub parse_timestamptz { $_[0]->current_timestamptz_parser->(@_); }
*parse_timestamp_with_time_zone = \&parse_timestamptz;

=item * current_date_parser

The current C generated parsing method
used by C and C.

=cut

*current_date_parser = _parser_generator('current_date_format');

=item * current_timestamp_parser

The current C generated parsing method
used by C.

=cut

*current_timestamp_parser = _parser_generator('current_timestamp_format');

=item * current_timestamptz_parser

The current C generated parsing method
used by C.

=cut

*current_timestamptz_parser = _parser_generator('current_timestamptz_format');

sub _parser_generator {
    # takes a method name for getting the current POSIX format
    # returns a parser generator code ref
    my $previous_format = '';
    my $previous_parser = '';
    my $method = shift;
    sub {
        my ( $self ) = @_;
        unless ($previous_format eq (my $current_format = $self->$method())) {
            $previous_format = $current_format;
            $previous_parser = $self->_create_parser_method($current_format);
        }
        return $previous_parser;
    }
}

sub _create_parser_method {
    # takes a strptime format, returns a parser method code ref
    my ( $self, $date_format ) = @_;
    my %parse_date = ( strptime => { pattern => $date_format } );
    my $parser = DateTime::Format::Builder->create_parser(\%parse_date);
    return DateTime::Format::Builder->create_method($parser);
}

=item * format_datetime

Given a C object, this method returns a string matching
the current value of C.

It is important to keep the value of C<$ENV{'NLS_DATE_FORMAT'}> the
same as the value of the Oracle session variable C.

To determine the current value of Oracle's C:

  select NLS_DATE_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's C:

  alter session set NLS_DATE_FORMAT='YYYY-MM-DD HH24:MI:SS'

It is generally a good idea to set C to an
unambiguos value, with four-digit year, and hour, minute, and second.

=cut

sub format_datetime {
    my ($self, $dt) = @_;
    return $dt->strftime($self->current_date_format);
}

=item * format_date

Alias to C.

=cut

*format_date = \&format_datetime;

=item * format_timestamp

Given a C object, this method returns a string matching
the current value of C.

It is important to keep the value of C<$ENV{'NLS_TIMESTAMP_FORMAT'}> the
same as the value of the Oracle session variable C.

To determine the current value of Oracle's C:

  select NLS_TIMESTAMP_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's C:

  alter session set NLS_TIMESTAMP_FORMAT='YYYY-MM-DD HH24:MI:SS'

It is generally a good idea to set C to an
unambiguos value, with four-digit year, and hour, minute, and second.

=cut

sub format_timestamp {
    my ($self, $dt) = @_;
    return $dt->strftime($self->current_timestamp_format);
}

=item * format_timestamptz
=item * format_timestamp_with_time_zone

Given a C object, this method returns a string matching
the current value of C.

It is important to keep the value of C<$ENV{'NLS_TIMESTAMP_TZ_FORMAT'}> the
same as the value of the Oracle session variable C.

To determine the current value of Oracle's C:

  select NLS_TIMESTAMP_TZ_FORMAT from NLS_SESSION_PARAMETERS

To reset Oracle's C:

  alter session set NLS_TIMESTAMP_TZ_FORMAT='YYYY-MM-DD HH24:MI:SS TZHTZM'

It is generally a good idea to set C to an
unambiguos value, with four-digit year, and hour, minute, and second.

=cut

sub format_timestamptz {
    my ($self, $dt) = @_;
    return $dt->strftime($self->current_timestamptz_format);
}

*format_timestamp_with_time_zone = \&format_timestamptz;

=item * current_date_format

The current generated method used by C,
C, and C to keep track of
the C translation of C.

=cut

*current_date_format = _format_generator('nls_date_format');

=item * current_timestamp_format

The current generated method used by C,
C, and C to keep track of
the C translation of C.

=cut

*current_timestamp_format = _format_generator('nls_timestamp_format');

=item * current_timestamptz_format

The current generated method used by C,
C, and C to keep track of
the C translation of C.

=cut

*current_timestamptz_format = _format_generator('nls_timestamp_tz_format');

sub _format_generator {
    # takes a method name for getting the current Oracle format
    # returns a format generator code ref
    my $previous_nls_format = '';
    my $previous_format = '';
    my $method = shift;
    sub {
        my ( $self ) = @_;
        unless ($previous_nls_format eq (my $current_nls_format = $self->$method())) {
            $previous_nls_format = $current_nls_format;
            $previous_format = $self->oracle_to_posix($current_nls_format);
        }
        return $previous_format;
    }
}

=item * oracle_to_posix

Given an C, C, or
C value, this method returns a
C-compatible C format value.

Translation is currently handled by C.

=cut

sub oracle_to_posix {
    my ( $self, $nls_format ) = @_;
    Convert::NLS_DATE_FORMAT::oracle2posix($nls_format);
}

=back

=cut

1;

__END__