Text::Bind - Bind Perl structures to text files
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;
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.
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.
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.
beginloop
The start of a repeatable loop. Text following, and up to the end-of-loop data site, is treated as a repeatable segment. See "Data Site Loops" for more information.
endloop
The end point of a repeatable loop. See "Data Site Loops" for more information.
The name is case insensitive.
=
Separator of name and 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.
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.
copyright.html
The following shows how the output of a program can be included:
##PL_file=/bin/ls -l |##
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:
The data site is replaced with the value of the scalar string.
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 ... });
Note, the return value of the function is used within in data site loops. See "Data Site Loops" for more information.
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.
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);
Note, the return value of the fill_site method is used within in data site loops. See "Data Site Loops" for more information.
Actually, a reference to an array. The values of the array are iterated over each time the data site is evaluated. The items in the array can be scalar strings, functions, filehandles, or objects, as defined above.
Binding an array to a site is most applicable for loops created by ##PL_beginloop##. See "Data Site Loops" for more information.
##PL_beginloop##
Occasionally, there is a need to have a block of text be repeatable. For example, lets take the following text data:
##PL_beginloop##Item = ##PL_site=listvalue## ##PL_endloop##
And the following bindings:
$text->bind_site('listvalue', [ 1, 2, 3, 4 ]);
Will generated the following output:
Item = 1 Item = 2 Item = 3 Item = 4
The text between the begin and end data sites is repeated until the evaluation of ALL data sites within the loop generate no more data.
Within a loop, types of data sites are treated as follows:
Will always be printed. However, a scalar string data site will always be treated to have no more data when determine end of loop condition.
Will always be invoked. However, the return value is check to determine if the last value has been generated for the data site. A return value of false tells Text::Bind that no more data exists for this site.
Text::Bind
WARNING: If the loop contains multiple data sites, it is possible that a function, or object method, will be called again if the other sites have not signified an end of data condition. Hence, the function/method should still return a false value for the duraction of the loop.
Will always be printed. However, a filehandle data site will always be treated to have no more data when determine end of loop condition. Also, since the EOF condition will be set after the first evaluation of the data site, subsequent evaluation will generate no data unless something resets the filehandle.
The items of the array are iterated over until end of the array is reached. Once the last item is reached, the end of data condition is set for the site.
A good example of loops is when populating an HTML table with data:
<table> ##PL_beginloop## <tr> <td>##PL_site=lastname##</td> <td>##PL_site=firstname##</td> <td>##PL_site=street##</td> <td>##PL_site=city##</td> <td>##PL_site=state##</td> <td>##PL_site=zip##</td> </tr> ##PL_endloop##
Data site loops cannot be nested.
Multiple data site loops cannot exist on a single line.
Earl Hood, earlhood@bigfoot.com
http://www.oac.uci.edu/indiv/ehood
To install Text::Bind, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Text::Bind
CPAN shell
perl -MCPAN -e shell install Text::Bind
For more information on module installation, please visit the detailed CPAN module installation guide.