The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-TemplateFill-1.7
River stage zero No dependents
++
/ Text::TemplateFill

NAME

Text::TemplateFill - Formatting of reports with templates from files, use for I18N

SYNOPSIS

    use Text::TemplateFill;

    my $tmpl = new Text::TemplateFill;
    $tmpl->SetOpt('BaseDir' => "paras/$Country");
    $tmpl->SetOpt('ErrorFunction' => \&LogMsg, 'LineTerminator' => "\r\n");

    # Must read all the files before printing a paragraph
    $tmpl->ReadPara('Header', "head");
    $tmpl->ReadPara('FirstPage');
    $tmpl->ReadPara('Footer');
    $tmpl->ReadPara('Body');
    $tmpl->SetOpt('StartPageTag' => 'Header');

    my ($a, $b, $cn, $d) = ('a', 'letter b', 'ACME Inc', 4.92);
    $tmpl->BindVars('NameOfA' => \$a, 'B' => \$b, 'CustomerName' => \$cn, 'VarD' => \$d);

    print $tmpl->GeneratePara('FirstPage');  # Optional - since we want a specific 1st page

    print $tmpl->GeneratePara('Body');
    ... $a = ...; $b = ...
    print $tmpl->GeneratePara('Body');
    print $tmpl->CompletePage;

DESCRIPTION

This module provides template-from-file driven report writing in a way that is as easy to use as perl's in-built write verb. Major features are:

  • I18N formatting support, eg: decimal comma in France

  • I18N date support

  • Automatic page breaks

  • Variables are 'registered', not passed to each GeneratePara

  • Items of text (paragraphs) that are output are initially read from a text file.

  • Calculations may be defined as part of the paragraph definition in the file.

  • Optional use of your own Error reporting code

  • Variables can be formatted by the full power of printf

  • Automatic page/paragraph counting

  • Output is a string that may be then written anywhere

By putting the paragraph text in a file you separate style from substance (formatting from code), it is easy to have varients of the same reports, it is easy to generate the same report in different human languages.

BASIC CONCEPTS

A page is made up from a set of paragraphs; each paragraph is read from a file when the program starts; when a paragraph is generated the whole paragraph will be output on one page. A paragraph may be marked as a StartPage or an EndPage paragraph. The EndPage and StartPage paragraphs are automatically generated when needed. A group of paragraphs will be used in one template.

Paragraphs are given names called 'tags', these are used by the program when generating, and allow the paragraphs to refer to each other.

Program variables are bound by reference to names. This means that the generation function need not be called with a long list of values, as the variables change the new value is used when a paragraph is next generated. The bound variables must all be scalar variables.

PARAGRAPHS

Paragraphs are read in from files. The text that they contain is output verbatim with special sequences of the form ${ ... }, these sequences are one of three types:

  • Variable substitution with optional formatting information

  • Option setting, eg language (L10N information/specification)

  • Calculations, eg summing the values of a variable

  • Comments

SAMPLE PARAGRAPH FILE

    ${#} The is a start of page paragraph
    ${Opt StartPage } This lines says so
    ${Opt Locale en_GB.ISO8859-1} Language.Characterset, see: man 7 locale
    ${#} Now and PageNo are automatically generated/maintained names
    ${Calc NumItems := Washers + Screws }
    Date ${Now@time<%d %b %Y>}      Report for ${CustomerName%-20.20s}       Page ${PageNo%4.4d}

    ${#} end of paragraph file

PROGRAMMER USE

Create a new instance of a template, you should use one for each distinct output stream that you have; set any options, these are the same as the options that may be set with ${Opt ... }, see below; read in the paragraphs; bind references to variables with names; generate paragraphs of output; optionally end the last page.

OPTIONS

Options may be set by use of the SetOpt method, or by use of ${Opt Option Value} in a paragraph's template file. If the option is in a template file the string ${Opt must start the line, the entire line will then be discarded. If Value is not present the value 1 is used. To specify the empty value use ${Opt Option ''}.

Although all options can be set in the template file, it makes no sense to set some of them, eg ErrorFunction.

ErrorFunction

This is a function that accepts printf style arguments that will be called when an error is detected. If this is not specified the error will be sent to stderr.

A count of the number of errors is maintained in the method Errors, eg $tmpl->{Errors}.

Locale

If this is set to something like fr_FR.ISO8859-1 a switch will be made to the locale before the paragraph is generated, the (default) locale in effect before the use of GeneratePara will be reinstated after generation. Error messages will be printed in the default locale. The Locale setting is global to all paragraphs in a template, ie you only need to set it in one template file. You can use different Locales in different templates.

BaseDir

This specifies the first part of the path that is used when a template file is read. The default is ..

LineTerminator

This is the string that is output at the end of every line. The default is a single newline.

EndPageSeq

This is a string that is output to end a page if there is no EndPage paragraph. You may want to set this to a string containing the form-feed character. If this is not set empty lines are used.

PageLen

The length of the output page - number of lines.

StartPage

If a paragraph contains this it will not be preceeded by a Start-Of-Page paragraph when it is generated. You may have several paragraphs marked with this option, for instance you might want the first page to start differently from subsequent pages.

The Start-Of-Page paragraph will be automatically generated when it is needed. A Start-Of-Page paragraph is located before the first paragraph is output, if there is more than one candidate the choice is random, if you want a specific paragraph, you should set it in the program with SetOpt('StartPageTag' => tag_name) or ${Opt StartPageTag tag_name }.

StartPageTag

Specify the tag of the paragraph that will be the default Start-Of-Page paragraph. This is only needed where there is more than one paragraph with the StartPage flag. Set this to the empty string to suppress a default start page: ${Opt StartPageTag '' }.

EndPage

A paragraph with this flag will be allowed to end a page. Before a paragraph is generated a check is made that the paragraph and any End-Of-Page paragraph will fit on what remains of the page, if not the end of page is generated followed by a start of page.

As with Start-Of-Page an End-Of-Page paragraph page will be determined before the first paragraph is output, you may specify when there is a choice with SetOpt('EndPageTag' => tag_name). Empty lines will be used to ensure that the End-Of-Page paragraph ends on the last line of the page (see BlanksAfter), if there is no End-Of-Page paragraph, EndPageSeq will be used if it is set.

BlanksAfter

Blank lines to ensure that the page is filled are to be generated after the paragraph, the default is before. This is only noticed on an EndPage.

EndPageTag

Specify the tag of the paragraph that will be the default End-Of-Page paragraph. This is only needed where there is more than one paragraph with the EndPage flag. Set this to the empty string to suppress a default end page: ${Opt EndPageTag '' }.

PageLen

The number of lines on the page. A length of zero is taken to mean infinite.

COMMENTS

Comments are lines that start with ${#}. The rest of line is ignored, the entire line is removed from input.

VARIABLE SUBSTITUTIONS

The basic syntax for a variable substitution within a template is ${variablename}, where the name has been bound with BindVars. The value will be printed using the minimum width.

You may specify printf formatting after a %, eg ${Counter%10d}. You should refer to the perl documentation for full details of what you can specify. No check is made that the formatting code is appropriate for the variable type.

You can request special conversion, these are currently:

time

The syntax is ${VariableName@time<format>}. The variable value should be the number of seconds since the epoch. The format is a string that will be passed to strftime, if this is missing %c is used.

center

The variable is centered in the width specified, eg: ${Name@center<30>}.

AUTOMATIC VARIABLES

Several variables are maintained by the package, these may be used in a variable substitution. All of these names will start with an upper case letter.

PageNo

This is the current page number, it starts from 1 on the first page generated.

PageLineNo

This is the line number on the current page.

Now

This is the time at which the new method was invoked.

ParaOnPage

The number of times that the current paragraph has appeared on the current page. This might be used for item numbering.

ParaTotal

The total number of times that the current paragraph has appeared.

It is possible for a page to refer to the automatic variables of another tag, by the syntax Tag.Name, eg ${Item.ParaTotal}. The search path for a variable is: program variables, calculated variables, paragraph automatic variables; if a name is used more than once the last found is what is used.

CALCULATIONS

The syntax is ${Calc variable := expression }. Calculations are done with the module Math::Expression, see there for details. Calculations are performed before any lines of a paragraph are generated.

METHODS

SetOpt

This may be used to set one or more options. The arguments are a set of option name/option value pairs.

ReadPara

This reads a paragraph from a file. The two arguments are: the pargraph tag name, the file name. If the file name is not specified the tag name is used.

BindVars

This is used to provide references to the variables that will be substituted when paragraphs are generated. The arguments are pairs of names and references. A warning is generated if a name is reused. The names must be alphanumeric. The variables bound must be scalar variables - ie no arrays or hashes.

UnbindVars

This removes the binding to a variable. You may want to do this to rebind the name to a different variable.

GeneratePara

This outputs a paragraph, the argument is the tag of the paragraph that you wish to output. The current values of any variables will be substituted. The result is a string that may be printed. If a Locale has been set, the locale will be selected before the paragraph is generated and reset afterwards.

CompletePage

This is used to end the current page. If a paragraph tag is specified that tag is used, otherwise the default end of page paragraph is used. If a tag is specified and it is not the default end page tag, a check will be made to see if the specified paragraph will fit on the page, if not a standard endpage is first done.

Nothing will be printed if the current page has not been started - should only happen if there has been no output at all.

Reset

This resets all page and paragraph to zero. You would use this if you were to reuse a template to write to a new file.

AUTHOR

Alain D D Williams <addw@phcomp.co.uk>

Copyright and Version

Version "1.7", this is available as: $Text::TemplateFill::Version.

Copyright (c) 2003 Parliament Hill Computers Ltd/Alain D D Williams. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please see the module source for the full copyright.