5,576
edits
Changes
From SME Server
Jump to navigationJump to searchno edit summary
If you specify a value for the "BROKEN" attribute, it should be a reference to a function that "fill_in" can call instead of the default function.
If you specify a value for the "BROKEN" attribute, it should be a reference to a function that "fill_in" can call instead of the default function.
* "fill_in"
will pass a hash to the "broken" function. The hash will have at least these three members:
* "text"
The source code of the program fragment that failed
* "error"
The text of the error message ($@) generated by eval.The text has been modified to omit the trailing newline and to include the name of the template file (if there was one). The line number counts from the beginning of the template, not from
the beginning of the failed program fragment.
* "lineno"
The line number of the template at which the program fragment began.
There may also be an "arg" member. See "BROKEN_ARG", below
===== "BROKEN_ARG" =====
If you supply the "BROKEN_ARG" option to "fill_in", the value of the option is passed to the "BROKEN" function whenever it is called. The default "BROKEN" function ignores the "BROKEN_ARG", but you can write a custom "BROKEN" function that uses the "BROKEN_ARG" to get more information about what went wrong.
The "BROKEN" function could also use the "BROKEN_ARG" as a reference to store an error message or some other information that it wants to communicate back to the caller. For example:
$error = ’’;
$error = ’’;
}
}
If one of the program fragments in the template fails, it will call the "BROKEN" function, "my_broken", and pass it the "BROKEN_ARG", which is a reference to $error. "my_broken" can store an error message into $error this way. Then the function that called "fill_in" can see if "my_broken" has left an error message for it to find, and proceed accordingly.
===== "SAFE" =====
If you give "fill_in" a "SAFE" option, its value should be a safe compartment object from the "Safe" package. All evaluation of program fragments will be performed in this compartment. See Safe for full details about such compartments and how to restrict the operations that can be performed in them.
If you use the "PACKAGE" option with "SAFE", the package you specify will be placed into the safe compartment and evaluation will take place in that package as usual.
If not, "SAFE" operation is a little different from the default. Usually, if you don’t specify a package, evaluation of program fragments occurs in the package from which the template was invoked. But in "SAFE" mode the evaluation occurs inside the safe compartment and cannot affect the calling package. Normally, if you use "HASH" without "PACKAGE", the hash variables are imported into a private, one-use-only package. But if you use "HASH" and "SAFE" together without "PACKAGE", the hash variables will just be loaded into the root namespace of the "Safe" compartment.
===== "OUTPUT" =====
If your template is going to generate a lot of text that you are just going to print out again anyway, you can save memory by having "Text::Template" print out the text as it is generated instead of making it into a big string and returning the string. If you supply the "OUTPUT" option to "fill_in", the value should be a filehandle. The generated text will be printed to this filehandle as it is constructed. For example:
$template->fill_in(OUTPUT => \*STDOUT, ...);
$template->fill_in(OUTPUT => \*STDOUT, ...);
fills in the $template as usual, but the results are immediately printed to STDOUT. This may result in the output appearing more quickly than it would have otherwise.
If you use "OUTPUT", the return value from "fill_in" is still true on success and false on failure, but the complete text is not returned to the caller.
===== "PREPEND" =====
You can have some Perl code prepended automatically to the beginning of every program fragment. See ""PREPEND" feature and using "strict" in templates" below.
===== "DELIMITERS" =====
If this option is present, its value should be a reference to a list of two strings. The first string is the string that signals the beginning of each program fragment, and the second string is the string that signals the end of each program fragment. See "Alternative Delimiters", below.
If you specify "DELIMITERS" in the call to "fill_in", they override any delimiters you set when you created the template object with "new".
Convenience Functions
Convenience Functions
