File Coverage

blib/lib/Rubric/Entry/Formatter.pm

Criterion	Covered	Total	%
statement	28	31	90.3
branch	9	16	56.2
condition			n/a
subroutine	7	7	100.0
pod	1	1	100.0
total	45	55	81.8

use strict;
use warnings;
package Rubric::Entry::Formatter;
# ABSTRACT: a base class for entry body formatters
$Rubric::Entry::Formatter::VERSION = '0.156';
#pod =head1 DESCRIPTION
#pod
#pod This class serves as a single point of dispatch for attempts to format entry
#pod bodies from their native format into rendered output.
#pod
#pod =cut

use Carp ();
use Rubric::Config;

#pod =head1 METHODS
#pod
#pod =head2 C< format >
#pod
#pod   my $formatted = Rubric::Entry::Formatter->format(\%arg);
#pod
#pod This method accepts a set of named arguments and returns formatted output in
#pod the requested format.  If it is unable to do so, it throws an exception.
#pod
#pod Valid arguments are:
#pod
#pod  markup - the markup format used to mark up the text (default: _default)
#pod  text   - the text that has been marked up and should be formatted (required)
#pod  format - the requested output format (required)
#pod
#pod Formatting requests are dispatched according to the configuration in
#pod C.
#pod
#pod =cut

sub _load_formatter {
  my ($class, $formatter) = @_;

  return 1 if eval { $formatter->can('as_text'); };

  ## no critic (StringyEval)
  return 1 if eval qq{require $formatter};
  ## use critic

  return 0;
}

sub _formatter_for {
  my ($class, $markup) = @_;

  my $markup_formatter = Rubric::Config->markup_formatter;
  $markup_formatter->{_default} = 'Rubric::Entry::Formatter::Nil'
    unless $markup_formatter->{_default};

  Carp::croak "no formatter is registered for $markup markup"
    unless my $formatter = $markup_formatter->{ $markup };

  return $formatter;
}

sub format {
  my ($class, $arg) = @_;
  my $config = {}; # extra configuration for formatter code

  my $formatter = $class->_formatter_for($arg->{markup});

  if (ref $formatter) {
    $config = { %$formatter };
    Carp::croak "formatter config for $arg->{markup} includes no class"
      unless $formatter = delete $config->{class};
  }

  $class->_load_formatter($formatter)
    or Carp::croak "couldn't load formatter '$formatter': $@";

  my $formatter_code = $formatter->can("as_$arg->{format}")
    or Carp::croak "$formatter does not implement formatting to $arg->{format}";

  $formatter_code->($formatter, $arg, $config);
}

#pod =head1 WRITING FORMATTERS
#pod
#pod Writing a formatter should be very simple; the interface is very simple,
#pod although it's also very young and so it may change when I figure out the
#pod problems in the current implementation.
#pod
#pod A formatter must implement an C method for each format to which it
#pod claims to be able to output formatted text.  When Rubric::Entry::Formatter
#pod wants to dispatch text for formatting, it will call that method as follows:
#pod
#pod   my $formatted = Formatter->as_whatever(\%arg);
#pod
#pod The arguments in C<%arg> will be the same as those passed to
#pod Rubric::Entry::Formatter.
#pod
#pod Actually, the method is found and called via C, so a suitably programmed
#pod module can respond to C to allow it to render into all the format it likes
#pod -- or at least to claim to.
#pod
#pod =cut

1;

__END__