Index

NAME
SYNOPSIS
DESCRIPTION
CLASS METHODS
- new
INSTANCE METHODS
- format
- unique_id
MISCELLANEOUS
- _do_format
- _do_unique_id
SEE ALSO
VERSION
AUTHOR
COPYRIGHT AND LICENSE

NAME

Newcomen::Formatter::Backend - Base class for formatter backends.

SYNOPSIS

package Newcomen::Formatter::MyBackend;

use namespace::autoclean;
use Moose;

extends 'Newcomen::Formatter::Backend';

override '_do_format' => sub {

   my $self    = shift;
   my $text    = shift;
   my $options = shift;
   my $content = shift;
   my $page    = shift;
   my $index   = shift;

   # Format text...

   return $text;

};

override '_do_unique_id' => sub {

   # Same parameters as above...

   # Calculate the ID...

   return $id;

};

__PACKAGE__ -> meta () -> make_immutable ();

1;

DESCRIPTION

This is the base class to be extended by formatter backends. It does not define any attributes.

It does define the methods format() and _do_format(). format() will call the _do_format() method, which has to be overridden by the actual backend implementation (see SYNOPSIS). The _do_format() method of the base class will simply die()!

It also defines the methods unique_id() and _do_unique_id(). Again, the former will automatically call the latter, which has to be overridden by the backend implementations (see SYNOPSIS). These methods are used by the frontend (see Newcomen::Formatter) for caching the formatter results. _do_unique_id() of the base class will return undef, which will disable caching for the backend.

CLASS METHODS

new

my $backend = Newcomen::Formatter::MyBackend -> new ();

Constructor, expects no parameters. new() will be called once for every (!) backend found. A backend does not have to be actually used to be instantiated! If it is actually used, format() will be called. The one backend instance will be used to format all content.

INSTANCE METHODS

format

Toggle source: format

sub format {

   my $self    = shift;
   my $text    = shift;
   my $opts    = shift;
   my $content = shift;
   my $page    = shift;
   my $index   = shift;

   confess 'Usage: format($text,$options,$content,$page,$index)' unless
      not @_ and defined $text and ref $text eq '' and defined $index and $index =~ /^\d+$/
      and is_a ($opts,    'Newcomen::Data')
      and is_a ($content, 'Newcomen::Content')
      and is_a ($page,    'Newcomen::Page');

   $text = $self -> _do_format ($text, $opts, $content, $page, $index);
   confess 'No string returned by formatter backend' unless defined $text and ref $text eq '';

   return $text;

}

$text = $backend -> format ($text, $backend_options, $content, $page, $index);

The format() method of a backend will be called when a piece of text should be formatted. It will return the formatted text. The original text to be formatted must be passed as first parameter, the backend options as second parameter (an Newcomen::Data instance), the Newcomen::Content instance as third parameter, the Newcomen::Page instance as fourth parameter and the index of the content on the page as fifth parameter.

The format() method must not be overridden by a backend implementation!

unique_id

Toggle source: unique_id

sub unique_id {

   my $self = shift;
   my $id   = $self -> _do_unique_id (@_);

   if (defined $id) {
      confess "Formatter's unique ID invalid" unless ref $id eq '' and $id =~ /^[a-z0-9_-]+$/ai;
   }

   return $id;

}

$id = $backend -> unique_id ($text, $backend_options, $content, $page, $index);

The unique_id() method will be called by the formatter frontend to retrieve a unique ID for a specific formatting operation. The unique ID may be derived from the backend options, page target, meta data, etc., but usually not from the text itself. If the backend option returns this unique ID, it may be used to cache the formatted text. The backend ensures that for the same unique ID the results of the formatting itself are always the same for the same input text. A backend may return undef, which means no caching should be used. If a unique ID is returned, it will consist only of the characters [A-Za-z0-9_-], it will not be an empty string.

MISCELLANEOUS

_do_format

Toggle source: _do_format

sub _do_format { confess '_do_format() not implemented by backend' }

The actual backends must implement a _do_format() method, _do_format() of this base class will die(). The parameters are the same as for the format() method described above.

_do_format() has to return a string containing the formatted text.

_do_unique_id

Toggle source: _do_unique_id

sub _do_unique_id { return undef }

If a backend wants its formatting results to be cached, it has to implement the _do_unique_id() method. This must return an ID used to identify a specific formatting operation, based on the supplied parameters. These parameters are the same as described for unique_id() above, see there for more details.

VERSION

This is version 2014052501.

AUTHOR

Stefan Goebel - newcomen {at} subtype {dot} de

COPYRIGHT AND LICENSE

This file is part of Newcomen.

Newcomen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the license, or (at your option) any later version.

Newcomen 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. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Newcomen. If not, see <http://www.gnu.org/licenses/>.

Newcomen