NAME
    Template::Plugin::Autoformat - Interface to Text::Autoformat module

SYNOPSIS
    [% USE Autoformat(options) %]
        
    [% Autoformat(text, more_text, ..., options) %]
        
    [% FILTER Autoformat(options) %]
       a block of text
    [% END %]

EXAMPLES
    # define some text for the examples
    [% text = BLOCK %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% END %]

    # pass options to constructor...
    [% USE Autoformat(case => 'upper') %]
    [% Autoformat(text) %]
        
    # and/or pass options to the Autoformat subroutine itself
    [% USE Autoformat %]
    [% Autoformat(text, case => 'upper') %]
        
    # using the Autoformat filter
    [% USE Autoformat(left => 10, right => 30) %]
    [% FILTER Autoformat %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% END %]

    # another filter example with configuration options
    [% USE Autoformat %]
    [% FILTER Autoformat(left => 20) %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% END %]

    # another FILTER example, defining a 'poetry' filter alias
    [% USE Autoformat %]
    [% text FILTER poetry = Autoformat(left => 20, right => 40) %]
        
    # reuse the 'poetry' filter alias
    [% text FILTER poetry %]

    # shorthand form ('|' is an alias for 'FILTER')
    [% text | Autoformat %]

    # using forms
    [% USE Autoformat(form => '>>>>.<<<', numeric => 'AllPlaces') %]
    [% Autoformat(10, 20.32, 11.35) %]

DESCRIPTION
    This Template Toolkit plugin module is an interface to Damian Conway's
    "Text::Autoformat" Perl module which provides advanced text wrapping and
    formatting.

    Configuration options may be passed to the plugin constructor via the
    "USE" directive.

        [% USE Autoformat(right => 30) %]

    The Autoformat subroutine can then be called, passing in text items
    which will be wrapped and formatted according to the current
    configuration.

        [% Autoformat('The cat sat on the mat') %]

    Additional configuration items can be passed to the Autoformat
    subroutine and will be merged with any existing configuration specified
    via the constructor.

        [% Autoformat(text, left => 20) %]

    Configuration options are passed directly to the "Text::Autoformat"
    plugin. At the time of writing, the basic configuration items are:

        left        left margin (default: 1)
        right       right margin (default 72)
        justify     justification as one of 'left', 'right', 'full'
                    or 'centre' (default: left)
        case        case conversion as one of 'lower', 'upper',
                    'sentence', 'title', or 'highlight' (default: none)
        squeeze     squeeze whitespace (default: enabled)

    The plugin also accepts a "form" item which can be used to define a
    format string. When a form is defined, the plugin will call the
    underlying "form()" subroutine in preference to "Autoformat()".

        [% USE Autoformat(form => '>>>>.<<') %]
        [% Autoformat(123.45, 666, 3.14) %]

    Additional configuration items relevant to forms can also be specified.

        [% USE Autoformat(form => '>>>>.<<', numeric => 'AllPlaces') %]
        [% Autoformat(123.45, 666, 3.14) %]

    These can also be passed directly to the Autoformat subroutine.

        [% USE Autoformat %]
        [% Autoformat( 123.45, 666, 3.14,
                       form    => '>>>>.<<', 
                       numeric => 'AllPlaces' )
        %]

    See Text::Autoformat for further details.

AUTHORS
    Robert McArthur wrote the original plugin code, with some modifications
    and additions from Andy Wardley.

    Damian Conway wrote the Text::Autoformat module which does all the
    clever stuff.

    The module was moved out of the Template Toolkit core and into a
    separate distribution in December 2008. Peter Karman is the current
    maintainer.

COPYRIGHT
    Copyright (C) 2000-2007 Robert McArthur & Andy Wardley. All Rights
    Reserved.

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

SEE ALSO
    Template, Template::Plugin, Text::Autoformat