Ken Williams > Text-FillIn-0.05 > Text::FillIn

Download:
Text-FillIn-0.05.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.05   Source  

NAME ^

Text::FillIn.pm - a class implementing a fill-in template

SYNOPSIS ^

 use Text::FillIn;
 
 # Set the functions to do the filling-in:
 Text::FillIn->hook('$', sub { return ${$_[0]} });  # Hard reference
 Text::FillIn->hook('&', "main::run_function");     # Symbolic reference
 sub run_function { return &{$_[0]} }
 
 $template = new Text::FillIn('some text with [[$vars]] and [[&routines]]');
 $filled_in = $template->interpret();  # Returns filled-in template
 print $filled_in;
 $template->interpret_and_print();  # Prints template to currently 
                                    # selected filehandle
 
 # Or
 $template = new Text::FillIn();
 $template->set_text('the text is [[ $[[$var1]][[$var2]] ]]');
 $TVars{'var1'} = 'two_';
 $TVars{'var2'} = 'parter';
 $TVars{'two_parter'} = 'interpreted';
 $template->interpret_and_print();  # Prints "the text is interpreted"
 
 # Or
 $template = new Text::FillIn();
 $template->get_file('/etc/template_dir/my_template');  # Fetches a file
 
 # Or
 $template = new Text::FillIn();
 $template->path('.', '/etc/template_dir');  # Where to find templates
 $template->get_file('my_template'); # Gets ./my_template or 
                                     # /etc/template_dir/my_template

DESCRIPTION ^

This module provides a class for doing fill-in templates. These templates may be used as web pages with dynamic content, e-mail messages with fill-in fields, or whatever other uses you might think of. Text::FillIn provides handy methods for fetching files from the disk, printing a template while interpreting it (also called streaming), and nested fill-in sections (i.e. expressions like [[ $th[[$thing2]]ing1 ]] are legal).

Note that the version number here is 0.04 - that means that the interface may change a bit. In fact, it's already changed some with respect to 0.02 (see the CHANGES file). In particular, the $LEFT_DELIM, $RIGHT_DELIM, %HOOK, and @TEMPLATE_PATH variables are gone, replaced by a default/instance variable system.

I might also change the default hooks or something. Please read the CHANGES file before upgrading to find out whether I've changed anything you use.

In this documentation, I generally use "template" to mean "an object of class Text::FillIn".

Defining the structure of templates

METHODS ^

The following methods all get and/or set certain attributes of the template. They can all be called as instance methods, a la $template->Ldelim(), or as static methods, a la Text::FillIn->Ldelim(). Using an instance method only changes the given template, it does not affect the properties of any other template. Using a static method will change the default behavior of all templates created in the future.

I think I need to reserve the right to change what happens when you create a template $t, then change the default behavior of all templates, then call $t->interpret() -- should it use the new defaults or the old defaults? Currently it uses the old defaults, but that might change.

COMMON MISTAKES ^

If you want to use nested fill-ins on your template, make sure things get printed in the order you think they'll be printed. If you have something like this: [[$var_number_[[&get_number]]]], and your &get_number prints a number, you won't get the results you probably want. Text::FillIn will print your number, then try to interpret [[$var_number_]], which probably won't work.

The solution is to make &get_number return its number rather than print it. Then Text::FillIn will turn [[$var_number_[[&get_number]]]] into [[$var_number_5]], and then print the value of $var_number_5. That's probably what you wanted.

TO DO ^

The deprecated methods get_text(), set_text(), get_property(), and set_property() will be removed in version 0.06 and greater. Use text() and property() instead.

By slick use of local() variables, it would be possible to have Text::FillIn keep track of when it's doing nested tags and when it's not, allowing the user to nest tags using arbitrary depth and not have to worry about the above "common mistake." This would let hook functions be oblivious to whether they're supposed to print their results or return them, since Text::FillIn would keep track of it all. This will take some doing on my part, but it's not insurmountable. It would probably involve evaluating the tags from the outside in, rather than the inside out.

BUGS ^

The interpreting engine can be fooled by certain backslashing sequences like \\[[$var]], which looks to it like the [[ is backslashed. I think I know how to fix this, but I need to think about it a little.

AUTHOR ^

Ken Williams (ken@forum.swarthmore.edu)

Copyright (c) 1998 Swarthmore College. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: