/ 
Astro-App-Satpass2-0.054
River stage zero No dependents
/ Astro::App::Satpass2::FormatTime::DateTime

NAME

Astro::App::Satpass2::FormatTime::DateTime - Format time using DateTime

SYNOPSIS

None. All externally-available functionality is provided by either the superclass or one of the subclasses.

NOTICE

This class and its subclasses are private to the Astro::App::Satpass2 package. The author reserves the right to add, change, or retract functionality without notice.

DETAILS

This subclass of Astro::App::Satpass2::FormatTime is an abstract class for formatting dates and times using DateTime. What you really want to use is one of its subclasses: Astro::App::Satpass2::FormatTime::DateTime::Cldr, Astro::App::Satpass2::FormatTime::DateTime::Strftime, or Astro::App::Satpass2::FormatTime::POSIX::Strftime

METHODS

This class provides the following methods over and above those provided by Astro::App::Satpass2::FormatTime.

These are public unless otherwise stated in the documentation of the individual method. As a guide, you should expect methods whose name begins with a double underscore to be private to the Astro-App-Satpass2 package.

back_end

$self->back_end( 'DateTime::Calendar::Christian' );
$self->back_end( 'Christian' );
$self->back_end( 'Christian,reform_date=uk' );
$self->back_end( 'Christian', reform_date => 'uk' );

my $back_end = $self->back_end();
my ( $class, @arg ) = $self->back_end();

This method acts as both accessor and mutator for the back end class that does all the actual time formatting.

When called with arguments it is a mutator, setting the name of the back end class, and any arguments that need to be passed to its new() method. The class specified should conform to the DateTime interface. If the class name begins with 'DateTime::Calendar::', this can be omitted as in the second example above. Arguments can be specified as comma-delimited 'name=value' pairs, as in the third example, or as separate name/value arguments, as in the fourth example.

When called with no arguments this method is an accessor. If called in list context it returns the class name and argument/value pairs as separate items. If called in scalar context the arguments are concatenated to the class name as comma-delimited 'name=value' pairs.

__preprocess_strftime_format

my $mod = $self->__preprocess_strftime_format( $dt_obj, $fmt );

The functionality documented below is supported, but this method is not, and may be changed or revoked without notice at any time. This method will in fact throw an exception unless called from a subclass of this class.

This package-private method pre-processes a format, finding and potentially replacing substrings that look like '%{name:modifiers}'. This is a further extension of the DateTime extension, providing more control of the output.

The arguments are a DateTime or DateTime-ish object and the format that is to be pre-processed. The return is the pre-processed format.

In the substrings that are (potentially) replaced, the 'name' represents either a special-case string or the name of a method on the $dt_obj object. If it is neither, the substring is left unmodified. The special-case names are:

%

This causes a literal '%' to be inserted.

calendar_name

This causes either 'Gregorian' or 'Julian' to be inserted. You get 'Julian' only if $dt_obj has an is_julian() method, and that method returns a true value. Otherwise, if the class name of the back end object begins with 'DateTime::Calendar::' you get the shortened name. Otherwise you get 'Gregorian'. There is no provision for localization, unfortunately.

The colon and modifiers are optional. If present, the modifiers consist of, in order:

zero or more single-character flags;

These modify the formatting of the value, and may appear in any order. The following flags are implemented:

  • '-'

    This flag causes the output to be left-justified in its field. It is only effective if the field width (see below) is positive.

  • '0'

    This flag causes the output to be zero-filled on the left. It is only effective if the field width (see below) is positive, and '-' is not specified.

  • 't'

    This flag causes the output to be truncated on the right to the field width (see below). It is only effective if the field width is positive.

a field width.

This is a non-negative integer, not beginning with zero, which specifies the width of the output. Output will be at least this width, but may be wider unless the 't' flag was specified.

For example, if the $dt_obj represents the Ides of March, 44 BC, and the template is '%{year_with_christian_era:06}-%m-%d', the returned value will be '0044BC-%m-%d'.

$dt_obj->strftime(
    $self->__preprocess_strftime_format(
        $dt_obj, '%{year_with_christian_era:06}-%m-%d' ) );

would therefore produce '0044BC-03-15'.

SUPPORT

Support is by the author. Please file bug reports at https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-App-Satpass2, https://github.com/trwyant/perl-Astro-App-Satpass2/issues, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2010-2024 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.