=encoding utf8

=head1 NAME

HTML::FromMail::Format - base-class for message formatters

=head1 INHERITANCE

 HTML::FromMail::Format
   is a Mail::Reporter

 HTML::FromMail::Format is extended by
   HTML::FromMail::Format::Magic
   HTML::FromMail::Format::OODoc

=head1 SYNOPSIS

  my $fmt  = HTML::FromMail::Format::Magic->new(...);

  my $make = HTML::FromMail->new(
    templates => ...,
    formatter => 'Magic'
  #, formatter => 'HTML::FromMail::Format::Magic'
  #, formatter => $fmt
   );

=head1 DESCRIPTION

The formatter is implementing the template system: it formats the output.
This base class defines the methods which must be provided by any extension.

At the moment, the following template systems are available:

=over 4

=item * L<HTML::FromMail::Format::OODoc|HTML::FromMail::Format::OODoc>

Based on OODoc::Template, a simplified version of Template::Magic. It
has all the basic needs of a template system, but may get slow for large
template files.

=item * L<HTML::FromMail::Format::Magic|HTML::FromMail::Format::Magic>

Based on Template::Magic, created by Domizio Demichelis.  You will
have to install that optional module before you can use this formatter.
The default system is compatible with the previous formatter, so you
can easily upgrade.

The formatter has nice simplifications for the user, especially
when a lot own data must be included in the templates: so data with or
without relation to messages which is not provided by this distribution
(yet).

=back

=head1 METHODS

=over 4

=item $obj-E<gt>B<containerText>(ARGS)

Produces the text encapsulated between begin and end tag of this
template block.  If the tag is "stand alone", not a container, the
value of C<undef> is returned.  When the container is "empty", an
(optionally empty) string with white-spaces is returned.

=item $obj-E<gt>B<lookup>(TAG, ARGS)

Lookup the value for a certain C<TAG>.  This C<TAG> may, but also may not,
be derived from the template.  The value is lookup is the data produced
by the various producer methods, implemented in L<HTML::FromMail::Page|HTML::FromMail::Page>
extensions.  The values are administered by the various formatters,
because there meaning (and for instance their scoping) is formatter
dependent.  Values which are looked-up are often not simple strings.

=item $class-E<gt>B<new>(OPTIONS)

Z<>

=item $obj-E<gt>B<onFinalToken>(ARGS)

Returns whether the parser has more data in this particular part of
the template.

=item $obj-E<gt>B<processText>(TEXT, ARGS)

New C<TEXT> is supplied, which can be seen as part of the currently active
container.

=back

=head1 SEE ALSO

This module is part of HTML-FromMail version 3.00,
built on November 19, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2003-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

