[%# # IMPORTANT NOTE # This documentation is generated automatically from source # templates. Any changes you make here may be lost. # # The 'docsrc' documentation source bundle is available for download # from http://www.template-toolkit.org/docs.html and contains all # the source templates, XML files, scripts, etc., from which the # documentation for the Template Toolkit is built. -%] [% META book = 'Modules' page = 'Plugin_Autoformat' %] [% WRAPPER toc; PROCESS tocitem title ="SYNOPSIS" subs = []; PROCESS tocitem title ="EXAMPLES" subs = []; PROCESS tocitem title ="DESCRIPTION" subs = []; PROCESS tocitem title ="AUTHORS" subs = []; PROCESS tocitem title ="VERSION" subs = []; PROCESS tocitem title ="COPYRIGHT" subs = []; PROCESS tocitem title ="SEE ALSO" subs = []; END %] [% WRAPPER section title="SYNOPSIS" -%]
    [% tt_start_tag %] USE autoformat(options) [% tt_end_tag %]
    [% tt_start_tag %] autoformat(text, more_text, ..., options) [% tt_end_tag %]
    [% tt_start_tag %] FILTER autoformat(options) [% tt_end_tag %]
       a block of text
    [% tt_start_tag %] END [% tt_end_tag %]
[%- END %] [% WRAPPER section title="EXAMPLES" -%]
    # define some text for the examples
    [% tt_start_tag %] text = BLOCK [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]
    # pass options to constructor...
    [% tt_start_tag %] USE autoformat(case => 'upper') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(text) [% tt_end_tag %]
    # and/or pass options to the autoformat subroutine itself
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] autoformat(text, case => 'upper') [% tt_end_tag %]
    
    # using the autoformat filter
    [% tt_start_tag %] USE autoformat(left => 10, right => 30) [% tt_end_tag %]
    [% tt_start_tag %] FILTER autoformat [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]
    # another filter example with configuration options
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] FILTER autoformat(left => 20) [% tt_end_tag %]
       Be not afeard.  The isle is full of noises, sounds and sweet 
       airs that give delight but hurt not.
    [% tt_start_tag %] END [% tt_end_tag %]
    
    # another FILTER example, defining a 'poetry' filter alias
    [% tt_start_tag %] USE autoformat [% tt_end_tag %]
    [% tt_start_tag %] text FILTER poetry = autoformat(left => 20, right => 40) [% tt_end_tag %]
    # reuse the 'poetry' filter alias
    [% tt_start_tag %] text FILTER poetry [% tt_end_tag %]
    # shorthand form ('|' is an alias for 'FILTER')
    [% tt_start_tag %] text | autoformat [% tt_end_tag %]
    # using forms
    [% tt_start_tag %] USE autoformat(form => '>>>>.<<<', numeric => 'AllPlaces') [% tt_end_tag %]
    [% tt_start_tag %] autoformat(10, 20.32, 11.35) [% tt_end_tag %]
[%- END %] [% WRAPPER section title="DESCRIPTION" -%]

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.

    [% tt_start_tag %] USE autoformat(right => 30) [% tt_end_tag %]

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

    [% tt_start_tag %] autoformat('The cat sat on the mat') [% tt_end_tag %]

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

    [% tt_start_tag %] autoformat(text, left => 20) [% tt_end_tag %]

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().

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

Additional configuration items relevant to forms can also be specified.

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

These can also be passed directly to the autoformat subroutine.

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

See [% ttlink('Text::Autoformat') -%] for further details.

[%- END %] [% WRAPPER section title="AUTHORS" -%]

Robert McArthur <mcarthur@dstc.edu.au> wrote the original plugin code, with some modifications and additions from Andy Wardley <abw@wardley.org>.

Damian Conway <damian@conway.org> wrote the Text::Autoformat module (in his copious spare time :-) which does all the clever stuff.

[%- END %] [% WRAPPER section title="VERSION" -%]

Template Toolkit version 2.19, released on 27 April 2007.

[%- END %] [% WRAPPER section title="COPYRIGHT" -%]

Copyright (C) 2000 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.

[%- END %] [% WRAPPER section title="SEE ALSO" -%]

[% ttlink('Template::Plugin', 'Template::Plugin') -%], [% ttlink('Text::Autoformat', 'Text::Autoformat') -%]

[%- END %]