[% USE autoformat(options) %]

[% autoformat(text, more_text, ..., options) %]

[% FILTER autoformat(options) %]
   a block of text
[% END %]

# 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) %]

The autoformat plugin 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.

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.

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.

Template::Plugin, Text::Autoformat