view release on metacpan or  search on metacpan

lib/App/Sqitch/ItemFormatter.pm  view on Meta::CPAN

App::Sqitch::ItemFormatter - Format events and changes for command output

=head1 Synopsis

  my $formatter = App::Sqitch::ItemFormatter->new(%params);
  say $formatter->format($format, $item);

=head1 Description

This class is used by commands to format items for output. For example,
L<C<log>|sqitch-log> uses it to format the events it finds. It uses
L<String::Formatter> to do the actual formatting, but configures it for all
the various times of things typically displayed, such as change names, IDs,
event types, etc. This keeps things relatively simple, as all one needs to
pass to C<format()> is a format and then a hash reference of values to be used
in the format.

=head1 Interface

=head2 Constructor

=head3 C<new>

  my $formatter = App::Sqitch::ItemFormatter->new(%params);

Constructs and returns a formatter object. The supported parameters are:

=over

=item C<abbrev>

Instead of showing the full 40-byte hexadecimal change ID, format as a partial
prefix the specified number of characters long.

=item C<date_format>

Format to use for timestamps. Defaults to C<iso>. Allowed values:

=over

=item C<iso>

=item C<iso8601>

ISO-8601 format.

=item C<rfc>

=item C<rfc2822>

RFC-2822 format.

=item C<full>

=item C<long>

=item C<medium>

=item C<short>

A format length to pass to the system locale's C<LC_TIME> category.

=item C<raw>

Raw format, which is strict ISO-8601 in the UTC time zone.

=item C<strftime:$string>

An arbitrary C<strftime> pattern. See L<DateTime/strftime Paterns> for
comprehensive documentation of supported patterns.

=item C<cldr:$pattern>

An arbitrary C<cldr> pattern. See L<DateTime/CLDR Paterns> for comprehensive
documentation of supported patterns.

=back

=item C<color>

Controls the use of ANSI color formatting. The value may be one of:

=over

=item C<auto> (the default)

=item C<always>

=item C<never>

=back

=item C<formatter>

A String::Formatter object. You probably don't want to pass one of these, as
the default one understands all the values to that Sqitch is likely to want to
format.

=back

=head2 Instance Methods

=head3 C<format>

  $formatter->format( $format, $item );

Formats an item as a string and returns it. The item will be formatted using
the first argument. See L</Formats> for the gory details.

The second argument is a hash reference defining the item to be formatted.
These are simple key/value pairs, generally identifying attribute names and
values. The supported keys are:

=over

=item C<event>

The type of event, which is one of:

=over