NAME
Text::Bind - Bind Perl structures to text files
SYNOPSIS
use Text::Bind;
# Create a new object
$text = new Text::Bind; # or
$text = new Text::Bind "page.html" # or
$text = new Text::Bind \*IN;
# Bind a string value to a data site
$text->bind_site("astring", "Hello World!");
# Bind a function to a data site
$text->bind_site("form", \&generate_form);
# Bind a filehandle to a data site
$text->bind_site("filehandle", \*FILE);
# Bind an object to a data site
$some_object = new SomeClass;
$text->bind_site("object", $some_object);
# Read text
$text->read_text(\*OUT, "page.html"); # or
$text->read_text(\*OUT, \*IN); # or
$text->read_text(\*OUT); # or
$text->read_text;DESCRIPTION
Text::Bind allows you to bind Perl structures (strings, routines, filehandles, objects) to specific locations (called data sites) in text files.
The main purpose of this module is to support HTML templates for CGI programs. Therefore, HTML pages design can be kept separate from CGI code. However, the class is general enough to be used in other contexts than CGI application development. For example, it could be used to do form letters.
To create a new object, do one of the following:
$text = new Text::Bind;
$text = new Text::Bind $filename;
$text = new Text::Bind \*FILE;If no argument is given during object instantiation, then the input must be specified during the read_text method. Otherwise, a filename or a filehandle can be listed to specify the input source of the text data.
To have the data processed, use the read_text method in one of the following ways:
$text->read_text;
$text->read_text(\*OUT);
$text->read_text(\*OUT, $filename);
$text->read_text(\*OUT, \*FILE);When called with no arguments, input is read from what is specified during object instantiation, and output goes to STDOUT. If arguments are specified, the first argument is the output filehandle. If undefined, STDOUT is used. The second argument is the filename or the filehandle of the input. If not defined, input is read from what is specified during object instantiation.
The syntax for specifying data sites in the input and how to bind Perl structures to those sites is covered in the following sections.
Data Site Syntax
To define a data site, the syntax is as follows:
##PL_name=value##where the components mean the following:
##PL_-
Start of a data site.
- name
-
Type name of the site, possible values:
site-
Specifies a labeled data site where the data for the site determined thru the bind_site method.
file-
Specifies the name of file that defines the contents of the data site. Works in a similiar manner as HTTP server-side file include directive. If a trailing pipe is included in the value, then the value is treated as program to invoke, and the output of the program is used to fill the site.
The name is case insensitive.
=-
Separator of name and value.
- value
-
String value associated with name. Value is case sensitive.
##-
End of data site.
Data sites that do not have a binding during processing of text input are expanded to the empty string.
Duplicate sites can occur. The binding will be reexecuted each time the site occurs.
Example data sites
A data site for an HTML form:
<html>
<body>
##PL_site=inputform##
</body>
</html>The call to bind_site may look like:
$text->bind_site("inputform", \&create_form)The following shows how a file can bound to a site:
<html>
<body>
...
<hr>
##PL_file=copyright.html##
</body>
</html>The contents of copyright.html will replace the site definition.
The following shows how the output of a program can be included:
##PL_file=/bin/ls -l |##Data Site Bindings via bind_site Method
The bind_site method takes 2 arguments, the name of the site to bind to and a value to define the value of the site during the read_text method. Example:
$text->bind_site($name, $bind);The $name of the data site corresponds to the value of a ##PL_site=value## data site.
The bind value can be one of the following Perl data structures:
- scalar string
-
The data site is replaced with the value of the scalar string.
- function
-
A reference to a function. The function is invoked as follows:
&func($textobj, $outfh, $site_name);Where, $textobj is the Text::Bind object. $outfh is the output filehandle. The function uses $outfh to output the data that should go in the location of the data site. For example:
print $outfh "... data here ...";$site_name is the name of the site the function is being called for.
Since the Text::Bind object is passed to the function, the function can change bindings. Any changes will affect any data sites following the site being processed.
Additional arguments can be passed to the bind_site method when binding a function. For example:
$text->bind_site($site_name, \&func, $arg1, $arg2);A copy of those arguments will be passed as extra arguments when the function is invoked. Continuing with the previous example, the function would be called as follows:
&func($page_obj, $outfh, $site_name, $arg1, $arg2);Since the function may only exist for the purpose of filling the contents of a site, an anonymous function can be passed instead of a named function. For example:
$text->bind_site($site_name, sub { my($txtobj, $fh, $site) = @_; ## ... code here ... }); - filehandle
-
A reference to a filehandle (technically a reference to a glob of a filehandle). The filehandle is read until EOF and any data read goes in the location of the site.
- object
-
An object reference. Text::Bind will attempt to call the method fill_site of the object. Therefore, the object must have defined a method called fill_site, or a runtime error will occur.
The method is invoked with the same arguments as in a function binding:
$object->fill_site($page_obj, $outfh, $site_name);Any additional arguments passed during the bind_site call will be passed to the registered object's fill_site method like in function bindings:
$object->fill_site($page_obj, $outfh, $site_name, $arg1, $arg2, ..., $argN);
AUTHOR
Earl Hood, ehood@medusa.acs.uci.edu
http://www.oac.uci.edu/indiv/ehood