Dogcows Code - chaz/git-codeowners/blob - lib/App/Codeowners/Formatter.pm

   1 package App::Codeowners::Formatter;
   2 # ABSTRACT: Base class for formatting codeowners output
   3
   4
   5 use warnings;
   6 use strict;
   7
   8 our $VERSION = '0.46'; # VERSION
   9
  10 use Module::Load;
  11
  12
  13 sub new {
  14     my $class = shift;
  15     my $args  = {@_ == 1 && ref $_[0] eq 'HASH' ? %{$_[0]} : @_};
  16
  17     $args->{results} = [];
  18
  19     # see if we can find a better class to bless into
  20     ($class, my $format) = $class->_best_formatter($args->{format}) if $args->{format};
  21     $args->{format} = $format;
  22
  23     my $self = bless $args, $class;
  24
  25     $self->start;
  26
  27     return $self;
  28 }
  29
  30 ### _best_formatter
  31 #   Find a formatter that can handle the format requested.
  32 sub _best_formatter {
  33     my $class = shift;
  34     my $type  = shift || '';
  35
  36     return ($class, $type) if $class ne __PACKAGE__;
  37
  38     my ($name, $format) = $type =~ /^([A-Za-z]+)(?::(.*))?$/;
  39     if (!$name) {
  40         $name   = '';
  41         $format = '';
  42     }
  43
  44     $name = lc($name);
  45     $name =~ s/:.*//;
  46
  47     my @formatters = $class->formatters;
  48
  49     # default to the string formatter since it has no dependencies
  50     my $package = __PACKAGE__.'::String';
  51
  52     # look for a formatter whose name matches the format
  53     for my $formatter (@formatters) {
  54         my $module = lc($formatter);
  55         $module =~ s/.*:://;
  56
  57         if ($module eq $name) {
  58             $package = $formatter;
  59             $type    = $format;
  60             last;
  61         }
  62     }
  63
  64     load $package;
  65     return ($package, $type);
  66 }
  67
  68
  69 sub DESTROY {
  70     my $self = shift;
  71     my $global_destruction = shift;
  72
  73     return if $global_destruction;
  74
  75     my $results = $self->{results};
  76     $self->finish($results) if $results;
  77     delete $self->{results};
  78 }
  79
  80
  81 sub handle  { shift->{handle}  }
  82 sub format  { shift->{format}  || '' }
  83 sub columns { shift->{columns} || [] }
  84 sub results { shift->{results} }
  85
  86
  87 sub add_result {
  88     my $self = shift;
  89     $self->stream($_) for @_;
  90 }
  91
  92
  93 sub start  {}
  94 sub stream { push @{$_[0]->results}, $_[1] }
  95 sub finish {}
  96
  97
  98 sub formatters {
  99     return qw(
 100         App::Codeowners::Formatter::CSV
 101         App::Codeowners::Formatter::JSON
 102         App::Codeowners::Formatter::String
 103         App::Codeowners::Formatter::TSV
 104         App::Codeowners::Formatter::Table
 105         App::Codeowners::Formatter::YAML
 106     );
 107 }
 108
 109 1;
 110
 111 __END__
 112
 113 =pod
 114
 115 =encoding UTF-8
 116
 117 =head1 NAME
 118
 119 App::Codeowners::Formatter - Base class for formatting codeowners output
 120
 121 =head1 VERSION
 122
 123 version 0.46
 124
 125 =head1 SYNOPSIS
 126
 127     my $formatter = App::Codeowners::Formatter->new(handle => *STDOUT);
 128     $formatter->add_result($_) for @results;
 129
 130 =head1 DESCRIPTION
 131
 132 This is a base class for formatters. A formatter is a class that takes data records, stringifies
 133 them, and prints them to an IO handle.
 134
 135 This class is mostly abstract, though it is also usable as a null formatter where results are simply
 136 discarded if it is instantiated directly. These other formatters do more interesting things:
 137
 138 =over 4
 139
 140 =item *
 141
 142 L<App::Codeowners::Formatter::CSV>
 143
 144 =item *
 145
 146 L<App::Codeowners::Formatter::String>
 147
 148 =item *
 149
 150 L<App::Codeowners::Formatter::JSON>
 151
 152 =item *
 153
 154 L<App::Codeowners::Formatter::TSV>
 155
 156 =item *
 157
 158 L<App::Codeowners::Formatter::Table>
 159
 160 =item *
 161
 162 L<App::Codeowners::Formatter::YAML>
 163
 164 =back
 165
 166 =head1 ATTRIBUTES
 167
 168 =head2 handle
 169
 170 Get the IO handle associated with a formatter.
 171
 172 =head2 format
 173
 174 Get the format string, which may be used to customize the formatting.
 175
 176 =head2 columns
 177
 178 Get an arrayref of column headings.
 179
 180 =head2 results
 181
 182 Get an arrayref of all the results that have been provided to the formatter using L</add_result> but
 183 have not yet been formatted.
 184
 185 =head1 METHODS
 186
 187 =head2 new
 188
 189     $formatter = App::Codeowners::Formatter->new;
 190     $formatter = App::Codeowners::Formatter->new(%attributes);
 191
 192 Construct a new formatter.
 193
 194 =head2 DESTROY
 195
 196 Destructor calls L</finish>.
 197
 198 =head2 add_result
 199
 200     $formatter->add_result($result);
 201
 202 Provide an additional lint result to be formatted.
 203
 204 =head2 start
 205
 206     $formatter->start;
 207
 208 Begin formatting results. Called before any results are passed to the L</stream> method.
 209
 210 This method may print a header to the L</handle>. This method is used by subclasses and should
 211 typically not be called explicitly.
 212
 213 =head2 stream
 214
 215     $formatter->stream(\@result, ...);
 216
 217 Format one result.
 218
 219 This method is expected to print a string representation of the result to the L</handle>. This
 220 method is used by subclasses and should typically not called be called explicitly.
 221
 222 The default implementation simply stores the L</results> so they will be available to L</finish>.
 223
 224 =head2 finish
 225
 226     $formatter->finish;
 227
 228 End formatting results. Called after all results are passed to the L</stream> method.
 229
 230 This method may print a footer to the L</handle>. This method is used by subclasses and should
 231 typically not be called explicitly.
 232
 233 =head2 formatters
 234
 235     @formatters = App::Codeowners::Formatter->formatters;
 236
 237 Get a list of package names of potential formatters within the C<App::Codeowners::Formatter>
 238 namespace.
 239
 240 =head1 BUGS
 241
 242 Please report any bugs or feature requests on the bugtracker website
 243 L<https://github.com/chazmcgarvey/git-codeowners/issues>
 244
 245 When submitting a bug or request, please include a test-file or a
 246 patch to an existing test-file that illustrates the bug or desired
 247 feature.
 248
 249 =head1 AUTHOR
 250
 251 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 252
 253 =head1 COPYRIGHT AND LICENSE
 254
 255 This software is copyright (c) 2019 by Charles McGarvey.
 256
 257 This is free software; you can redistribute it and/or modify it under
 258 the same terms as the Perl 5 programming language system itself.
 259
 260 =cut