Downloaded and bundled Perl modules
-----------------------------------
-Text::Template 1.46 was downloaded from
-http://search.cpan.org/CPAN/authors/id/M/MJ/MJD/Text-Template-1.46.tar.gz
+Text::Template 1.56 was downloaded from
+https://cpan.metacpan.org/authors/id/M/MS/MSCHOUT/Text-Template-1.56.tar.gz
-Text-Template-1.46/lib
+Text-Template-1.56/lib
+++ /dev/null
-
-
-
-
- The "Artistic License"
-
- Preamble
-
-The intent of this document is to state the conditions under which a
-Package may be copied, such that the Copyright Holder maintains some
-semblance of artistic control over the development of the package,
-while giving the users of the package the right to use and distribute
-the Package in a more-or-less customary fashion, plus the right to make
-reasonable modifications.
-
-Definitions:
-
- "Package" refers to the collection of files distributed by the
- Copyright Holder, and derivatives of that collection of files
- created through textual modification.
-
- "Standard Version" refers to such a Package if it has not been
- modified, or has been modified in accordance with the wishes
- of the Copyright Holder as specified below.
-
- "Copyright Holder" is whoever is named in the copyright or
- copyrights for the package.
-
- "You" is you, if you're thinking about copying or distributing
- this Package.
-
- "Reasonable copying fee" is whatever you can justify on the
- basis of media cost, duplication charges, time of people involved,
- and so on. (You will not be required to justify it to the
- Copyright Holder, but only to the computing community at large
- as a market that must bear the fee.)
-
- "Freely Available" means that no fee is charged for the item
- itself, though there may be fees involved in handling the item.
- It also means that recipients of the item may redistribute it
- under the same conditions they received it.
-
-1. You may make and give away verbatim copies of the source form of the
-Standard Version of this Package without restriction, provided that you
-duplicate all of the original copyright notices and associated disclaimers.
-
-2. You may apply bug fixes, portability fixes and other modifications
-derived from the Public Domain or from the Copyright Holder. A Package
-modified in such a way shall still be considered the Standard Version.
-
-3. You may otherwise modify your copy of this Package in any way, provided
-that you insert a prominent notice in each changed file stating how and
-when you changed that file, and provided that you do at least ONE of the
-following:
-
- a) place your modifications in the Public Domain or otherwise make them
- Freely Available, such as by posting said modifications to Usenet or
- an equivalent medium, or placing the modifications on a major archive
- site such as uunet.uu.net, or by allowing the Copyright Holder to include
- your modifications in the Standard Version of the Package.
-
- b) use the modified Package only within your corporation or organization.
-
- c) rename any non-standard executables so the names do not conflict
- with standard executables, which must also be provided, and provide
- a separate manual page for each non-standard executable that clearly
- documents how it differs from the Standard Version.
-
- d) make other distribution arrangements with the Copyright Holder.
-
-4. You may distribute the programs of this Package in object code or
-executable form, provided that you do at least ONE of the following:
-
- a) distribute a Standard Version of the executables and library files,
- together with instructions (in the manual page or equivalent) on where
- to get the Standard Version.
-
- b) accompany the distribution with the machine-readable source of
- the Package with your modifications.
-
- c) give non-standard executables non-standard names, and clearly
- document the differences in manual pages (or equivalent), together
- with instructions on where to get the Standard Version.
-
- d) make other distribution arrangements with the Copyright Holder.
-
-5. You may charge a reasonable copying fee for any distribution of this
-Package. You may charge any fee you choose for support of this
-Package. You may not charge a fee for this Package itself. However,
-you may distribute this Package in aggregate with other (possibly
-commercial) programs as part of a larger (possibly commercial) software
-distribution provided that you do not advertise this Package as a
-product of your own. You may embed this Package's interpreter within
-an executable of yours (by linking); this shall be construed as a mere
-form of aggregation, provided that the complete Standard Version of the
-interpreter is so embedded.
-
-6. The scripts and library files supplied as input to or produced as
-output from the programs of this Package do not automatically fall
-under the copyright of this Package, but belong to whoever generated
-them, and may be sold commercially, and may be aggregated with this
-Package. If such scripts or library files are aggregated with this
-Package via the so-called "undump" or "unexec" methods of producing a
-binary executable image, then distribution of such an image shall
-neither be construed as a distribution of this Package nor shall it
-fall under the restrictions of Paragraphs 3 and 4, provided that you do
-not represent such an executable image as a Standard Version of this
-Package.
-
-7. C subroutines (or comparably compiled subroutines in other
-languages) supplied by you and linked into this Package in order to
-emulate subroutines and variables of the language defined by this
-Package shall not be considered part of this Package, but are the
-equivalent of input as in Paragraph 6, provided these subroutines do
-not change the language in any way that would cause it to fail the
-regression tests for the language.
-
-8. Aggregation of this Package with a commercial distribution is always
-permitted provided that the use of this Package is embedded; that is,
-when no overt attempt is made to make this Package's interfaces visible
-to the end user of the commercial distribution. Such use shall not be
-construed as a distribution of this Package.
-
-9. The name of the Copyright Holder may not be used to endorse or promote
-products derived from this software without specific prior written permission.
-
-10. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
-IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
-WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-
- The End
+++ /dev/null
- GNU GENERAL PUBLIC LICENSE
- Version 2, June 1991
-
- Copyright (C) 1989, 1991 Free Software Foundation, Inc.
- 59 Temple Place - Suite 330, Boston, MA
- 02111-1307, USA.
- Everyone is permitted to copy and distribute verbatim copies
- of this license document, but changing it is not allowed.
-
- Preamble
-
- The licenses for most software are designed to take away your
-freedom to share and change it. By contrast, the GNU General Public
-License is intended to guarantee your freedom to share and change free
-software--to make sure the software is free for all its users. This
-General Public License applies to most of the Free Software
-Foundation's software and to any other program whose authors commit to
-using it. (Some other Free Software Foundation software is covered by
-the GNU Library General Public License instead.) You can apply it to
-your programs, too.
-
- When we speak of free software, we are referring to freedom, not
-price. Our General Public Licenses are designed to make sure that you
-have the freedom to distribute copies of free software (and charge for
-this service if you wish), that you receive source code or can get it
-if you want it, that you can change the software or use pieces of it
-in new free programs; and that you know you can do these things.
-
- To protect your rights, we need to make restrictions that forbid
-anyone to deny you these rights or to ask you to surrender the rights.
-These restrictions translate to certain responsibilities for you if you
-distribute copies of the software, or if you modify it.
-
- For example, if you distribute copies of such a program, whether
-gratis or for a fee, you must give the recipients all the rights that
-you have. You must make sure that they, too, receive or can get the
-source code. And you must show them these terms so they know their
-rights.
-
- We protect your rights with two steps: (1) copyright the software, and
-(2) offer you this license which gives you legal permission to copy,
-distribute and/or modify the software.
-
- Also, for each author's protection and ours, we want to make certain
-that everyone understands that there is no warranty for this free
-software. If the software is modified by someone else and passed on, we
-want its recipients to know that what they have is not the original, so
-that any problems introduced by others will not reflect on the original
-authors' reputations.
-
- Finally, any free program is threatened constantly by software
-patents. We wish to avoid the danger that redistributors of a free
-program will individually obtain patent licenses, in effect making the
-program proprietary. To prevent this, we have made it clear that any
-patent must be licensed for everyone's free use or not licensed at all.
-
- The precise terms and conditions for copying, distribution and
-modification follow.
-\f
- GNU GENERAL PUBLIC LICENSE
- TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
- 0. This License applies to any program or other work which contains
-a notice placed by the copyright holder saying it may be distributed
-under the terms of this General Public License. The "Program", below,
-refers to any such program or work, and a "work based on the Program"
-means either the Program or any derivative work under copyright law:
-that is to say, a work containing the Program or a portion of it,
-either verbatim or with modifications and/or translated into another
-language. (Hereinafter, translation is included without limitation in
-the term "modification".) Each licensee is addressed as "you".
-
-Activities other than copying, distribution and modification are not
-covered by this License; they are outside its scope. The act of
-running the Program is not restricted, and the output from the Program
-is covered only if its contents constitute a work based on the
-Program (independent of having been made by running the Program).
-Whether that is true depends on what the Program does.
-
- 1. You may copy and distribute verbatim copies of the Program's
-source code as you receive it, in any medium, provided that you
-conspicuously and appropriately publish on each copy an appropriate
-copyright notice and disclaimer of warranty; keep intact all the
-notices that refer to this License and to the absence of any warranty;
-and give any other recipients of the Program a copy of this License
-along with the Program.
-
-You may charge a fee for the physical act of transferring a copy, and
-you may at your option offer warranty protection in exchange for a fee.
-
- 2. You may modify your copy or copies of the Program or any portion
-of it, thus forming a work based on the Program, and copy and
-distribute such modifications or work under the terms of Section 1
-above, provided that you also meet all of these conditions:
-
- a) You must cause the modified files to carry prominent notices
- stating that you changed the files and the date of any change.
-
- b) You must cause any work that you distribute or publish, that in
- whole or in part contains or is derived from the Program or any
- part thereof, to be licensed as a whole at no charge to all third
- parties under the terms of this License.
-
- c) If the modified program normally reads commands interactively
- when run, you must cause it, when started running for such
- interactive use in the most ordinary way, to print or display an
- announcement including an appropriate copyright notice and a
- notice that there is no warranty (or else, saying that you provide
- a warranty) and that users may redistribute the program under
- these conditions, and telling the user how to view a copy of this
- License. (Exception: if the Program itself is interactive but
- does not normally print such an announcement, your work based on
- the Program is not required to print an announcement.)
-\f
-These requirements apply to the modified work as a whole. If
-identifiable sections of that work are not derived from the Program,
-and can be reasonably considered independent and separate works in
-themselves, then this License, and its terms, do not apply to those
-sections when you distribute them as separate works. But when you
-distribute the same sections as part of a whole which is a work based
-on the Program, the distribution of the whole must be on the terms of
-this License, whose permissions for other licensees extend to the
-entire whole, and thus to each and every part regardless of who wrote it.
-
-Thus, it is not the intent of this section to claim rights or contest
-your rights to work written entirely by you; rather, the intent is to
-exercise the right to control the distribution of derivative or
-collective works based on the Program.
-
-In addition, mere aggregation of another work not based on the Program
-with the Program (or with a work based on the Program) on a volume of
-a storage or distribution medium does not bring the other work under
-the scope of this License.
-
- 3. You may copy and distribute the Program (or a work based on it,
-under Section 2) in object code or executable form under the terms of
-Sections 1 and 2 above provided that you also do one of the following:
-
- a) Accompany it with the complete corresponding machine-readable
- source code, which must be distributed under the terms of Sections
- 1 and 2 above on a medium customarily used for software interchange; or,
-
- b) Accompany it with a written offer, valid for at least three
- years, to give any third party, for a charge no more than your
- cost of physically performing source distribution, a complete
- machine-readable copy of the corresponding source code, to be
- distributed under the terms of Sections 1 and 2 above on a medium
- customarily used for software interchange; or,
-
- c) Accompany it with the information you received as to the offer
- to distribute corresponding source code. (This alternative is
- allowed only for noncommercial distribution and only if you
- received the program in object code or executable form with such
- an offer, in accord with Subsection b above.)
-
-The source code for a work means the preferred form of the work for
-making modifications to it. For an executable work, complete source
-code means all the source code for all modules it contains, plus any
-associated interface definition files, plus the scripts used to
-control compilation and installation of the executable. However, as a
-special exception, the source code distributed need not include
-anything that is normally distributed (in either source or binary
-form) with the major components (compiler, kernel, and so on) of the
-operating system on which the executable runs, unless that component
-itself accompanies the executable.
-
-If distribution of executable or object code is made by offering
-access to copy from a designated place, then offering equivalent
-access to copy the source code from the same place counts as
-distribution of the source code, even though third parties are not
-compelled to copy the source along with the object code.
-\f
- 4. You may not copy, modify, sublicense, or distribute the Program
-except as expressly provided under this License. Any attempt
-otherwise to copy, modify, sublicense or distribute the Program is
-void, and will automatically terminate your rights under this License.
-However, parties who have received copies, or rights, from you under
-this License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- 5. You are not required to accept this License, since you have not
-signed it. However, nothing else grants you permission to modify or
-distribute the Program or its derivative works. These actions are
-prohibited by law if you do not accept this License. Therefore, by
-modifying or distributing the Program (or any work based on the
-Program), you indicate your acceptance of this License to do so, and
-all its terms and conditions for copying, distributing or modifying
-the Program or works based on it.
-
- 6. Each time you redistribute the Program (or any work based on the
-Program), the recipient automatically receives a license from the
-original licensor to copy, distribute or modify the Program subject to
-these terms and conditions. You may not impose any further
-restrictions on the recipients' exercise of the rights granted herein.
-You are not responsible for enforcing compliance by third parties to
-this License.
-
- 7. If, as a consequence of a court judgment or allegation of patent
-infringement or for any other reason (not limited to patent issues),
-conditions are imposed on you (whether by court order, agreement or
-otherwise) that contradict the conditions of this License, they do not
-excuse you from the conditions of this License. If you cannot
-distribute so as to satisfy simultaneously your obligations under this
-License and any other pertinent obligations, then as a consequence you
-may not distribute the Program at all. For example, if a patent
-license would not permit royalty-free redistribution of the Program by
-all those who receive copies directly or indirectly through you, then
-the only way you could satisfy both it and this License would be to
-refrain entirely from distribution of the Program.
-
-If any portion of this section is held invalid or unenforceable under
-any particular circumstance, the balance of the section is intended to
-apply and the section as a whole is intended to apply in other
-circumstances.
-
-It is not the purpose of this section to induce you to infringe any
-patents or other property right claims or to contest validity of any
-such claims; this section has the sole purpose of protecting the
-integrity of the free software distribution system, which is
-implemented by public license practices. Many people have made
-generous contributions to the wide range of software distributed
-through that system in reliance on consistent application of that
-system; it is up to the author/donor to decide if he or she is willing
-to distribute software through any other system and a licensee cannot
-impose that choice.
-
-This section is intended to make thoroughly clear what is believed to
-be a consequence of the rest of this License.
-\f
- 8. If the distribution and/or use of the Program is restricted in
-certain countries either by patents or by copyrighted interfaces, the
-original copyright holder who places the Program under this License
-may add an explicit geographical distribution limitation excluding
-those countries, so that distribution is permitted only in or among
-countries not thus excluded. In such case, this License incorporates
-the limitation as if written in the body of this License.
-
- 9. The Free Software Foundation may publish revised and/or new versions
-of the General Public License from time to time. Such new versions will
-be similar in spirit to the present version, but may differ in detail to
-address new problems or concerns.
-
-Each version is given a distinguishing version number. If the Program
-specifies a version number of this License which applies to it and "any
-later version", you have the option of following the terms and conditions
-either of that version or of any later version published by the Free
-Software Foundation. If the Program does not specify a version number of
-this License, you may choose any version ever published by the Free Software
-Foundation.
-
- 10. If you wish to incorporate parts of the Program into other free
-programs whose distribution conditions are different, write to the author
-to ask for permission. For software which is copyrighted by the Free
-Software Foundation, write to the Free Software Foundation; we sometimes
-make exceptions for this. Our decision will be guided by the two goals
-of preserving the free status of all derivatives of our free software and
-of promoting the sharing and reuse of software generally.
-
- NO WARRANTY
-
- 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
-FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
-OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
-PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
-OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
-TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
-PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
-REPAIR OR CORRECTION.
-
- 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
-WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
-REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
-INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
-OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
-TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
-YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
-PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
-POSSIBILITY OF SUCH DAMAGES.
-
- END OF TERMS AND CONDITIONS
-\f
- Appendix: How to Apply These Terms to Your New Programs
-
- If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
- To do so, attach the following notices to the program. It is safest
-to attach them to the start of each source file to most effectively
-convey the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
- <one line to give the program's name and a brief idea of what it does.>
- Copyright (C) 19yy <name of author>
-
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-Also add information on how to contact you by electronic and paper mail.
-
-If the program is interactive, make it output a short notice like this
-when it starts in an interactive mode:
-
- Gnomovision version 69, Copyright (C) 19yy name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
- This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License. Of course, the commands you use may
-be called something other than `show w' and `show c'; they could even be
-mouse-clicks or menu items--whatever suits your program.
-
-You should also get your employer (if you work as a programmer) or your
-school, if any, to sign a "copyright disclaimer" for the program, if
-necessary. Here is a sample; alter the names:
-
- Yoyodyne, Inc., hereby disclaims all copyright interest in the program
- `Gnomovision' (which makes passes at compilers) written by James Hacker.
-
- <signature of Ty Coon>, 1 April 1989
- Ty Coon, President of Vice
-
-This General Public License does not permit incorporating your program into
-proprietary programs. If your program is a subroutine library, you may
-consider it more useful to permit linking proprietary applications with the
-library. If this is what you want to do, use the GNU Library General
-Public License instead of this License.
+++ /dev/null
-
-To install:
-
- perl Makefile.PL
-
-to construct the Makefile, then
-
- make test
-
-to test the package. If it fails any tests, please send me the output
-of `make test' and `perl -V'. I'll tell you whether it is safe to go
-ahead, or I'll provide a fix.
-
-If it passes the tests, use
-
- make install
-
-to install it.
-
-Detailed documentation is at the bottom of the lib/Text/Template.pm
-file. You may be able to view it with the following command:
-
- perldoc Text::Template
-
-Or:
-
- perldoc lib/Text/Template.pm
-
-If you have problems, send me mail:
-
-mjd-perl-template+@plover.com
+++ /dev/null
-MANIFEST
-COPYING
-Artistic
-Makefile.PL
-INSTALL
-README
-lib/Text/Template.pm
-lib/Text/Template/Preprocess.pm
-t/00-version.t
-t/01-basic.t
-t/02-hash.t
-t/03-out.t
-t/04-safe.t
-t/05-safe2.t
-t/06-ofh.t
-t/07-safe3.t
-t/08-exported.t
-t/09-error.t
-t/10-delimiters.t
-t/11-prepend.t
-t/12-preprocess.t
-t/13-taint.t
-t/14-broken.t
-META.yml Module meta-data (added by MakeMaker)
-META.json Module JSON meta-data (added by MakeMaker)
+++ /dev/null
-{
- "abstract" : "unknown",
- "author" : [
- "unknown"
- ],
- "dynamic_config" : 1,
- "generated_by" : "ExtUtils::MakeMaker version 6.62, CPAN::Meta::Converter version 2.120630",
- "license" : [
- "unknown"
- ],
- "meta-spec" : {
- "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
- "version" : "2"
- },
- "name" : "Text-Template",
- "no_index" : {
- "directory" : [
- "t",
- "inc"
- ]
- },
- "prereqs" : {
- "build" : {
- "requires" : {
- "ExtUtils::MakeMaker" : "0"
- }
- },
- "configure" : {
- "requires" : {
- "ExtUtils::MakeMaker" : "0"
- }
- },
- "runtime" : {
- "requires" : {}
- }
- },
- "release_status" : "stable",
- "version" : "1.46"
-}
+++ /dev/null
----
-abstract: unknown
-author:
- - unknown
-build_requires:
- ExtUtils::MakeMaker: 0
-configure_requires:
- ExtUtils::MakeMaker: 0
-dynamic_config: 1
-generated_by: 'ExtUtils::MakeMaker version 6.62, CPAN::Meta::Converter version 2.120630'
-license: unknown
-meta-spec:
- url: http://module-build.sourceforge.net/META-spec-v1.4.html
- version: 1.4
-name: Text-Template
-no_index:
- directory:
- - t
- - inc
-requires: {}
-version: 1.46
+++ /dev/null
-use ExtUtils::MakeMaker;
-WriteMakefile(
- NAME => 'Text::Template',
- VERSION_FROM => 'lib/Text/Template.pm',
-# 'linkext' => {LINKTYPE => ''},
- 'dist' => {COMPRESS => 'gzip', SUFFIX => 'gz'},
-);
+++ /dev/null
-
-Text::Template v1.46
-
-This is a library for generating form letters, building HTML pages, or
-filling in templates generally. A `template' is a piece of text that
-has little Perl programs embedded in it here and there. When you
-`fill in' a template, you evaluate the little programs and replace
-them with their values.
-
-Here's an example of a template:
-
- Dear {$title} {$lastname},
-
- It has come to our attention that you are delinquent in your
- {$monthname[$last_paid_month]} payment. Please remit
- ${sprintf("%.2f", $amount)} immediately, or your patellae may
- be needlessly endangered.
-
- Love,
-
- Mark "{nickname(rand 20)}" Dominus
-
-
-The result of filling in this template is a string, which might look
-something like this:
-
- Dear Mr. Gates,
-
- It has come to our attention that you are delinquent in your
- February payment. Please remit
- $392.12 immediately, or your patellae may
- be needlessly endangered.
-
-
- Love,
-
- Mark "Vizopteryx" Dominus
-
-You can store a template in a file outside your program. People can
-modify the template without modifying the program. You can separate
-the formatting details from the main code, and put the formatting
-parts of the program into the template. That prevents code bloat and
-encourages functional separation.
-
-You can fill in the template in a `Safe' compartment. This means that
-if you don't trust the person who wrote the code in the template, you
-won't have to worry that they are tampering with your program when you
-execute it.
-
-----------------------------------------------------------------
-
-Text::Template was originally released some time in late 1995 or early
-1996. After three years of study and investigation, I rewrote it from
-scratch in January 1999. The new version, 1.0, was much faster,
-delivered better functionality and was almost 100% backward-compatible
-with the previous beta versions.
-
-I have added a number of useful features and conveniences since the
-1.0 release, while still retaining backward compatibility. With one
-merely cosmetic change, the current version of Text::Template passes
-the test suite that the old beta versions passed.
-
-Questions or comments should be addressed to
-mjd-perl-template+@plover.com. This address goes directly to me, and
-not to anyone else; it is not a mailing list address.
-
-To receive occasional announcements of new versions of T::T, send an
-empty note to mjd-perl-template-request@plover.com. This mailing list
-is not for discussion; it is for announcements only. Therefore, there
-is no address for sending messages to the list.
-
-You can get the most recent version of Text::Template, news, comments,
-and other collateral information from
-<URL:http://www.plover.com/~mjd/perl/Template/>.
-
-----------------------------------------------------------------
-
-What's new in v1.46 since v1.44:
-
- Thanks to Rik Signes, there is a new
- Text::Template->append_text_to_output method, which
- Text::Template always uses whenever it wants to emit output.
- You can subclass this to get control over the output, for
- example for postprocessing.
-
- A spurious warning is no longer emitted when the TYPE
- parameter to ->new is omitted.
-
-----------------------------------------------------------------
-What's new in v1.44 since v1.43:
-
-This is a maintentance release. There are no feature changes.
-
- _scrubpkg, which was responsible for eptying out temporary
- packages after the module had done with them, wasn't always
- working; the result was memory-leaks in long-running
- applications. This should be fixed now, and there is a test
- in the test suite for it.
-
- Minor changes to the test suite to prevent spurious errors.
-
- Minor documentation changes.
-
-----------------------------------------------------------------
-What's new in v1.43 since v1.42:
-
- The ->new method now fails immediately and sets
- $Text::Template::ERROR if the file that is named by a filename
- argument does not exist or cannot be opened for some other
- reason. Formerly, the constructor would succeed and the
- ->fill_in call would fail.
-
-----------------------------------------------------------------
-
-What's new in v1.42 since v1.41:
-
-This is a maintentance release. There are no feature changes.
-
- Fixed a bug relating to use of UNTAINT under perl 5.005_03 and
- possibly other versions.
-
- Taint-related tests are now more comprehensive.
-----------------------------------------------------------------
-
-What's new in v1.41 since v1.40:
-
-This is a maintentance release. There are no feature changes.
-
- Tests now work correctly on Windows systems and possibly on
- other non-unix systems.
-
-----------------------------------------------------------------
-
-What's new in v1.40 since v1.31:
-
- New UNTAINT option tells the module that it is safe to 'eval'
- code even though it has come from a file or filehandle.
-
- Code added to prevent memory leaks when filling many
- templates. Thanks to Itamar Almeida de Carvalho.
-
- Bug fix: $OUT was not correctly initialized when used in
- conjunction with SAFE.
-
- You may now use a glob ref when passing a filehandle to the
- ->new funcion. Formerly, a glob was reuqired.
-
- New subclass: Text::Template::Preprocess. Just like
- Text::Template, but you may supply a PREPROCESS option in the
- constructor or the fill_in call; this is a function which
- receives each code fragment prior to evaluation, and which may
- modify and return the fragment; the modified fragment is what
- is evaluated.
-
- Error messages passed to BROKEN subroutines will now report
- the correct line number of the template at which the error
- occurred:
-
- Illegal division by zero at template line 37.
-
- If the template comes from a file, the filename will be
- reported as well:
-
- Illegal division by zero at catalog.tmpl line 37.
-
-
- INCOMPATIBLE CHANGE:
-
- The format of the default error message has changed. It used
- to look like:
-
- Program fragment at line 30 delivered error ``Illegal division by zero''
-
- It now looks like:
-
- Program fragment delivered error ``Illegal division by zero at catalog.tmpl line 37''
-
- Note that the default message used to report the line number
- at which the program fragment began; it now reports the line
- number at which the error actually occurred.
-
-----------------------------------------------------------------
-What's new in v1.31 since v1.23:
-
- Just bug fixes---fill_in_string was failing. Thanks to
- Donald L. Greer Jr. for the test case.
-
-----------------------------------------------------------------
-What's new in v1.23 since v1.22:
-
- Small bug fix: DELIMITER and other arguments were being
- ignored in calls to fill_in_file and fill_this_in. (Thanks to
- Jonathan Roy for reporting this.)
-
-----------------------------------------------------------------
-What's new in v1.22 since v1.20:
-
- You can now specify that certain Perl statements be prepended
- to the beginning of every program fragment in a template,
- either per template, or for all templates, or for the duration
- of only one call to fill_in. This is useful, for example, if
- you want to enable `strict' checks in your templates but you
- don't want to manually add `use strict' to the front of every
- program fragment everywhere.
-
-----------------------------------------------------------------
-What's new in v1.20 since v1.12:
-
- You can now specify that the program fragment delimiters are
- strings other than { and }. This has three interesting
- effects: First, it changes the delimiter strings. Second, it
- disables the special meaning of \, so you have to be really,
- really sure that the delimiters will not appear in your
- templates. And third, because of the simplifications
- introduced by the elimination of \ processing, template
- parsing is 20-25% faster.
-
- See the manual section on `Alternative Delimiters'.
-
- Fixed bug having to do with undefined values in HASH options.
- In particular, Text::Template no longer generates a warning if
- you try to give a variable an undefined value.
-
-----------------------------------------------------------------
-
-What's new in v1.12 since v1.11:
-
- I forgot to say that Text::Template ISA Exporter, so the
- exported functions never got exported. Duhhh!
-
- Template TYPEs are now case-insensitive. The `new' method now
- diagnoses attempts to use an invalid TYPE.
-
- More tests for these things.
-
-----------------------------------------------------------------
-
-What's new in v1.11 since v1.10:
-
- Fixed a bug in the way backslashes were processed. The 1.10
- behavior was incompatible with the beta versions and was also
- inconvenient. (`\n' in templates was replaced with `n' before
- it was given to Perl for evaluation.) The new behavior is
- also incompatible with the beta versions, but it is only a
- little bit incompatible, and it is probbaly better.
-
- Documentation for the new behavior, and tests for the bug.
-
-----------------------------------------------------------------
-
-What's new in v1.10 since v1.03:
-
- New OUTPUT option delivers template results directly to a
- filehandle instead of making them into a string. Saves space
- and time.
-
- PACKAGE and HASH now work intelligently with SAFE.
-
- Fragments may now output data directly to the template, rather
- than having to arrange to return it as a return value at the
- end. This means that where you used to have to write this:
-
- { my $blist = '';
- foreach $i (@items) {
- $blist .= qq{ * $i\n};
- }
- $blist;
- }
-
- You can now write this instead, because $OUT is special.
-
- { foreach $i (@items) {
- $OUT.= " * $i\n";
- }
- }
-
- (`A spoonful of sugar makes the medicine go down.')
-
- Fixed some small bugs. Worked around a bug in Perl that does
- the wrong thing with $x = <Y> when $x contains a glob.
-
- More documentation. Errors fixed.
-
- Lots more tests.
-
-----------------------------------------------------------------
-
-What's new in v1.03 since v1.0:
-
- Code added to support HASH option to fill_in.
- (Incl. `_gensym' function.)
-
- Documentation for HASH.
-
- New test file for HASH.
-
- Note about failure of lexical variables to propagate into
- templates. Why does this surprise people?
-
- Bug fix: program fragments are evaluated in an environment with
- `no strict' by default. Otherwise, you get a lot of `Global
- symbol "$v" requires explicit package name' failures. Why didn't
- the test program pick this up? Because the only variable the test
- program ever used was `$a', which is exempt. Duhhhhh.
-
- Fixed the test program.
-
- Various minor documentation fixes.
-
-
-
-----------------------------------------------------------------
-
-Improvements of 1.0 over the old 0.1beta:
-
-New features:
-
- At least twice as fast
-
- Better support for filling out the same template more than once
-
- Now supports evaluation of program fragments in Safe
- compartments. (Thanks, Jonathan!)
-
- Better argument syntax
-
- More convenience functions
-
- The parser is much better and simpler.
-
- Once a template is parsed, the parsed version is stored so that
- it needn't be parsed again.
-
- BROKEN function behavior is rationalized. You can now pass an
- arbitrary argument to your BROKEN function, or return a value
- from it to the main program.
-
- Documentation overhauled.
-
+++ /dev/null
-# -*- perl -*-
-# Text::Template.pm
-#
-# Fill in `templates'
-#
-# Copyright 2013 M. J. Dominus.
-# You may copy and distribute this program under the
-# same terms as Perl iteself.
-# If in doubt, write to mjd-perl-template+@plover.com for a license.
-#
-# Version 1.46
-
-package Text::Template;
-require 5.004;
-use Exporter;
-@ISA = qw(Exporter);
-@EXPORT_OK = qw(fill_in_file fill_in_string TTerror);
-use vars '$ERROR';
-use strict;
-
-$Text::Template::VERSION = '1.46';
-my %GLOBAL_PREPEND = ('Text::Template' => '');
-
-sub Version {
- $Text::Template::VERSION;
-}
-
-sub _param {
- my $kk;
- my ($k, %h) = @_;
- for $kk ($k, "\u$k", "\U$k", "-$k", "-\u$k", "-\U$k") {
- return $h{$kk} if exists $h{$kk};
- }
- return;
-}
-
-sub always_prepend
-{
- my $pack = shift;
- my $old = $GLOBAL_PREPEND{$pack};
- $GLOBAL_PREPEND{$pack} = shift;
- $old;
-}
-
-{
- my %LEGAL_TYPE;
- BEGIN {
- %LEGAL_TYPE = map {$_=>1} qw(FILE FILEHANDLE STRING ARRAY);
- }
- sub new {
- my $pack = shift;
- my %a = @_;
- my $stype = uc(_param('type', %a) || "FILE");
- my $source = _param('source', %a);
- my $untaint = _param('untaint', %a);
- my $prepend = _param('prepend', %a);
- my $alt_delim = _param('delimiters', %a);
- my $broken = _param('broken', %a);
- unless (defined $source) {
- require Carp;
- Carp::croak("Usage: $ {pack}::new(TYPE => ..., SOURCE => ...)");
- }
- unless ($LEGAL_TYPE{$stype}) {
- require Carp;
- Carp::croak("Illegal value `$stype' for TYPE parameter");
- }
- my $self = {TYPE => $stype,
- PREPEND => $prepend,
- UNTAINT => $untaint,
- BROKEN => $broken,
- (defined $alt_delim ? (DELIM => $alt_delim) : ()),
- };
- # Under 5.005_03, if any of $stype, $prepend, $untaint, or $broken
- # are tainted, all the others become tainted too as a result of
- # sharing the expression with them. We install $source separately
- # to prevent it from acquiring a spurious taint.
- $self->{SOURCE} = $source;
-
- bless $self => $pack;
- return unless $self->_acquire_data;
-
- $self;
- }
-}
-
-# Convert template objects of various types to type STRING,
-# in which the template data is embedded in the object itself.
-sub _acquire_data {
- my ($self) = @_;
- my $type = $self->{TYPE};
- if ($type eq 'STRING') {
- # nothing necessary
- } elsif ($type eq 'FILE') {
- my $data = _load_text($self->{SOURCE});
- unless (defined $data) {
- # _load_text already set $ERROR
- return undef;
- }
- if ($self->{UNTAINT} && _is_clean($self->{SOURCE})) {
- _unconditionally_untaint($data);
- }
- $self->{TYPE} = 'STRING';
- $self->{FILENAME} = $self->{SOURCE};
- $self->{SOURCE} = $data;
- } elsif ($type eq 'ARRAY') {
- $self->{TYPE} = 'STRING';
- $self->{SOURCE} = join '', @{$self->{SOURCE}};
- } elsif ($type eq 'FILEHANDLE') {
- $self->{TYPE} = 'STRING';
- local $/;
- my $fh = $self->{SOURCE};
- my $data = <$fh>; # Extra assignment avoids bug in Solaris perl5.00[45].
- if ($self->{UNTAINT}) {
- _unconditionally_untaint($data);
- }
- $self->{SOURCE} = $data;
- } else {
- # This should have been caught long ago, so it represents a
- # drastic `can't-happen' sort of failure
- my $pack = ref $self;
- die "Can only acquire data for $pack objects of subtype STRING, but this is $type; aborting";
- }
- $self->{DATA_ACQUIRED} = 1;
-}
-
-sub source {
- my ($self) = @_;
- $self->_acquire_data unless $self->{DATA_ACQUIRED};
- return $self->{SOURCE};
-}
-
-sub set_source_data {
- my ($self, $newdata) = @_;
- $self->{SOURCE} = $newdata;
- $self->{DATA_ACQUIRED} = 1;
- $self->{TYPE} = 'STRING';
- 1;
-}
-
-sub compile {
- my $self = shift;
-
- return 1 if $self->{TYPE} eq 'PREPARSED';
-
- return undef unless $self->_acquire_data;
- unless ($self->{TYPE} eq 'STRING') {
- my $pack = ref $self;
- # This should have been caught long ago, so it represents a
- # drastic `can't-happen' sort of failure
- die "Can only compile $pack objects of subtype STRING, but this is $self->{TYPE}; aborting";
- }
-
- my @tokens;
- my $delim_pats = shift() || $self->{DELIM};
-
-
-
- my ($t_open, $t_close) = ('{', '}');
- my $DELIM; # Regex matches a delimiter if $delim_pats
- if (defined $delim_pats) {
- ($t_open, $t_close) = @$delim_pats;
- $DELIM = "(?:(?:\Q$t_open\E)|(?:\Q$t_close\E))";
- @tokens = split /($DELIM|\n)/, $self->{SOURCE};
- } else {
- @tokens = split /(\\\\(?=\\*[{}])|\\[{}]|[{}\n])/, $self->{SOURCE};
- }
- my $state = 'TEXT';
- my $depth = 0;
- my $lineno = 1;
- my @content;
- my $cur_item = '';
- my $prog_start;
- while (@tokens) {
- my $t = shift @tokens;
- next if $t eq '';
- if ($t eq $t_open) { # Brace or other opening delimiter
- if ($depth == 0) {
- push @content, [$state, $cur_item, $lineno] if $cur_item ne '';
- $cur_item = '';
- $state = 'PROG';
- $prog_start = $lineno;
- } else {
- $cur_item .= $t;
- }
- $depth++;
- } elsif ($t eq $t_close) { # Brace or other closing delimiter
- $depth--;
- if ($depth < 0) {
- $ERROR = "Unmatched close brace at line $lineno";
- return undef;
- } elsif ($depth == 0) {
- push @content, [$state, $cur_item, $prog_start] if $cur_item ne '';
- $state = 'TEXT';
- $cur_item = '';
- } else {
- $cur_item .= $t;
- }
- } elsif (!$delim_pats && $t eq '\\\\') { # precedes \\\..\\\{ or \\\..\\\}
- $cur_item .= '\\';
- } elsif (!$delim_pats && $t =~ /^\\([{}])$/) { # Escaped (literal) brace?
- $cur_item .= $1;
- } elsif ($t eq "\n") { # Newline
- $lineno++;
- $cur_item .= $t;
- } else { # Anything else
- $cur_item .= $t;
- }
- }
-
- if ($state eq 'PROG') {
- $ERROR = "End of data inside program text that began at line $prog_start";
- return undef;
- } elsif ($state eq 'TEXT') {
- push @content, [$state, $cur_item, $lineno] if $cur_item ne '';
- } else {
- die "Can't happen error #1";
- }
-
- $self->{TYPE} = 'PREPARSED';
- $self->{SOURCE} = \@content;
- 1;
-}
-
-sub prepend_text {
- my ($self) = @_;
- my $t = $self->{PREPEND};
- unless (defined $t) {
- $t = $GLOBAL_PREPEND{ref $self};
- unless (defined $t) {
- $t = $GLOBAL_PREPEND{'Text::Template'};
- }
- }
- $self->{PREPEND} = $_[1] if $#_ >= 1;
- return $t;
-}
-
-sub fill_in {
- my $fi_self = shift;
- my %fi_a = @_;
-
- unless ($fi_self->{TYPE} eq 'PREPARSED') {
- my $delims = _param('delimiters', %fi_a);
- my @delim_arg = (defined $delims ? ($delims) : ());
- $fi_self->compile(@delim_arg)
- or return undef;
- }
-
- my $fi_varhash = _param('hash', %fi_a);
- my $fi_package = _param('package', %fi_a) ;
- my $fi_broken =
- _param('broken', %fi_a) || $fi_self->{BROKEN} || \&_default_broken;
- my $fi_broken_arg = _param('broken_arg', %fi_a) || [];
- my $fi_safe = _param('safe', %fi_a);
- my $fi_ofh = _param('output', %fi_a);
- my $fi_eval_package;
- my $fi_scrub_package = 0;
- my $fi_filename = _param('filename') || $fi_self->{FILENAME} || 'template';
-
- my $fi_prepend = _param('prepend', %fi_a);
- unless (defined $fi_prepend) {
- $fi_prepend = $fi_self->prepend_text;
- }
-
- if (defined $fi_safe) {
- $fi_eval_package = 'main';
- } elsif (defined $fi_package) {
- $fi_eval_package = $fi_package;
- } elsif (defined $fi_varhash) {
- $fi_eval_package = _gensym();
- $fi_scrub_package = 1;
- } else {
- $fi_eval_package = caller;
- }
-
- my $fi_install_package;
- if (defined $fi_varhash) {
- if (defined $fi_package) {
- $fi_install_package = $fi_package;
- } elsif (defined $fi_safe) {
- $fi_install_package = $fi_safe->root;
- } else {
- $fi_install_package = $fi_eval_package; # The gensymmed one
- }
- _install_hash($fi_varhash => $fi_install_package);
- }
-
- if (defined $fi_package && defined $fi_safe) {
- no strict 'refs';
- # Big fat magic here: Fix it so that the user-specified package
- # is the default one available in the safe compartment.
- *{$fi_safe->root . '::'} = \%{$fi_package . '::'}; # LOD
- }
-
- my $fi_r = '';
- my $fi_item;
- foreach $fi_item (@{$fi_self->{SOURCE}}) {
- my ($fi_type, $fi_text, $fi_lineno) = @$fi_item;
- if ($fi_type eq 'TEXT') {
- $fi_self->append_text_to_output(
- text => $fi_text,
- handle => $fi_ofh,
- out => \$fi_r,
- type => $fi_type,
- );
- } elsif ($fi_type eq 'PROG') {
- no strict;
- my $fi_lcomment = "#line $fi_lineno $fi_filename";
- my $fi_progtext =
- "package $fi_eval_package; $fi_prepend;\n$fi_lcomment\n$fi_text;";
- my $fi_res;
- my $fi_eval_err = '';
- if ($fi_safe) {
- $fi_safe->reval(q{undef $OUT});
- $fi_res = $fi_safe->reval($fi_progtext);
- $fi_eval_err = $@;
- my $OUT = $fi_safe->reval('$OUT');
- $fi_res = $OUT if defined $OUT;
- } else {
- my $OUT;
- $fi_res = eval $fi_progtext;
- $fi_eval_err = $@;
- $fi_res = $OUT if defined $OUT;
- }
-
- # If the value of the filled-in text really was undef,
- # change it to an explicit empty string to avoid undefined
- # value warnings later.
- $fi_res = '' unless defined $fi_res;
-
- if ($fi_eval_err) {
- $fi_res = $fi_broken->(text => $fi_text,
- error => $fi_eval_err,
- lineno => $fi_lineno,
- arg => $fi_broken_arg,
- );
- if (defined $fi_res) {
- $fi_self->append_text_to_output(
- text => $fi_res,
- handle => $fi_ofh,
- out => \$fi_r,
- type => $fi_type,
- );
- } else {
- return $fi_res; # Undefined means abort processing
- }
- } else {
- $fi_self->append_text_to_output(
- text => $fi_res,
- handle => $fi_ofh,
- out => \$fi_r,
- type => $fi_type,
- );
- }
- } else {
- die "Can't happen error #2";
- }
- }
-
- _scrubpkg($fi_eval_package) if $fi_scrub_package;
- defined $fi_ofh ? 1 : $fi_r;
-}
-
-sub append_text_to_output {
- my ($self, %arg) = @_;
-
- if (defined $arg{handle}) {
- print { $arg{handle} } $arg{text};
- } else {
- ${ $arg{out} } .= $arg{text};
- }
-
- return;
-}
-
-sub fill_this_in {
- my $pack = shift;
- my $text = shift;
- my $templ = $pack->new(TYPE => 'STRING', SOURCE => $text, @_)
- or return undef;
- $templ->compile or return undef;
- my $result = $templ->fill_in(@_);
- $result;
-}
-
-sub fill_in_string {
- my $string = shift;
- my $package = _param('package', @_);
- push @_, 'package' => scalar(caller) unless defined $package;
- Text::Template->fill_this_in($string, @_);
-}
-
-sub fill_in_file {
- my $fn = shift;
- my $templ = Text::Template->new(TYPE => 'FILE', SOURCE => $fn, @_)
- or return undef;
- $templ->compile or return undef;
- my $text = $templ->fill_in(@_);
- $text;
-}
-
-sub _default_broken {
- my %a = @_;
- my $prog_text = $a{text};
- my $err = $a{error};
- my $lineno = $a{lineno};
- chomp $err;
-# $err =~ s/\s+at .*//s;
- "Program fragment delivered error ``$err''";
-}
-
-sub _load_text {
- my $fn = shift;
- local *F;
- unless (open F, $fn) {
- $ERROR = "Couldn't open file $fn: $!";
- return undef;
- }
- local $/;
- <F>;
-}
-
-sub _is_clean {
- my $z;
- eval { ($z = join('', @_)), eval '#' . substr($z,0,0); 1 } # LOD
-}
-
-sub _unconditionally_untaint {
- for (@_) {
- ($_) = /(.*)/s;
- }
-}
-
-{
- my $seqno = 0;
- sub _gensym {
- __PACKAGE__ . '::GEN' . $seqno++;
- }
- sub _scrubpkg {
- my $s = shift;
- $s =~ s/^Text::Template:://;
- no strict 'refs';
- my $hash = $Text::Template::{$s."::"};
- foreach my $key (keys %$hash) {
- undef $hash->{$key};
- }
- }
-}
-
-# Given a hashful of variables (or a list of such hashes)
-# install the variables into the specified package,
-# overwriting whatever variables were there before.
-sub _install_hash {
- my $hashlist = shift;
- my $dest = shift;
- if (UNIVERSAL::isa($hashlist, 'HASH')) {
- $hashlist = [$hashlist];
- }
- my $hash;
- foreach $hash (@$hashlist) {
- my $name;
- foreach $name (keys %$hash) {
- my $val = $hash->{$name};
- no strict 'refs';
- local *SYM = *{"$ {dest}::$name"};
- if (! defined $val) {
- delete ${"$ {dest}::"}{$name};
- } elsif (ref $val) {
- *SYM = $val;
- } else {
- *SYM = \$val;
- }
- }
- }
-}
-
-sub TTerror { $ERROR }
-
-1;
-
-
-=head1 NAME
-
-Text::Template - Expand template text with embedded Perl
-
-=head1 VERSION
-
-This file documents C<Text::Template> version B<1.46>
-
-=head1 SYNOPSIS
-
- use Text::Template;
-
-
- $template = Text::Template->new(TYPE => 'FILE', SOURCE => 'filename.tmpl');
- $template = Text::Template->new(TYPE => 'ARRAY', SOURCE => [ ... ] );
- $template = Text::Template->new(TYPE => 'FILEHANDLE', SOURCE => $fh );
- $template = Text::Template->new(TYPE => 'STRING', SOURCE => '...' );
- $template = Text::Template->new(PREPEND => q{use strict;}, ...);
-
- # Use a different template file syntax:
- $template = Text::Template->new(DELIMITERS => [$open, $close], ...);
-
- $recipient = 'King';
- $text = $template->fill_in(); # Replaces `{$recipient}' with `King'
- print $text;
-
- $T::recipient = 'Josh';
- $text = $template->fill_in(PACKAGE => T);
-
- # Pass many variables explicitly
- $hash = { recipient => 'Abed-Nego',
- friends => [ 'me', 'you' ],
- enemies => { loathsome => 'Bill Gates',
- fearsome => 'Larry Ellison' },
- };
- $text = $template->fill_in(HASH => $hash, ...);
- # $recipient is Abed-Nego,
- # @friends is ( 'me', 'you' ),
- # %enemies is ( loathsome => ..., fearsome => ... )
-
-
- # Call &callback in case of programming errors in template
- $text = $template->fill_in(BROKEN => \&callback, BROKEN_ARG => $ref, ...);
-
- # Evaluate program fragments in Safe compartment with restricted permissions
- $text = $template->fill_in(SAFE => $compartment, ...);
-
- # Print result text instead of returning it
- $success = $template->fill_in(OUTPUT => \*FILEHANDLE, ...);
-
- # Parse template with different template file syntax:
- $text = $template->fill_in(DELIMITERS => [$open, $close], ...);
- # Note that this is *faster* than using the default delimiters
-
- # Prepend specified perl code to each fragment before evaluating:
- $text = $template->fill_in(PREPEND => q{use strict 'vars';}, ...);
-
- use Text::Template 'fill_in_string';
- $text = fill_in_string( <<EOM, PACKAGE => 'T', ...);
- Dear {$recipient},
- Pay me at once.
- Love,
- G.V.
- EOM
-
- use Text::Template 'fill_in_file';
- $text = fill_in_file($filename, ...);
-
- # All templates will always have `use strict vars' attached to all fragments
- Text::Template->always_prepend(q{use strict 'vars';});
-
-=head1 DESCRIPTION
-
-This is a library for generating form letters, building HTML pages, or
-filling in templates generally. A `template' is a piece of text that
-has little Perl programs embedded in it here and there. When you
-`fill in' a template, you evaluate the little programs and replace
-them with their values.
-
-You can store a template in a file outside your program. People can
-modify the template without modifying the program. You can separate
-the formatting details from the main code, and put the formatting
-parts of the program into the template. That prevents code bloat and
-encourages functional separation.
-
-=head2 Example
-
-Here's an example of a template, which we'll suppose is stored in the
-file C<formletter.tmpl>:
-
- Dear {$title} {$lastname},
-
- It has come to our attention that you are delinquent in your
- {$monthname[$last_paid_month]} payment. Please remit
- ${sprintf("%.2f", $amount)} immediately, or your patellae may
- be needlessly endangered.
-
- Love,
-
- Mark "Vizopteryx" Dominus
-
-
-The result of filling in this template is a string, which might look
-something like this:
-
- Dear Mr. Gates,
-
- It has come to our attention that you are delinquent in your
- February payment. Please remit
- $392.12 immediately, or your patellae may
- be needlessly endangered.
-
-
- Love,
-
- Mark "Vizopteryx" Dominus
-
-Here is a complete program that transforms the example
-template into the example result, and prints it out:
-
- use Text::Template;
-
- my $template = Text::Template->new(SOURCE => 'formletter.tmpl')
- or die "Couldn't construct template: $Text::Template::ERROR";
-
- my @monthname = qw(January February March April May June
- July August September October November December);
- my %vars = (title => 'Mr.',
- firstname => 'Bill',
- lastname => 'Gates',
- last_paid_month => 1, # February
- amount => 392.12,
- monthname => \@monthname,
- );
-
- my $result = $template->fill_in(HASH => \%vars);
-
- if (defined $result) { print $result }
- else { die "Couldn't fill in template: $Text::Template::ERROR" }
-
-
-=head2 Philosophy
-
-When people make a template module like this one, they almost always
-start by inventing a special syntax for substitutions. For example,
-they build it so that a string like C<%%VAR%%> is replaced with the
-value of C<$VAR>. Then they realize the need extra formatting, so
-they put in some special syntax for formatting. Then they need a
-loop, so they invent a loop syntax. Pretty soon they have a new
-little template language.
-
-This approach has two problems: First, their little language is
-crippled. If you need to do something the author hasn't thought of,
-you lose. Second: Who wants to learn another language? You already
-know Perl, so why not use it?
-
-C<Text::Template> templates are programmed in I<Perl>. You embed Perl
-code in your template, with C<{> at the beginning and C<}> at the end.
-If you want a variable interpolated, you write it the way you would in
-Perl. If you need to make a loop, you can use any of the Perl loop
-constructions. All the Perl built-in functions are available.
-
-=head1 Details
-
-=head2 Template Parsing
-
-The C<Text::Template> module scans the template source. An open brace
-C<{> begins a program fragment, which continues until the matching
-close brace C<}>. When the template is filled in, the program
-fragments are evaluated, and each one is replaced with the resulting
-value to yield the text that is returned.
-
-A backslash C<\> in front of a brace (or another backslash that is in
-front of a brace) escapes its special meaning. The result of filling
-out this template:
-
- \{ The sum of 1 and 2 is {1+2} \}
-
-is
-
- { The sum of 1 and 2 is 3 }
-
-If you have an unmatched brace, C<Text::Template> will return a
-failure code and a warning about where the problem is. Backslashes
-that do not precede a brace are passed through unchanged. If you have
-a template like this:
-
- { "String that ends in a newline.\n" }
-
-The backslash inside the string is passed through to Perl unchanged,
-so the C<\n> really does turn into a newline. See the note at the end
-for details about the way backslashes work. Backslash processing is
-I<not> done when you specify alternative delimiters with the
-C<DELIMITERS> option. (See L<"Alternative Delimiters">, below.)
-
-Each program fragment should be a sequence of Perl statements, which
-are evaluated the usual way. The result of the last statement
-executed will be evaluted in scalar context; the result of this
-statement is a string, which is interpolated into the template in
-place of the program fragment itself.
-
-The fragments are evaluated in order, and side effects from earlier
-fragments will persist into later fragments:
-
- {$x = @things; ''}The Lord High Chamberlain has gotten {$x}
- things for me this year.
- { $diff = $x - 17;
- $more = 'more'
- if ($diff == 0) {
- $diff = 'no';
- } elsif ($diff < 0) {
- $more = 'fewer';
- }
- '';
- }
- That is {$diff} {$more} than he gave me last year.
-
-The value of C<$x> set in the first line will persist into the next
-fragment that begins on the third line, and the values of C<$diff> and
-C<$more> set in the second fragment will persist and be interpolated
-into the last line. The output will look something like this:
-
- The Lord High Chamberlain has gotten 42
- things for me this year.
-
- That is 25 more than he gave me last year.
-
-That is all the syntax there is.
-
-=head2 The C<$OUT> variable
-
-There is one special trick you can play in a template. Here is the
-motivation for it: Suppose you are going to pass an array, C<@items>,
-into the template, and you want the template to generate a bulleted
-list with a header, like this:
-
- Here is a list of the things I have got for you since 1907:
- * Ivory
- * Apes
- * Peacocks
- * ...
-
-One way to do it is with a template like this:
-
- Here is a list of the things I have got for you since 1907:
- { my $blist = '';
- foreach $i (@items) {
- $blist .= qq{ * $i\n};
- }
- $blist;
- }
-
-Here we construct the list in a variable called C<$blist>, which we
-return at the end. This is a little cumbersome. There is a shortcut.
-
-Inside of templates, there is a special variable called C<$OUT>.
-Anything you append to this variable will appear in the output of the
-template. Also, if you use C<$OUT> in a program fragment, the normal
-behavior, of replacing the fragment with its return value, is
-disabled; instead the fragment is replaced with the value of C<$OUT>.
-This means that you can write the template above like this:
-
- Here is a list of the things I have got for you since 1907:
- { foreach $i (@items) {
- $OUT .= " * $i\n";
- }
- }
-
-C<$OUT> is reinitialized to the empty string at the start of each
-program fragment. It is private to C<Text::Template>, so
-you can't use a variable named C<$OUT> in your template without
-invoking the special behavior.
-
-=head2 General Remarks
-
-All C<Text::Template> functions return C<undef> on failure, and set the
-variable C<$Text::Template::ERROR> to contain an explanation of what
-went wrong. For example, if you try to create a template from a file
-that does not exist, C<$Text::Template::ERROR> will contain something like:
-
- Couldn't open file xyz.tmpl: No such file or directory
-
-=head2 C<new>
-
- $template = new Text::Template ( TYPE => ..., SOURCE => ... );
-
-This creates and returns a new template object. C<new> returns
-C<undef> and sets C<$Text::Template::ERROR> if it can't create the
-template object. C<SOURCE> says where the template source code will
-come from. C<TYPE> says what kind of object the source is.
-
-The most common type of source is a file:
-
- new Text::Template ( TYPE => 'FILE', SOURCE => $filename );
-
-This reads the template from the specified file. The filename is
-opened with the Perl C<open> command, so it can be a pipe or anything
-else that makes sense with C<open>.
-
-The C<TYPE> can also be C<STRING>, in which case the C<SOURCE> should
-be a string:
-
- new Text::Template ( TYPE => 'STRING',
- SOURCE => "This is the actual template!" );
-
-The C<TYPE> can be C<ARRAY>, in which case the source should be a
-reference to an array of strings. The concatenation of these strings
-is the template:
-
- new Text::Template ( TYPE => 'ARRAY',
- SOURCE => [ "This is ", "the actual",
- " template!",
- ]
- );
-
-The C<TYPE> can be FILEHANDLE, in which case the source should be an
-open filehandle (such as you got from the C<FileHandle> or C<IO::*>
-packages, or a glob, or a reference to a glob). In this case
-C<Text::Template> will read the text from the filehandle up to
-end-of-file, and that text is the template:
-
- # Read template source code from STDIN:
- new Text::Template ( TYPE => 'FILEHANDLE',
- SOURCE => \*STDIN );
-
-
-If you omit the C<TYPE> attribute, it's taken to be C<FILE>.
-C<SOURCE> is required. If you omit it, the program will abort.
-
-The words C<TYPE> and C<SOURCE> can be spelled any of the following ways:
-
- TYPE SOURCE
- Type Source
- type source
- -TYPE -SOURCE
- -Type -Source
- -type -source
-
-Pick a style you like and stick with it.
-
-=over 4
-
-=item C<DELIMITERS>
-
-You may also add a C<DELIMITERS> option. If this option is present,
-its value should be a reference to an array 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 L<"Alternative Delimiters">, below.
-
-=item C<UNTAINT>
-
-If your program is running in taint mode, you may have problems if
-your templates are stored in files. Data read from files is
-considered 'untrustworthy', and taint mode will not allow you to
-evaluate the Perl code in the file. (It is afraid that a malicious
-person might have tampered with the file.)
-
-In some environments, however, local files are trustworthy. You can
-tell C<Text::Template> that a certain file is trustworthy by supplying
-C<UNTAINT =E<gt> 1> in the call to C<new>. This will tell
-C<Text::Template> to disable taint checks on template code that has
-come from a file, as long as the filename itself is considered
-trustworthy. It will also disable taint checks on template code that
-comes from a filehandle. When used with C<TYPE =E<gt> 'string'> or C<TYPE
-=E<gt> 'array'>, it has no effect.
-
-See L<perlsec> for more complete information about tainting.
-
-Thanks to Steve Palincsar, Gerard Vreeswijk, and Dr. Christoph Baehr
-for help with this feature.
-
-=item C<PREPEND>
-
-This option is passed along to the C<fill_in> call unless it is
-overridden in the arguments to C<fill_in>. See L<C<PREPEND> feature
-and using C<strict> in templates> below.
-
-=item C<BROKEN>
-
-This option is passed along to the C<fill_in> call unless it is
-overridden in the arguments to C<fill_in>. See L<C<BROKEN>> below.
-
-=back
-
-=head2 C<compile>
-
- $template->compile()
-
-Loads all the template text from the template's source, parses and
-compiles it. If successful, returns true; otherwise returns false and
-sets C<$Text::Template::ERROR>. If the template is already compiled,
-it returns true and does nothing.
-
-You don't usually need to invoke this function, because C<fill_in>
-(see below) compiles the template if it isn't compiled already.
-
-If there is an argument to this function, it must be a reference to an
-array containing alternative delimiter strings. See C<"Alternative
-Delimiters">, below.
-
-=head2 C<fill_in>
-
- $template->fill_in(OPTIONS);
-
-Fills in a template. Returns the resulting text if successful.
-Otherwise, returns C<undef> and sets C<$Text::Template::ERROR>.
-
-The I<OPTIONS> are a hash, or a list of key-value pairs. You can
-write the key names in any of the six usual styles as above; this
-means that where this manual says C<PACKAGE> (for example) you can
-actually use any of
-
- PACKAGE Package package -PACKAGE -Package -package
-
-Pick a style you like and stick with it. The all-lowercase versions
-may yield spurious warnings about
-
- Ambiguous use of package => resolved to "package"
-
-so you might like to avoid them and use the capitalized versions.
-
-At present, there are eight legal options: C<PACKAGE>, C<BROKEN>,
-C<BROKEN_ARG>, C<SAFE>, C<HASH>, C<OUTPUT>, and C<DELIMITERS>.
-
-=over 4
-
-=item C<PACKAGE>
-
-C<PACKAGE> specifies the name of a package in which the program
-fragments should be evaluated. The default is to use the package from
-which C<fill_in> was called. For example, consider this template:
-
- The value of the variable x is {$x}.
-
-If you use C<$template-E<gt>fill_in(PACKAGE =E<gt> 'R')> , then the C<$x> in
-the template is actually replaced with the value of C<$R::x>. If you
-omit the C<PACKAGE> option, C<$x> will be replaced with the value of
-the C<$x> variable in the package that actually called C<fill_in>.
-
-You should almost always use C<PACKAGE>. If you don't, and your
-template makes changes to variables, those changes will be propagated
-back into the main program. Evaluating the template in a private
-package helps prevent this. The template can still modify variables
-in your program if it wants to, but it will have to do so explicitly.
-See the section at the end on `Security'.
-
-Here's an example of using C<PACKAGE>:
-
- Your Royal Highness,
-
- Enclosed please find a list of things I have gotten
- for you since 1907:
-
- { foreach $item (@items) {
- $item_no++;
- $OUT .= " $item_no. \u$item\n";
- }
- }
-
- Signed,
- Lord High Chamberlain
-
-We want to pass in an array which will be assigned to the array
-C<@items>. Here's how to do that:
-
-
- @items = ('ivory', 'apes', 'peacocks', );
- $template->fill_in();
-
-This is not very safe. The reason this isn't as safe is that if you
-had a variable named C<$item_no> in scope in your program at the point
-you called C<fill_in>, its value would be clobbered by the act of
-filling out the template. The problem is the same as if you had
-written a subroutine that used those variables in the same way that
-the template does. (C<$OUT> is special in templates and is always
-safe.)
-
-One solution to this is to make the C<$item_no> variable private to the
-template by declaring it with C<my>. If the template does this, you
-are safe.
-
-But if you use the C<PACKAGE> option, you will probably be safe even
-if the template does I<not> declare its variables with C<my>:
-
- @Q::items = ('ivory', 'apes', 'peacocks', );
- $template->fill_in(PACKAGE => 'Q');
-
-In this case the template will clobber the variable C<$Q::item_no>,
-which is not related to the one your program was using.
-
-Templates cannot affect variables in the main program that are
-declared with C<my>, unless you give the template references to those
-variables.
-
-=item C<HASH>
-
-You may not want to put the template variables into a package.
-Packages can be hard to manage: You can't copy them, for example.
-C<HASH> provides an alternative.
-
-The value for C<HASH> should be a reference to a hash that maps
-variable names to values. For example,
-
- $template->fill_in(HASH => { recipient => "The King",
- items => ['gold', 'frankincense', 'myrrh'],
- object => \$self,
- });
-
-will fill out the template and use C<"The King"> as the value of
-C<$recipient> and the list of items as the value of C<@items>. Note
-that we pass an array reference, but inside the template it appears as
-an array. In general, anything other than a simple string or number
-should be passed by reference.
-
-We also want to pass an object, which is in C<$self>; note that we
-pass a reference to the object, C<\$self> instead. Since we've passed
-a reference to a scalar, inside the template the object appears as
-C<$object>.
-
-The full details of how it works are a little involved, so you might
-want to skip to the next section.
-
-Suppose the key in the hash is I<key> and the value is I<value>.
-
-=over 4
-
-=item *
-
-If the I<value> is C<undef>, then any variables named C<$key>,
-C<@key>, C<%key>, etc., are undefined.
-
-=item *
-
-If the I<value> is a string or a number, then C<$key> is set to that
-value in the template.
-
-=item *
-
-For anything else, you must pass a reference.
-
-If the I<value> is a reference to an array, then C<@key> is set to
-that array. If the I<value> is a reference to a hash, then C<%key> is
-set to that hash. Similarly if I<value> is any other kind of
-reference. This means that
-
- var => "foo"
-
-and
-
- var => \"foo"
-
-have almost exactly the same effect. (The difference is that in the
-former case, the value is copied, and in the latter case it is
-aliased.)
-
-=item *
-
-In particular, if you want the template to get an object or any kind,
-you must pass a reference to it:
-
- $template->fill_in(HASH => { database_handle => \$dbh, ... });
-
-If you do this, the template will have a variable C<$database_handle>
-which is the database handle object. If you leave out the C<\>, the
-template will have a hash C<%database_handle>, which exposes the
-internal structure of the database handle object; you don't want that.
-
-=back
-
-Normally, the way this works is by allocating a private package,
-loading all the variables into the package, and then filling out the
-template as if you had specified that package. A new package is
-allocated each time. However, if you I<also> use the C<PACKAGE>
-option, C<Text::Template> loads the variables into the package you
-specified, and they stay there after the call returns. Subsequent
-calls to C<fill_in> that use the same package will pick up the values
-you loaded in.
-
-If the argument of C<HASH> is a reference to an array instead of a
-reference to a hash, then the array should contain a list of hashes
-whose contents are loaded into the template package one after the
-other. You can use this feature if you want to combine several sets
-of variables. For example, one set of variables might be the defaults
-for a fill-in form, and the second set might be the user inputs, which
-override the defaults when they are present:
-
- $template->fill_in(HASH => [\%defaults, \%user_input]);
-
-You can also use this to set two variables with the same name:
-
- $template->fill_in(HASH => [{ v => "The King" },
- { v => [1,2,3] },
- ]
- );
-
-This sets C<$v> to C<"The King"> and C<@v> to C<(1,2,3)>.
-
-=item C<BROKEN>
-
-If any of the program fragments fails to compile or aborts for any
-reason, and you have set the C<BROKEN> option to a function reference,
-C<Text::Template> will invoke the function. This function is called
-the I<C<BROKEN> function>. The C<BROKEN> function will tell
-C<Text::Template> what to do next.
-
-If the C<BROKEN> function returns C<undef>, C<Text::Template> will
-immediately abort processing the template and return the text that it
-has accumulated so far. If your function does this, it should set a
-flag that you can examine after C<fill_in> returns so that you can
-tell whether there was a premature return or not.
-
-If the C<BROKEN> function returns any other value, that value will be
-interpolated into the template as if that value had been the return
-value of the program fragment to begin with. For example, if the
-C<BROKEN> function returns an error string, the error string will be
-interpolated into the output of the template in place of the program
-fragment that cased the error.
-
-If you don't specify a C<BROKEN> function, C<Text::Template> supplies
-a default one that returns something like
-
- Program fragment delivered error ``Illegal division by 0 at
- template line 37''
-
-(Note that the format of this message has changed slightly since
-version 1.31.) The return value of the C<BROKEN> function is
-interpolated into the template at the place the error occurred, so
-that this template:
-
- (3+4)*5 = { 3+4)*5 }
-
-yields this result:
-
- (3+4)*5 = Program fragment delivered error ``syntax error at template line 1''
-
-If you specify a value for the C<BROKEN> attribute, it should be a
-reference to a function that C<fill_in> can call instead of the
-default function.
-
-C<fill_in> will pass a hash to the C<broken> function.
-The hash will have at least these three members:
-
-=over 4
-
-=item C<text>
-
-The source code of the program fragment that failed
-
-=item C<error>
-
-The text of the error message (C<$@>) 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.
-
-=item C<lineno>
-
-The line number of the template at which the program fragment began.
-
-=back
-
-There may also be an C<arg> member. See C<BROKEN_ARG>, below
-
-=item C<BROKEN_ARG>
-
-If you supply the C<BROKEN_ARG> option to C<fill_in>, the value of the
-option is passed to the C<BROKEN> function whenever it is called. The
-default C<BROKEN> function ignores the C<BROKEN_ARG>, but you can
-write a custom C<BROKEN> function that uses the C<BROKEN_ARG> to get
-more information about what went wrong.
-
-The C<BROKEN> function could also use the C<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 = '';
-
- sub my_broken {
- my %args = @_;
- my $err_ref = $args{arg};
- ...
- $$err_ref = "Some error message";
- return undef;
- }
-
- $template->fill_in(BROKEN => \&my_broken,
- BROKEN_ARG => \$error,
- );
-
- if ($error) {
- die "It didn't work: $error";
- }
-
-If one of the program fragments in the template fails, it will call
-the C<BROKEN> function, C<my_broken>, and pass it the C<BROKEN_ARG>,
-which is a reference to C<$error>. C<my_broken> can store an error
-message into C<$error> this way. Then the function that called
-C<fill_in> can see if C<my_broken> has left an error message for it
-to find, and proceed accordingly.
-
-=item C<SAFE>
-
-If you give C<fill_in> a C<SAFE> option, its value should be a safe
-compartment object from the C<Safe> package. All evaluation of
-program fragments will be performed in this compartment. See L<Safe>
-for full details about such compartments and how to restrict the
-operations that can be performed in them.
-
-If you use the C<PACKAGE> option with C<SAFE>, the package you specify
-will be placed into the safe compartment and evaluation will take
-place in that package as usual.
-
-If not, C<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 C<SAFE> mode the evaluation occurs inside the safe compartment
-and cannot affect the calling package. Normally, if you use C<HASH>
-without C<PACKAGE>, the hash variables are imported into a private,
-one-use-only package. But if you use C<HASH> and C<SAFE> together
-without C<PACKAGE>, the hash variables will just be loaded into the
-root namespace of the C<Safe> compartment.
-
-=item C<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
-C<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 C<OUTPUT> option to C<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, ...);
-
-fills in the C<$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 C<OUTPUT>, the return value from C<fill_in> is still true on
-success and false on failure, but the complete text is not returned to
-the caller.
-
-=item C<PREPEND>
-
-You can have some Perl code prepended automatically to the beginning
-of every program fragment. See L<C<PREPEND> feature and using
-C<strict> in templates> below.
-
-=item C<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
-L<"Alternative Delimiters">, below.
-
-If you specify C<DELIMITERS> in the call to C<fill_in>, they override
-any delimiters you set when you created the template object with
-C<new>.
-
-=back
-
-=head1 Convenience Functions
-
-=head2 C<fill_this_in>
-
-The basic way to fill in a template is to create a template object and
-then call C<fill_in> on it. This is useful if you want to fill in
-the same template more than once.
-
-In some programs, this can be cumbersome. C<fill_this_in> accepts a
-string, which contains the template, and a list of options, which are
-passed to C<fill_in> as above. It constructs the template object for
-you, fills it in as specified, and returns the results. It returns
-C<undef> and sets C<$Text::Template::ERROR> if it couldn't generate
-any results.
-
-An example:
-
- $Q::name = 'Donald';
- $Q::amount = 141.61;
- $Q::part = 'hyoid bone';
-
- $text = Text::Template->fill_this_in( <<'EOM', PACKAGE => Q);
- Dear {$name},
- You owe me \\${sprintf('%.2f', $amount)}.
- Pay or I will break your {$part}.
- Love,
- Grand Vizopteryx of Irkutsk.
- EOM
-
-Notice how we included the template in-line in the program by using a
-`here document' with the C<E<lt>E<lt>> notation.
-
-C<fill_this_in> is a deprecated feature. It is only here for
-backwards compatibility, and may be removed in some far-future version
-in C<Text::Template>. You should use C<fill_in_string> instead. It
-is described in the next section.
-
-=head2 C<fill_in_string>
-
-It is stupid that C<fill_this_in> is a class method. It should have
-been just an imported function, so that you could omit the
-C<Text::Template-E<gt>> in the example above. But I made the mistake
-four years ago and it is too late to change it.
-
-C<fill_in_string> is exactly like C<fill_this_in> except that it is
-not a method and you can omit the C<Text::Template-E<gt>> and just say
-
- print fill_in_string(<<'EOM', ...);
- Dear {$name},
- ...
- EOM
-
-To use C<fill_in_string>, you need to say
-
- use Text::Template 'fill_in_string';
-
-at the top of your program. You should probably use
-C<fill_in_string> instead of C<fill_this_in>.
-
-=head2 C<fill_in_file>
-
-If you import C<fill_in_file>, you can say
-
- $text = fill_in_file(filename, ...);
-
-The C<...> are passed to C<fill_in> as above. The filename is the
-name of the file that contains the template you want to fill in. It
-returns the result text. or C<undef>, as usual.
-
-If you are going to fill in the same file more than once in the same
-program you should use the longer C<new> / C<fill_in> sequence instead.
-It will be a lot faster because it only has to read and parse the file
-once.
-
-=head2 Including files into templates
-
-People always ask for this. ``Why don't you have an include
-function?'' they want to know. The short answer is this is Perl, and
-Perl already has an include function. If you want it, you can just put
-
- {qx{cat filename}}
-
-into your template. VoilE<agrave>.
-
-If you don't want to use C<cat>, you can write a little four-line
-function that opens a file and dumps out its contents, and call it
-from the template. I wrote one for you. In the template, you can say
-
- {Text::Template::_load_text(filename)}
-
-If that is too verbose, here is a trick. Suppose the template package
-that you are going to be mentioning in the C<fill_in> call is package
-C<Q>. Then in the main program, write
-
- *Q::include = \&Text::Template::_load_text;
-
-This imports the C<_load_text> function into package C<Q> with the
-name C<include>. From then on, any template that you fill in with
-package C<Q> can say
-
- {include(filename)}
-
-to insert the text from the named file at that point. If you are
-using the C<HASH> option instead, just put C<include =E<gt>
-\&Text::Template::_load_text> into the hash instead of importing it
-explicitly.
-
-Suppose you don't want to insert a plain text file, but rather you
-want to include one template within another? Just use C<fill_in_file>
-in the template itself:
-
- {Text::Template::fill_in_file(filename)}
-
-You can do the same importing trick if this is too much to type.
-
-=head1 Miscellaneous
-
-=head2 C<my> variables
-
-People are frequently surprised when this doesn't work:
-
- my $recipient = 'The King';
- my $text = fill_in_file('formletter.tmpl');
-
-The text C<The King> doesn't get into the form letter. Why not?
-Because C<$recipient> is a C<my> variable, and the whole point of
-C<my> variables is that they're private and inaccessible except in the
-scope in which they're declared. The template is not part of that
-scope, so the template can't see C<$recipient>.
-
-If that's not the behavior you want, don't use C<my>. C<my> means a
-private variable, and in this case you don't want the variable to be
-private. Put the variables into package variables in some other
-package, and use the C<PACKAGE> option to C<fill_in>:
-
- $Q::recipient = $recipient;
- my $text = fill_in_file('formletter.tmpl', PACKAGE => 'Q');
-
-
-or pass the names and values in a hash with the C<HASH> option:
-
- my $text = fill_in_file('formletter.tmpl', HASH => { recipient => $recipient });
-
-=head2 Security Matters
-
-All variables are evaluated in the package you specify with the
-C<PACKAGE> option of C<fill_in>. if you use this option, and if your
-templates don't do anything egregiously stupid, you won't have to
-worry that evaluation of the little programs will creep out into the
-rest of your program and wreck something.
-
-Nevertheless, there's really no way (except with C<Safe>) to protect
-against a template that says
-
- { $Important::Secret::Security::Enable = 0;
- # Disable security checks in this program
- }
-
-or
-
- { $/ = "ho ho ho"; # Sabotage future uses of <FH>.
- # $/ is always a global variable
- }
-
-or even
-
- { system("rm -rf /") }
-
-so B<don't> go filling in templates unless you're sure you know what's
-in them. If you're worried, or you can't trust the person who wrote
-the template, use the C<SAFE> option.
-
-A final warning: program fragments run a small risk of accidentally
-clobbering local variables in the C<fill_in> function itself. These
-variables all have names that begin with C<$fi_>, so if you stay away
-from those names you'll be safe. (Of course, if you're a real wizard
-you can tamper with them deliberately for exciting effects; this is
-actually how C<$OUT> works.) I can fix this, but it will make the
-package slower to do it, so I would prefer not to. If you are worried
-about this, send me mail and I will show you what to do about it.
-
-=head2 Alternative Delimiters
-
-Lorenzo Valdettaro pointed out that if you are using C<Text::Template>
-to generate TeX output, the choice of braces as the program fragment
-delimiters makes you suffer suffer suffer. Starting in version 1.20,
-you can change the choice of delimiters to something other than curly
-braces.
-
-In either the C<new()> call or the C<fill_in()> call, you can specify
-an alternative set of delimiters with the C<DELIMITERS> option. For
-example, if you would like code fragments to be delimited by C<[@-->
-and C<--@]> instead of C<{> and C<}>, use
-
- ... DELIMITERS => [ '[@--', '--@]' ], ...
-
-Note that these delimiters are I<literal strings>, not regexes. (I
-tried for regexes, but it complicates the lexical analysis too much.)
-Note also that C<DELIMITERS> disables the special meaning of the
-backslash, so if you want to include the delimiters in the literal
-text of your template file, you are out of luck---it is up to you to
-choose delimiters that do not conflict with what you are doing. The
-delimiter strings may still appear inside of program fragments as long
-as they nest properly. This means that if for some reason you
-absolutely must have a program fragment that mentions one of the
-delimiters, like this:
-
- [@--
- print "Oh no, a delimiter: --@]\n"
- --@]
-
-you may be able to make it work by doing this instead:
-
- [@--
- # Fake matching delimiter in a comment: [@--
- print "Oh no, a delimiter: --@]\n"
- --@]
-
-It may be safer to choose delimiters that begin with a newline
-character.
-
-Because the parsing of templates is simplified by the absence of
-backslash escapes, using alternative C<DELIMITERS> may speed up the
-parsing process by 20-25%. This shows that my original choice of C<{>
-and C<}> was very bad.
-
-=head2 C<PREPEND> feature and using C<strict> in templates
-
-Suppose you would like to use C<strict> in your templates to detect
-undeclared variables and the like. But each code fragment is a
-separate lexical scope, so you have to turn on C<strict> at the top of
-each and every code fragment:
-
- { use strict;
- use vars '$foo';
- $foo = 14;
- ...
- }
-
- ...
-
- { # we forgot to put `use strict' here
- my $result = $boo + 12; # $boo is misspelled and should be $foo
- # No error is raised on `$boo'
- }
-
-Because we didn't put C<use strict> at the top of the second fragment,
-it was only active in the first fragment, and we didn't get any
-C<strict> checking in the second fragment. Then we mispelled C<$foo>
-and the error wasn't caught.
-
-C<Text::Template> version 1.22 and higher has a new feature to make
-this easier. You can specify that any text at all be automatically
-added to the beginning of each program fragment.
-
-When you make a call to C<fill_in>, you can specify a
-
- PREPEND => 'some perl statements here'
-
-option; the statements will be prepended to each program fragment for
-that one call only. Suppose that the C<fill_in> call included a
-
- PREPEND => 'use strict;'
-
-option, and that the template looked like this:
-
- { use vars '$foo';
- $foo = 14;
- ...
- }
-
- ...
-
- { my $result = $boo + 12; # $boo is misspelled and should be $foo
- ...
- }
-
-The code in the second fragment would fail, because C<$boo> has not
-been declared. C<use strict> was implied, even though you did not
-write it explicitly, because the C<PREPEND> option added it for you
-automatically.
-
-There are two other ways to do this. At the time you create the
-template object with C<new>, you can also supply a C<PREPEND> option,
-in which case the statements will be prepended each time you fill in
-that template. If the C<fill_in> call has its own C<PREPEND> option,
-this overrides the one specified at the time you created the
-template. Finally, you can make the class method call
-
- Text::Template->always_prepend('perl statements');
-
-If you do this, then call calls to C<fill_in> for I<any> template will
-attach the perl statements to the beginning of each program fragment,
-except where overridden by C<PREPEND> options to C<new> or C<fill_in>.
-
-=head2 Prepending in Derived Classes
-
-This section is technical, and you should skip it on the first few
-readings.
-
-Normally there are three places that prepended text could come from.
-It could come from the C<PREPEND> option in the C<fill_in> call, from
-the C<PREPEND> option in the C<new> call that created the template
-object, or from the argument of the C<always_prepend> call.
-C<Text::Template> looks for these three things in order and takes the
-first one that it finds.
-
-In a subclass of C<Text::Template>, this last possibility is
-ambiguous. Suppose C<S> is a subclass of C<Text::Template>. Should
-
- Text::Template->always_prepend(...);
-
-affect objects in class C<Derived>? The answer is that you can have it
-either way.
-
-The C<always_prepend> value for C<Text::Template> is normally stored
-in a hash variable named C<%GLOBAL_PREPEND> under the key
-C<Text::Template>. When C<Text::Template> looks to see what text to
-prepend, it first looks in the template object itself, and if not, it
-looks in C<$GLOBAL_PREPEND{I<class>}> where I<class> is the class to
-which the template object belongs. If it doesn't find any value, it
-looks in C<$GLOBAL_PREPEND{'Text::Template'}>. This means that
-objects in class C<Derived> I<will> be affected by
-
- Text::Template->always_prepend(...);
-
-I<unless> there is also a call to
-
- Derived->always_prepend(...);
-
-So when you're designing your derived class, you can arrange to have
-your objects ignore C<Text::Template::always_prepend> calls by simply
-putting C<Derived-E<gt>always_prepend('')> at the top of your module.
-
-Of course, there is also a final escape hatch: Templates support a
-C<prepend_text> that is used to look up the appropriate text to be
-prepended at C<fill_in> time. Your derived class can override this
-method to get an arbitrary effect.
-
-=head2 JavaScript
-
-Jennifer D. St Clair asks:
-
- > Most of my pages contain JavaScript and Stylesheets.
- > How do I change the template identifier?
-
-Jennifer is worried about the braces in the JavaScript being taken as
-the delimiters of the Perl program fragments. Of course, disaster
-will ensue when perl tries to evaluate these as if they were Perl
-programs. The best choice is to find some unambiguous delimiter
-strings that you can use in your template instead of curly braces, and
-then use the C<DELIMITERS> option. However, if you can't do this for
-some reason, there are two easy workarounds:
-
-1. You can put C<\> in front of C<{>, C<}>, or C<\> to remove its
-special meaning. So, for example, instead of
-
- if (br== "n3") {
- // etc.
- }
-
-you can put
-
- if (br== "n3") \{
- // etc.
- \}
-
-and it'll come out of the template engine the way you want.
-
-But here is another method that is probably better. To see how it
-works, first consider what happens if you put this into a template:
-
- { 'foo' }
-
-Since it's in braces, it gets evaluated, and obviously, this is going
-to turn into
-
- foo
-
-So now here's the trick: In Perl, C<q{...}> is the same as C<'...'>.
-So if we wrote
-
- {q{foo}}
-
-it would turn into
-
- foo
-
-So for your JavaScript, just write
-
- {q{if (br== "n3") {
- // etc.
- }}
- }
-
-and it'll come out as
-
- if (br== "n3") {
- // etc.
- }
-
-which is what you want.
-
-
-=head2 Shut Up!
-
-People sometimes try to put an initialization section at the top of
-their templates, like this:
-
- { ...
- $var = 17;
- }
-
-Then they complain because there is a C<17> at the top of the output
-that they didn't want to have there.
-
-Remember that a program fragment is replaced with its own return
-value, and that in Perl the return value of a code block is the value
-of the last expression that was evaluated, which in this case is 17.
-If it didn't do that, you wouldn't be able to write C<{$recipient}>
-and have the recipient filled in.
-
-To prevent the 17 from appearing in the output is very simple:
-
- { ...
- $var = 17;
- '';
- }
-
-Now the last expression evaluated yields the empty string, which is
-invisible. If you don't like the way this looks, use
-
- { ...
- $var = 17;
- ($SILENTLY);
- }
-
-instead. Presumably, C<$SILENTLY> has no value, so nothing will be
-interpolated. This is what is known as a `trick'.
-
-=head2 Compatibility
-
-Every effort has been made to make this module compatible with older
-versions. The only known exceptions follow:
-
-The output format of the default C<BROKEN> subroutine has changed
-twice, most recently between versions 1.31 and 1.40.
-
-Starting in version 1.10, the C<$OUT> variable is arrogated for a
-special meaning. If you had templates before version 1.10 that
-happened to use a variable named C<$OUT>, you will have to change them
-to use some other variable or all sorts of strangeness will result.
-
-Between versions 0.1b and 1.00 the behavior of the \ metacharacter
-changed. In 0.1b, \\ was special everywhere, and the template
-processor always replaced it with a single backslash before passing
-the code to Perl for evaluation. The rule now is more complicated but
-probably more convenient. See the section on backslash processing,
-below, for a full discussion.
-
-=head2 Backslash Processing
-
-In C<Text::Template> beta versions, the backslash was special whenever
-it appeared before a brace or another backslash. That meant that
-while C<{"\n"}> did indeed generate a newline, C<{"\\"}> did not
-generate a backslash, because the code passed to Perl for evaluation
-was C<"\"> which is a syntax error. If you wanted a backslash, you
-would have had to write C<{"\\\\"}>.
-
-In C<Text::Template> versions 1.00 through 1.10, there was a bug:
-Backslash was special everywhere. In these versions, C<{"\n"}>
-generated the letter C<n>.
-
-The bug has been corrected in version 1.11, but I did not go back to
-exactly the old rule, because I did not like the idea of having to
-write C<{"\\\\"}> to get one backslash. The rule is now more
-complicated to remember, but probably easier to use. The rule is now:
-Backslashes are always passed to Perl unchanged I<unless> they occur
-as part of a sequence like C<\\\\\\{> or C<\\\\\\}>. In these
-contexts, they are special; C<\\> is replaced with C<\>, and C<\{> and
-C<\}> signal a literal brace.
-
-Examples:
-
- \{ foo \}
-
-is I<not> evaluated, because the C<\> before the braces signals that
-they should be taken literally. The result in the output looks like this:
-
- { foo }
-
-
-This is a syntax error:
-
- { "foo}" }
-
-because C<Text::Template> thinks that the code ends at the first C<}>,
-and then gets upset when it sees the second one. To make this work
-correctly, use
-
- { "foo\}" }
-
-This passes C<"foo}"> to Perl for evaluation. Note there's no C<\> in
-the evaluated code. If you really want a C<\> in the evaluated code,
-use
-
- { "foo\\\}" }
-
-This passes C<"foo\}"> to Perl for evaluation.
-
-Starting with C<Text::Template> version 1.20, backslash processing is
-disabled if you use the C<DELIMITERS> option to specify alternative
-delimiter strings.
-
-=head2 A short note about C<$Text::Template::ERROR>
-
-In the past some people have fretted about `violating the package
-boundary' by examining a variable inside the C<Text::Template>
-package. Don't feel this way. C<$Text::Template::ERROR> is part of
-the published, official interface to this package. It is perfectly OK
-to inspect this variable. The interface is not going to change.
-
-If it really, really bothers you, you can import a function called
-C<TTerror> that returns the current value of the C<$ERROR> variable.
-So you can say:
-
- use Text::Template 'TTerror';
-
- my $template = new Text::Template (SOURCE => $filename);
- unless ($template) {
- my $err = TTerror;
- die "Couldn't make template: $err; aborting";
- }
-
-I don't see what benefit this has over just doing this:
-
- use Text::Template;
-
- my $template = new Text::Template (SOURCE => $filename)
- or die "Couldn't make template: $Text::Template::ERROR; aborting";
-
-But if it makes you happy to do it that way, go ahead.
-
-=head2 Sticky Widgets in Template Files
-
-The C<CGI> module provides functions for `sticky widgets', which are
-form input controls that retain their values from one page to the
-next. Sometimes people want to know how to include these widgets
-into their template output.
-
-It's totally straightforward. Just call the C<CGI> functions from
-inside the template:
-
- { $q->checkbox_group(NAME => 'toppings',
- LINEBREAK => true,
- COLUMNS => 3,
- VALUES => \@toppings,
- );
- }
-
-=head2 Automatic preprocessing of program fragments
-
-It may be useful to preprocess the program fragments before they are
-evaluated. See C<Text::Template::Preprocess> for more details.
-
-=head2 Automatic postprocessing of template hunks
-
-It may be useful to process hunks of output before they are appended to
-the result text. For this, subclass and replace the C<append_text_to_result>
-method. It is passed a list of pairs with these entries:
-
- handle - a filehandle to which to print the desired output
- out - a ref to a string to which to append, to use if handle is not given
- text - the text that will be appended
- type - where the text came from: TEXT for literal text, PROG for code
-
-=head2 Author
-
-Mark Jason Dominus, Plover Systems
-
-Please send questions and other remarks about this software to
-C<mjd-perl-template+@plover.com>
-
-You can join a very low-volume (E<lt>10 messages per year) mailing
-list for announcements about this package. Send an empty note to
-C<mjd-perl-template-request@plover.com> to join.
-
-For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
-
-=head2 Support?
-
-This software is version 1.46. It may have bugs. Suggestions and bug
-reports are always welcome. Send them to
-C<mjd-perl-template+@plover.com>. (That is my address, not the address
-of the mailing list. The mailing list address is a secret.)
-
-=head1 LICENSE
-
- Text::Template version 1.46
- Copyright 2013 Mark Jason Dominus
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License as
- published by the Free Software Foundation; either version 2 of the
- License, or (at your option) any later version. You may also can
- redistribute it and/or modify it under the terms of the Perl
- Artistic License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received copies of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-
-=head1 THANKS
-
-Many thanks to the following people for offering support,
-encouragement, advice, bug reports, and all the other good stuff.
-
-David H. Adler /
-Joel Appelbaum /
-Klaus Arnhold /
-AntE<oacute>nio AragE<atilde>o /
-Kevin Atteson /
-Chris.Brezil /
-Mike Brodhead /
-Tom Brown /
-Dr. Frank Bucolo /
-Tim Bunce /
-Juan E. Camacho /
-Itamar Almeida de Carvalho /
-Joseph Cheek /
-Gene Damon /
-San Deng /
-Bob Dougherty /
-Marek Grac /
-Dan Franklin /
-gary at dls.net /
-Todd A. Green /
-Donald L. Greer Jr. /
-Michelangelo Grigni /
-Zac Hansen /
-Tom Henry /
-Jarko Hietaniemi /
-Matt X. Hunter /
-Robert M. Ioffe /
-Daniel LaLiberte /
-Reuven M. Lerner /
-Trip Lilley /
-Yannis Livassof /
-Val Luck /
-Kevin Madsen /
-David Marshall /
-James Mastros /
-Joel Meulenberg /
-Jason Moore /
-Sergey Myasnikov /
-Chris Nandor /
-Bek Oberin /
-Steve Palincsar /
-Ron Pero /
-Hans Persson /
-Sean Roehnelt /
-Jonathan Roy /
-Shabbir J. Safdar /
-Jennifer D. St Clair /
-Uwe Schneider /
-Randal L. Schwartz /
-Michael G Schwern /
-Yonat Sharon /
-Brian C. Shensky /
-Niklas Skoglund /
-Tom Snee /
-Fred Steinberg /
-Hans Stoop /
-Michael J. Suzio /
-Dennis Taylor /
-James H. Thompson /
-Shad Todd /
-Lieven Tomme /
-Lorenzo Valdettaro /
-Larry Virden /
-Andy Wardley /
-Archie Warnock /
-Chris Wesley /
-Matt Womer /
-Andrew G Wood /
-Daini Xie /
-Michaely Yeung
-
-Special thanks to:
-
-=over 2
-
-=item Jonathan Roy
-
-for telling me how to do the C<Safe> support (I spent two years
-worrying about it, and then Jonathan pointed out that it was trivial.)
-
-=item Ranjit Bhatnagar
-
-for demanding less verbose fragments like they have in ASP, for
-helping me figure out the Right Thing, and, especially, for talking me
-out of adding any new syntax. These discussions resulted in the
-C<$OUT> feature.
-
-=back
-
-=head2 Bugs and Caveats
-
-C<my> variables in C<fill_in> are still susceptible to being clobbered
-by template evaluation. They all begin with C<fi_>, so avoid those
-names in your templates.
-
-The line number information will be wrong if the template's lines are
-not terminated by C<"\n">. You should let me know if this is a
-problem. If you do, I will fix it.
-
-The C<$OUT> variable has a special meaning in templates, so you cannot
-use it as if it were a regular variable.
-
-There are not quite enough tests in the test suite.
-
-=cut
+++ /dev/null
-
-package Text::Template::Preprocess;
-use Text::Template;
-@ISA = qw(Text::Template);
-$Text::Template::Preprocess::VERSION = 1.46;
-
-sub fill_in {
- my $self = shift;
- my (%args) = @_;
- my $pp = $args{PREPROCESSOR} || $self->{PREPROCESSOR} ;
- if ($pp) {
- local $_ = $self->source();
-# print "# fill_in: before <$_>\n";
- &$pp;
-# print "# fill_in: after <$_>\n";
- $self->set_source_data($_);
- }
- $self->SUPER::fill_in(@_);
-}
-
-sub preprocessor {
- my ($self, $pp) = @_;
- my $old_pp = $self->{PREPROCESSOR};
- $self->{PREPROCESSOR} = $pp if @_ > 1; # OK to pass $pp=undef
- $old_pp;
-}
-
-1;
-
-
-=head1 NAME
-
-Text::Template::Preprocess - Expand template text with embedded Perl
-
-=head1 VERSION
-
-This file documents C<Text::Template::Preprocess> version B<1.46>
-
-=head1 SYNOPSIS
-
- use Text::Template::Preprocess;
-
- my $t = Text::Template::Preprocess->new(...); # identical to Text::Template
-
- # Fill in template, but preprocess each code fragment with pp().
- my $result = $t->fill_in(..., PREPROCESSOR => \&pp);
-
- my $old_pp = $t->preprocessor(\&new_pp);
-
-=head1 DESCRIPTION
-
-C<Text::Template::Preprocess> provides a new C<PREPROCESSOR> option to
-C<fill_in>. If the C<PREPROCESSOR> option is supplied, it must be a
-reference to a preprocessor subroutine. When filling out a template,
-C<Text::Template::Preprocessor> will use this subroutine to preprocess
-the program fragment prior to evaluating the code.
-
-The preprocessor subroutine will be called repeatedly, once for each
-program fragment. The program fragment will be in C<$_>. The
-subroutine should modify the contents of C<$_> and return.
-C<Text::Template::Preprocess> will then execute contents of C<$_> and
-insert the result into the appropriate part of the template.
-
-C<Text::Template::Preprocess> objects also support a utility method,
-C<preprocessor()>, which sets a new preprocessor for the object. This
-preprocessor is used for all subsequent calls to C<fill_in> except
-where overridden by an explicit C<PREPROCESSOR> option.
-C<preprocessor()> returns the previous default preprocessor function,
-or undefined if there wasn't one. When invoked with no arguments,
-C<preprocessor()> returns the object's current default preprocessor
-function without changing it.
-
-In all other respects, C<Text::Template::Preprocess> is identical to
-C<Text::Template>.
-
-=head1 WHY?
-
-One possible purpose: If your files contain a lot of JavaScript, like
-this:
-
-
- Plain text here...
- { perl code }
- <script language=JavaScript>
- if (br== "n3") {
- // etc.
- }
- </script>
- { more perl code }
- More plain text...
-
-You don't want C<Text::Template> to confuse the curly braces in the
-JavaScript program with executable Perl code. One strategy:
-
- sub quote_scripts {
- s(<script(.*?)</script>)(q{$1})gsi;
- }
-
-Then use C<PREPROCESSOR =E<gt> \"e_scripts>. This will transform
-
-
-
-=head1 SEE ALSO
-
-L<Text::Template>
-
-=head1 AUTHOR
-
-
-Mark Jason Dominus, Plover Systems
-
-Please send questions and other remarks about this software to
-C<mjd-perl-template+@plover.com>
-
-You can join a very low-volume (E<lt>10 messages per year) mailing
-list for announcements about this package. Send an empty note to
-C<mjd-perl-template-request@plover.com> to join.
-
-For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
-
-=head1 LICENSE
-
- Text::Template::Preprocess version 1.46
- Copyright 2013 Mark Jason Dominus
-
- This program is free software; you can redistribute it and/or
- modify it under the terms of the GNU General Public License as
- published by the Free Software Foundation; either version 2 of the
- License, or (at your option) any later version. You may also can
- redistribute it and/or modify it under the terms of the Perl
- Artistic License.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received copies of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-
-=cut
-
+++ /dev/null
-#!perl
-
-use Text::Template;
-print "1..1\n";
-
-if ($Text::Template::VERSION == 1.46) {
- print "ok 1\n";
-} else {
- print "not ok 1\n";
-}
-
+++ /dev/null
-#!perl
-#
-# Tests of basic, essential functionality
-#
-
-use Text::Template;
-$X::v = $Y::v = 0; # Suppress `var used only once'
-
-print "1..31\n";
-
-$n=1;
-
-$template_1 = <<EOM;
-We will put value of \$v (which is "abc") here -> {\$v}
-We will evaluate 1+1 here -> {1 + 1}
-EOM
-
-# (1) Construct temporary template file for testing
-# file operations
-$TEMPFILE = "tt$$";
-open(TMP, "> $TEMPFILE") or print "not ok $n\n" && &abort("Couldn\'t write tempfile $TEMPFILE: $!");
-print TMP $template_1;
-close TMP;
-print "ok $n\n"; $n++;
-
-# (2) Build template from file
-$template = new Text::Template ('type' => 'FILE', 'source' => $TEMPFILE);
-if (defined($template)) {
- print "ok $n\n";
-} else {
- print "not ok $n $Text::Template::ERROR\n";
-}
-$n++;
-
-# (3) Fill in template from file
-$X::v = "abc";
-$resultX = <<EOM;
-We will put value of \$v (which is "abc") here -> abc
-We will evaluate 1+1 here -> 2
-EOM
-$Y::v = "ABC";
-$resultY = <<EOM;
-We will put value of \$v (which is "abc") here -> ABC
-We will evaluate 1+1 here -> 2
-EOM
-
-$text = $template->fill_in('package' => X);
-if ($text eq $resultX) {
- print "ok $n\n";
-} else {
- print "not ok $n\n";
-}
-$n++;
-
-# (4) Fill in same template again
-$text = $template->fill_in('package' => Y);
-if ($text eq $resultY) {
- print "ok $n\n";
-} else {
- print "not ok $n\n";
-}
-$n++;
-
-
-
-# (5) Simple test of `fill_this_in'
-$text = Text::Template->fill_this_in( $template_1, 'package' => X);
-if ($text eq $resultX) {
- print "ok $n\n";
-} else {
- print "not ok $n\n";
-}
-$n++;
-
-# (6) test creation of template from filehandle
-if (open (TMPL, "< $TEMPFILE")) {
- $template = new Text::Template ('type' => 'FILEHANDLE',
- 'source' => *TMPL);
- if (defined($template)) {
- print "ok $n\n";
- } else {
- print "not ok $n $Text::Template::ERROR\n";
- }
- $n++;
-
-# (7) test filling in of template from filehandle
- $text = $template->fill_in('package' => X);
- if ($text eq $resultX) {
- print "ok $n\n";
- } else {
- print "not ok $n\n";
- }
- $n++;
-
-# (8) test second fill_in on same template object
- $text = $template->fill_in('package' => Y);
- if ($text eq $resultY) {
- print "ok $n\n";
- } else {
- print "not ok $n\n";
- }
- $n++;
- close TMPL;
-} else {
- print "not ok $n\n"; $n++;
- print "not ok $n\n"; $n++;
- print "not ok $n\n"; $n++;
-}
-
-
-# (9) test creation of template from array
-$template = new Text::Template
- ('type' => 'ARRAY',
- 'source' => [
- 'We will put value of $v (which is "abc") here -> {$v}',
- "\n",
- 'We will evaluate 1+1 here -> {1+1}',
- "\n",
- ]);
-if (defined($template)) {
- print "ok $n\n";
-} else {
- print "not ok $n $Text::Template::ERROR\n";
-}
-$n++;
-
-# (10) test filling in of template from array
-$text = $template->fill_in('package' => X);
-if ($text eq $resultX) {
- print "ok $n\n";
-} else {
- print "not ok $n\n";
-}
-$n++;
-
-# (11) test second fill_in on same array template object
-$text = $template->fill_in('package' => Y);
-if ($text eq $resultY) {
- print "ok $n\n";
-} else {
- print "not ok $n\n";
- print STDERR "$resultX\n---\n$text";
- unless (!defined($text)) { print STDERR "ERROR: $Text::Template::ERROR\n"};
-}
-$n++;
-
-
-
-# (12) Make sure \ is working properly
-# Test added for version 1.11
-my $tmpl = Text::Template->new(TYPE => 'STRING',
- SOURCE => 'B{"\\}"}C{"\\{"}D',
- );
-# This should fail if the \ are not interpreted properly.
-my $text = $tmpl->fill_in();
-print +($text eq "B}C{D" ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (13) Make sure \ is working properly
-# Test added for version 1.11
-$tmpl = Text::Template->new(TYPE => 'STRING',
- SOURCE => qq{A{"\t"}B},
- );
-# Symptom of old problem: ALL \ were special in templates, so
-# The lexer would return (A, PROGTEXT("t"), B), and the
-# result text would be AtB instead of A(tab)B.
-$text = $tmpl->fill_in();
-
-print +($text eq "A\tB" ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (14-27) Make sure \ is working properly
-# Test added for version 1.11
-# This is a sort of general test.
-my @tests = ('{""}' => '', # (14)
- '{"}"}' => undef, # (15)
- '{"\\}"}' => '}', # One backslash
- '{"\\\\}"}' => undef, # Two backslashes
- '{"\\\\\\}"}' => '}', # Three backslashes
- '{"\\\\\\\\}"}' => undef, # Four backslashes
- '{"\\\\\\\\\\}"}' => '\}', # Five backslashes (20)
- '{"x20"}' => 'x20',
- '{"\\x20"}' => ' ', # One backslash
- '{"\\\\x20"}' => '\\x20', # Two backslashes
- '{"\\\\\\x20"}' => '\\ ', # Three backslashes
- '{"\\\\\\\\x20"}' => '\\\\x20', # Four backslashes (25)
- '{"\\\\\\\\\\x20"}' => '\\\\ ', # Five backslashes
- '{"\\x20\\}"}' => ' }', # (27)
- );
-
-my $i;
-for ($i=0; $i<@tests; $i+=2) {
- my $tmpl = Text::Template->new(TYPE => 'STRING',
- SOURCE => $tests[$i],
- );
- my $text = $tmpl->fill_in;
- my $result = $tests[$i+1];
- my $ok = (! defined $text && ! defined $result
- || $text eq $result);
- unless ($ok) {
- print STDERR "($n) expected .$result., got .$text.\n";
- }
- print +($ok ? '' : 'not '), "ok $n\n";
- $n++;
-}
-
-
-# (28-30) I discovered that you can't pass a glob ref as your filehandle.
-# MJD 20010827
-# (28) test creation of template from filehandle
-if (open (TMPL, "< $TEMPFILE")) {
- $template = new Text::Template ('type' => 'FILEHANDLE',
- 'source' => \*TMPL);
- if (defined($template)) {
- print "ok $n\n";
- } else {
- print "not ok $n $Text::Template::ERROR\n";
- }
- $n++;
-
-# (29) test filling in of template from filehandle
- $text = $template->fill_in('package' => X);
- if ($text eq $resultX) {
- print "ok $n\n";
- } else {
- print "not ok $n\n";
- }
- $n++;
-
-# (30) test second fill_in on same template object
- $text = $template->fill_in('package' => Y);
- if ($text eq $resultY) {
- print "ok $n\n";
- } else {
- print "not ok $n\n";
- }
- $n++;
- close TMPL;
-} else {
- print "not ok $n\n"; $n++;
- print "not ok $n\n"; $n++;
- print "not ok $n\n"; $n++;
-}
-
-# (31) Test _scrubpkg for leakiness
-$Text::Template::GEN0::test = 1;
-Text::Template::_scrubpkg('Text::Template::GEN0');
-if ($Text::Template::GEN0::test) {
- print "not ok $n\n";
-} else {
- print "ok $n\n";
-}
-$n++;
-
-
-END {unlink $TEMPFILE;}
-
-exit;
-
-
-
-
-sub abort {
- unlink $TEMPFILE;
- die $_[0];
-}
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-
-print "1..12\n";
-
-$n=1;
-
-$template = 'We will put value of $v (which is "good") here -> {$v}';
-
-$v = 'oops (main)';
-$Q::v = 'oops (Q)';
-
-$vars = { 'v' => \'good' };
-
-# (1) Build template from string
-$template = new Text::Template ('type' => 'STRING', 'source' => $template);
-print +($template ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (2) Fill in template in anonymous package
-$result2 = 'We will put value of $v (which is "good") here -> good';
-$text = $template->fill_in(HASH => $vars);
-print +($text eq $result2 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (3) Did we clobber the main variable?
-print +($v eq 'oops (main)' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (4) Fill in same template again
-$result4 = 'We will put value of $v (which is "good") here -> good';
-$text = $template->fill_in(HASH => $vars);
-print +($text eq $result4 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (5) Now with a package
-$result5 = 'We will put value of $v (which is "good") here -> good';
-$text = $template->fill_in(HASH => $vars, PACKAGE => 'Q');
-print +($text eq $result5 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (6) We expect to have clobbered the Q variable.
-print +($Q::v eq 'good' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (7) Now let's try it without a package
-$result7 = 'We will put value of $v (which is "good") here -> good';
-$text = $template->fill_in(HASH => $vars);
-print +($text eq $result7 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (8-11) Now what does it do when we pass a hash with undefined values?
-# Roy says it does something bad. (Added for 1.20.)
-my $WARNINGS = 0;
-{
- local $SIG{__WARN__} = sub {$WARNINGS++};
- local $^W = 1; # Make sure this is on for this test
- $template8 = 'We will put value of $v (which is "good") here -> {defined $v ? "bad" : "good"}';
- $result8 = 'We will put value of $v (which is "good") here -> good';
- my $template =
- new Text::Template ('type' => 'STRING', 'source' => $template8);
- my $text = $template->fill_in(HASH => {'v' => undef});
- # (8) Did we generate a warning?
- print +($WARNINGS == 0 ? '' : 'not '), "ok $n\n";
- $n++;
-
- # (9) Was the output correct?
- print +($text eq $result8 ? '' : 'not '), "ok $n\n";
- $n++;
-
- # (10-11) Let's try that again, with a twist this time
- $WARNINGS = 0;
- $text = $template->fill_in(HASH => [{'v' => 17}, {'v' => undef}]);
- # (10) Did we generate a warning?
- print +($WARNINGS == 0 ? '' : 'not '), "ok $n\n";
- $n++;
-
- # (11) Was the output correct?
- if ($] < 5.005) {
- print "ok $n # skipped -- not supported before 5.005\n";
- } else {
- print +($text eq $result8 ? '' : 'not '), "ok $n\n";
- }
- $n++;
-}
-
-
-# (12) Now we'll test the multiple-hash option (Added for 1.20.)
-$text = Text::Template::fill_in_string(q{$v: {$v}. @v: [{"@v"}].},
- HASH => [{'v' => 17},
- {'v' => ['a', 'b', 'c']},
- {'v' => \23},
- ]);
-$result = q{$v: 23. @v: [a b c].};
-print +($text eq $result ? '' : 'not '), "ok $n\n";
-$n++;
-
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-#
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..1\n";
-
-$n=1;
-
-$template = q{
-This line should have a 3: {1+2}
-
-This line should have several numbers:
-{ $t = ''; foreach $n (1 .. 20) { $t .= $n . ' ' } $t }
-};
-
-$templateOUT = q{
-This line should have a 3: { $OUT = 1+2 }
-
-This line should have several numbers:
-{ foreach $n (1 .. 20) { $OUT .= $n . ' ' } }
-};
-
-# Build templates from string
-$template = new Text::Template ('type' => 'STRING', 'source' => $template)
- or die;
-$templateOUT = new Text::Template ('type' => 'STRING', 'source' => $templateOUT)
- or die;
-
-# Fill in templates
-$text = $template->fill_in()
- or die;
-$textOUT = $templateOUT->fill_in()
- or die;
-
-# (1) They should be the same
-print +($text eq $textOUT ? '' : 'not '), "ok $n\n";
-$n++;
-
-# Missing: Test this feature in Safe compartments;
-# it's a totally different code path.
-# Decision: Put that into safe.t, because that file should
-# be skipped when Safe.pm is unavailable.
-
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template;
-
-BEGIN {
- eval "use Safe";
- if ($@) {
- print "1..0\n";
- exit 0;
- }
-}
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..16\n";
-
-if ($^O eq 'MacOS') {
- $BADOP = qq{};
- $FAILURE = q{};
-} else {
- $BADOP = qq{kill 0};
- $FAILURE = q{Program fragment at line 1 delivered error ``kill trapped by operation mask''};
-}
-
-$n=1;
-$v = $v = 119;
-
-$c = new Safe or die;
-
-$goodtemplate = q{This should succeed: { $v }};
-$goodoutput = q{This should succeed: 119};
-
-$template1 = new Text::Template ('type' => 'STRING', 'source' => $goodtemplate)
- or die;
-$template2 = new Text::Template ('type' => 'STRING', 'source' => $goodtemplate)
- or die;
-
-$text1 = $template1->fill_in();
-$text2 = $template1->fill_in(SAFE => $c);
-$ERR2 = $@;
-$text3 = $template2->fill_in(SAFE => $c);
-$ERR3 = $@;
-
-# (1)(2)(3) None of these should have failed.
-print +(defined $text1 ? '' : 'not '), "ok $n\n";
-$n++;
-print +(defined $text2 ? '' : 'not '), "ok $n\n";
-$n++;
-print +(defined $text3 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (4) Safe and non-safe fills of different template objects with the
-# same template text should yield the same result.
-# print +($text1 eq $text3 ? '' : 'not '), "ok $n\n";
-# (4) voided this test: it's not true, because the unsafe fill
-# uses package main, while the safe fill uses the secret safe package.
-# We could alias the secret safe package to be identical to main,
-# but that wouldn't be safe. If you want the aliasing, you have to
-# request it explicitly with `PACKAGE'.
-print "ok $n\n";
-$n++;
-
-# (5) Safe and non-safe fills of the same template object
-# should yield the same result.
-# (5) voided this test for the same reason as #4.
-# print +($text1 eq $text2 ? '' : 'not '), "ok $n\n";
-print "ok $n\n";
-$n++;
-
-# (6) Make sure the output was actually correct
-print +($text1 eq $goodoutput ? '' : 'not '), "ok $n\n";
-$n++;
-
-
-$badtemplate = qq{This should fail: { $BADOP; 'NOFAIL' }};
-$badnosafeoutput = q{This should fail: NOFAIL};
-$badsafeoutput = q{This should fail: Program fragment delivered error ``kill trapped by operation mask at template line 1.''};
-
-$template1 = new Text::Template ('type' => 'STRING', 'source' => $badtemplate)
- or die;
-$template2 = new Text::Template ('type' => 'STRING', 'source' => $badtemplate)
- or die;
-
-$text1 = $template1->fill_in();
-$text2 = $template1->fill_in(SAFE => $c);
-$ERR2 = $@;
-$text3 = $template2->fill_in(SAFE => $c);
-$ERR3 = $@;
-$text4 = $template1->fill_in();
-
-# (7)(8)(9)(10) None of these should have failed.
-print +(defined $text1 ? '' : 'not '), "ok $n\n";
-$n++;
-print +(defined $text2 ? '' : 'not '), "ok $n\n";
-$n++;
-print +(defined $text3 ? '' : 'not '), "ok $n\n";
-$n++;
-print +(defined $text4 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (11) text1 and text4 should be the same (using safe in between
-# didn't change anything.)
-print +($text1 eq $text4 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (12) text2 and text3 should be the same (same template text in different
-# objects
-print +($text2 eq $text3 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (13) text1 should yield badnosafeoutput
-print +($text1 eq $badnosafeoutput ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (14) text2 should yield badsafeoutput
-$text2 =~ s/'kill'/kill/; # 5.8.1 added quote marks around the op name
-print "# expected: <$badsafeoutput>\n# got : <$text2>\n";
-print +($text2 eq $badsafeoutput ? '' : 'not '), "ok $n\n";
-$n++;
-
-
-$template = q{{$x=1}{$x+1}};
-
-$template1 = new Text::Template ('type' => 'STRING', 'source' => $template)
- or die;
-$template2 = new Text::Template ('type' => 'STRING', 'source' => $template)
- or die;
-
-$text1 = $template1->fill_in();
-$text2 = $template1->fill_in(SAFE => new Safe);
-
-# (15) Do effects persist in safe compartments?
-print +($text1 eq $text2 ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (16) Try the BROKEN routine in safe compartments
-sub my_broken {
- my %a = @_; $a{error} =~ s/ at.*//s;
- "OK! text:$a{text} error:$a{error} lineno:$a{lineno} arg:$a{arg}" ;
-}
-$templateB = new Text::Template (TYPE => 'STRING', SOURCE => '{die}')
- or die;
-$text1 = $templateB->fill_in(BROKEN => \&my_broken,
- BROKEN_ARG => 'barg',
- SAFE => new Safe,
- );
-$result1 = qq{OK! text:die error:Died lineno:1 arg:barg};
-print +($text1 eq $result1 ? '' : 'not '), "ok $n\n";
-$n++;
-
-
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template;
-
-BEGIN {
- eval "use Safe";
- if ($@) {
- print "1..0\n";
- exit 0;
- }
-}
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..12\n";
-$n = 1;
-
-$c = new Safe or die;
-
-# Test handling of packages and importing.
-$c->reval('$P = "safe root"');
-$P = $P = 'main';
-$Q::P = $Q::P = 'Q';
-
-# How to effectively test the gensymming?
-
-$t = new Text::Template TYPE => 'STRING', SOURCE => 'package is {$P}'
- or die;
-
-# (1) Default behavior: Inherit from calling package, `main' in this case.
-$text = $t->fill_in();
-print +($text eq 'package is main' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (2) When a package is specified, we should use that package instead.
-$text = $t->fill_in(PACKAGE => 'Q');
-print +($text eq 'package is Q' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (3) When no package is specified in safe mode, we should use the
-# default safe root.
-$text = $t->fill_in(SAFE => $c);
-print +($text eq 'package is safe root' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (4) When a package is specified in safe mode, we should use the
-# default safe root, after aliasing to the specified package
-$text = $t->fill_in(SAFE => $c, PACKAGE => Q);
-print +($text eq 'package is Q' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# Now let's see if hash vars are installed properly into safe templates
-$t = new Text::Template TYPE => 'STRING', SOURCE => 'hash is {$H}'
- or die;
-
-# (5) First in default mode
-$text = $t->fill_in(HASH => {H => 'good5'} );
-print +($text eq 'hash is good5' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (6) Now in packages
-$text = $t->fill_in(HASH => {H => 'good6'}, PACKAGE => 'Q' );
-print +($text eq 'hash is good6' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (7) Now in the default root of the safe compartment
-$text = $t->fill_in(HASH => {H => 'good7'}, SAFE => $c );
-print +($text eq 'hash is good7' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (8) Now in the default root after aliasing to a package that
-# got the hash stuffed in
-$text = $t->fill_in(HASH => {H => 'good8'}, SAFE => $c, PACKAGE => 'Q2' );
-print +($text eq 'hash is good8' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# Now let's make sure that none of the packages leaked on each other.
-# (9) This var should NOT have been installed into the main package
-print +(defined $H ? 'not ' : ''), "ok $n\n";
-$H=$H;
-$n++;
-
-# (10) good6 was overwritten in test 7, so there's nothing to test for here.
-print "ok $n\n";
-$n++;
-
-# (11) this value overwrote the one from test 6.
-print +($Q::H eq 'good7' ? '' : 'not '), "ok $n\n";
-$Q::H = $Q::H;
-$n++;
-
-# (12)
-print +($Q2::H eq 'good8' ? '' : 'not '), "ok $n\n";
-$Q2::H = $Q2::H;
-$n++;
-
-
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..2\n";
-
-$n=1;
-
-$template = new Text::Template TYPE => STRING, SOURCE => q{My process ID is {$$}};
-$of = "t$$";
-END { unlink $of }
-open O, "> $of" or die;
-
-$text = $template->fill_in(OUTPUT => \*O);
-
-# (1) No $text should have been constructed. Return value should be true.
-print +($text eq '1' ? '' : 'not '), "ok $n\n";
-$n++;
-
-close O or die;
-open I, "< $of" or die;
-{ local $/; $t = <I> }
-close I;
-
-# (2) The text should have been printed to the file
-print +($t eq "My process ID is $$" ? '' : 'not '), "ok $n\n";
-$n++;
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-
-use Text::Template;
-
-BEGIN {
- eval "use Safe";
- if ($@) {
- print "1..0\n";
- exit 0;
- }
-}
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..3\n";
-
-$n=1;
-
-# Test the OUT feature with safe compartments
-
-$template = q{
-This line should have a 3: {1+2}
-
-This line should have several numbers:
-{ $t = ''; foreach $n (1 .. 20) { $t .= $n . ' ' } $t }
-};
-
-$templateOUT = q{
-This line should have a 3: { $OUT = 1+2 }
-
-This line should have several numbers:
-{ foreach $n (1 .. 20) { $OUT .= $n . ' ' } }
-};
-
-$c = new Safe;
-
-# Build templates from string
-$template = new Text::Template ('type' => 'STRING', 'source' => $template,
- SAFE => $c)
- or die;
-$templateOUT = new Text::Template ('type' => 'STRING', 'source' => $templateOUT,
- SAFE => $c)
- or die;
-
-# Fill in templates
-$text = $template->fill_in()
- or die;
-$textOUT = $templateOUT->fill_in()
- or die;
-
-# (1) They should be the same
-print +($text eq $textOUT ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (2-3) "Joel Appelbaum" <joel@orbz.com> <000701c0ac2c$aed1d6e0$0201a8c0@prime>
-# "Contrary to the documentation the $OUT variable is not always
-# undefined at the start of each program fragment. The $OUT variable
-# is never undefined after it is used once if you are using the SAFE
-# option. The result is that every fragment after the fragment that
-# $OUT was used in is replaced by the old $OUT value instead of the
-# result of the fragment. This holds true even after the
-# Text::Template object goes out of scope and a new one is created!"
-#
-# Also reported by Daini Xie.
-
-{
- my $template = q{{$OUT = 'x'}y{$OUT .= 'z'}};
- my $expected = "xyz";
- my $s = Safe->new;
- my $o = Text::Template->new(type => 'string',
- source => $template,
- );
- for (1..2) {
- my $r = $o->fill_in(SAFE => $s);
- if ($r ne $expected) {
- print "not ok $n # <$r>\n";
- } else {
- print "ok $n\n";
- }
- $n++;
- }
-}
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template 'fill_in_file', 'fill_in_string';
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..6\n";
-
-$n=1;
-$Q::n = $Q::n = 119;
-
-# (1) Test fill_in_string
-$out = fill_in_string('The value of $n is {$n}.', PACKAGE => 'Q' );
-print +($out eq 'The value of $n is 119.' ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (2) Test fill_in_file
-$TEMPFILE = "tt$$";
-open F, "> $TEMPFILE" or die "Couldn't open test file: $!; aborting";
-print F 'The value of $n is {$n}.', "\n";
-close F or die "Couldn't write test file: $!; aborting";
-$R::n = $R::n = 8128;
-
-$out = fill_in_file($TEMPFILE, PACKAGE => 'R');
-print +($out eq "The value of \$n is 8128.\n" ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (3) Jonathan Roy reported this bug:
-open F, "> $TEMPFILE" or die "Couldn't open test file: $!; aborting";
-print F "With a message here? [% \$var %]\n";
-close F or die "Couldn't close test file: $!; aborting";
-$out = fill_in_file($TEMPFILE, DELIMITERS => ['[%', '%]'],
- HASH => { "var" => \"It is good!" });
-print +($out eq "With a message here? It is good!\n" ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (4) It probably occurs in fill_this_in also:
-$out =
- Text::Template->fill_this_in("With a message here? [% \$var %]\n",
- DELIMITERS => ['[%', '%]'],
- HASH => { "var" => \"It is good!" });
-print +($out eq "With a message here? It is good!\n" ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (5) This test failed in 1.25. It was supplied by Donald L. Greer Jr.
-# Note that it's different from (1) in that there's no explicit
-# package=> argument.
-use vars qw($string $foo $r);
-$string='Hello {$foo}';
-$foo="Don";
-$r = fill_in_string($string);
-print (($r eq 'Hello Don' ? '' : 'not '), 'ok ', $n++, "\n");
-
-# (6) This test failed in 1.25. It's a variation on (5)
-package Q2;
-use Text::Template 'fill_in_string';
-use vars qw($string $foo $r);
-$string='Hello {$foo}';
-$foo="Don";
-$r = fill_in_string($string);
-print (($r eq 'Hello Don' ? '' : 'not '), 'ok ', $main::n++, "\n");
-
-package main;
-
-END { $TEMPFILE && unlink $TEMPFILE }
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# test apparatus for Text::Template module
-# still incomplete.
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..5\n";
-$n = 1;
-
-# (1-2) Missing source
-eval {
- Text::Template->new();
-};
-unless ($@ =~ /^\QUsage: Text::Template::new(TYPE => ..., SOURCE => ...)/) {
- print STDERR $@;
- print "not ";
-}
-print "ok $n\n";
-$n++;
-
-eval {
- Text::Template->new(TYPE => 'FILE');
-};
-if ($@ =~ /^\QUsage: Text::Template::new(TYPE => ..., SOURCE => ...)/) {
- print "ok $n\n";
-} else {
- print STDERR $@;
- print "not ok $n\n";
-}
-$n++;
-
-# (3) Invalid type
-eval {
- Text::Template->new(TYPE => 'wlunch', SOURCE => 'fish food');
-};
-if ($@ =~ /^\QIllegal value `WLUNCH' for TYPE parameter/) {
- print "ok $n\n";
-} else {
- print STDERR $@;
- print "not ok $n\n";
-}
-$n++;
-
-# (4-5) File does not exist
-my $o = Text::Template->new(TYPE => 'file',
- SOURCE => 'this file does not exist');
-print $o ? "not ok $n\n" : "ok $n\n";
-$n++;
-print defined($Text::Template::ERROR)
- && $Text::Template::ERROR =~ /^Couldn't open file/
- ? "ok $n\n" : "not ok $n\n";
-$n++;
-
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# Tests for user-specified delimiter functions
-# These tests first appeared in version 1.20.
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..18\n";
-$n = 1;
-
-# (1) Try a simple delimiter: <<..>>
-# First with the delimiters specified at object creation time
-$V = $V = 119;
-$template = q{The value of $V is <<$V>>.};
-$result = q{The value of $V is 119.};
-$template1 = Text::Template->new(TYPE => STRING,
- SOURCE => $template,
- DELIMITERS => ['<<', '>>']
- )
- or die "Couldn't construct template object: $Text::Template::ERROR; aborting";
-$text = $template1->fill_in();
-print +($text eq $result ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (2) Now with delimiter choice deferred until fill-in time.
-$template1 = Text::Template->new(TYPE => STRING, SOURCE => $template);
-$text = $template1->fill_in(DELIMITERS => ['<<', '>>']);
-print +($text eq $result ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (3) Now we'll try using regex metacharacters
-# First with the delimiters specified at object creation time
-$template = q{The value of $V is [$V].};
-$template1 = Text::Template->new(TYPE => STRING,
- SOURCE => $template,
- DELIMITERS => ['[', ']']
- )
- or die "Couldn't construct template object: $Text::Template::ERROR; aborting";
-$text = $template1->fill_in();
-print +($text eq $result ? '' : 'not '), "ok $n\n";
-$n++;
-
-# (4) Now with delimiter choice deferred until fill-in time.
-$template1 = Text::Template->new(TYPE => STRING, SOURCE => $template);
-$text = $template1->fill_in(DELIMITERS => ['[', ']']);
-print +($text eq $result ? '' : 'not '), "ok $n\n";
-$n++;
-
-
-
-# (5-18) Make sure \ is working properly
-# (That is to say, it is ignored.)
-# These tests are similar to those in 01-basic.t.
-my @tests = ('{""}' => '', # (5)
-
- # Backslashes don't matter
- '{"}"}' => undef,
- '{"\\}"}' => undef, # One backslash
- '{"\\\\}"}' => undef, # Two backslashes
- '{"\\\\\\}"}' => undef, # Three backslashes
- '{"\\\\\\\\}"}' => undef, # Four backslashes (10)
- '{"\\\\\\\\\\}"}' => undef, # Five backslashes
-
- # Backslashes are always passed directly to Perl
- '{"x20"}' => 'x20',
- '{"\\x20"}' => ' ', # One backslash
- '{"\\\\x20"}' => '\\x20', # Two backslashes
- '{"\\\\\\x20"}' => '\\ ', # Three backslashes (15)
- '{"\\\\\\\\x20"}' => '\\\\x20', # Four backslashes
- '{"\\\\\\\\\\x20"}' => '\\\\ ', # Five backslashes
- '{"\\x20\\}"}' => undef, # (18)
- );
-
-my $i;
-for ($i=0; $i<@tests; $i+=2) {
- my $tmpl = Text::Template->new(TYPE => 'STRING',
- SOURCE => $tests[$i],
- DELIMITERS => ['{', '}'],
- );
- my $text = $tmpl->fill_in;
- my $result = $tests[$i+1];
- my $ok = (! defined $text && ! defined $result
- || $text eq $result);
- unless ($ok) {
- print STDERR "($n) expected .$result., got .$text.\n";
- }
- print +($ok ? '' : 'not '), "ok $n\n";
- $n++;
-}
-
-
-exit;
-
+++ /dev/null
-#!perl
-#
-# Tests for PREPEND features
-# These tests first appeared in version 1.22.
-
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-print "1..9\n";
-my $n = 1;
-
-@Emptyclass1::ISA = 'Text::Template';
-@Emptyclass2::ISA = 'Text::Template';
-
-my $tin = q{The value of $foo is: {$foo}};
-
-Text::Template->always_prepend(q{$foo = "global"});
-
-$tmpl1 = Text::Template->new(TYPE => 'STRING',
- SOURCE => $tin,
- );
-
-$tmpl2 = Text::Template->new(TYPE => 'STRING',
- SOURCE => $tin,
- PREPEND => q{$foo = "template"},
- );
-
-$tmpl1->compile;
-$tmpl2->compile;
-
-$t1 = $tmpl1->fill_in(PACKAGE => 'T1');
-$t2 = $tmpl2->fill_in(PACKAGE => 'T2');
-$t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T3');
-
-($t1 eq 'The value of $foo is: global') or print "not ";
-print "ok $n\n"; $n++;
-($t2 eq 'The value of $foo is: template') or print "not ";
-print "ok $n\n"; $n++;
-($t3 eq 'The value of $foo is: fillin') or print "not ";
-print "ok $n\n"; $n++;
-
-Emptyclass1->always_prepend(q{$foo = 'Emptyclass global';});
-$tmpl1 = Emptyclass1->new(TYPE => 'STRING',
- SOURCE => $tin,
- );
-
-$tmpl2 = Emptyclass1->new(TYPE => 'STRING',
- SOURCE => $tin,
- PREPEND => q{$foo = "template"},
- );
-
-$tmpl1->compile;
-$tmpl2->compile;
-
-$t1 = $tmpl1->fill_in(PACKAGE => 'T4');
-$t2 = $tmpl2->fill_in(PACKAGE => 'T5');
-$t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T6');
-
-($t1 eq 'The value of $foo is: Emptyclass global') or print "not ";
-print "ok $n\n"; $n++;
-($t2 eq 'The value of $foo is: template') or print "not ";
-print "ok $n\n"; $n++;
-($t3 eq 'The value of $foo is: fillin') or print "not ";
-print "ok $n\n"; $n++;
-
-$tmpl1 = Emptyclass2->new(TYPE => 'STRING',
- SOURCE => $tin,
- );
-
-$tmpl2 = Emptyclass2->new(TYPE => 'STRING',
- SOURCE => $tin,
- PREPEND => q{$foo = "template"},
- );
-
-$tmpl1->compile;
-$tmpl2->compile;
-
-$t1 = $tmpl1->fill_in(PACKAGE => 'T4');
-$t2 = $tmpl2->fill_in(PACKAGE => 'T5');
-$t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T6');
-
-($t1 eq 'The value of $foo is: global') or print "not ";
-print "ok $n\n"; $n++;
-($t2 eq 'The value of $foo is: template') or print "not ";
-print "ok $n\n"; $n++;
-($t3 eq 'The value of $foo is: fillin') or print "not ";
-print "ok $n\n"; $n++;
-
-
+++ /dev/null
-#!perl
-#
-# Tests for PREPROCESSOR features
-# These tests first appeared in version 1.25.
-
-use Text::Template::Preprocess;
-
-die "This is the test program for Text::Template::Preprocess version 1.46.
-You are using version $Text::Template::Preprocess::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::Preprocess::VERSION == 1.46;
-
-$TMPFILE = "tt$$";
-
-print "1..8\n";
-my $n = 1;
-
-my $py = sub { tr/x/y/ };
-my $pz = sub { tr/x/z/ };
-
-my $t = 'xxx The value of $x is {$x}';
-my $outx = 'xxx The value of $x is 119';
-my $outy = 'yyy The value of $y is 23';
-my $outz = 'zzz The value of $z is 5';
-open TF, "> $TMPFILE" or die "Couldn't open test file: $!; aborting";
-print TF $t;
-close TF;
-
-@result = ($outx, $outy, $outz, $outz);
-for my $trial (1, 0) {
- for my $test (0 .. 3) {
- my $tmpl;
- if ($trial == 0) {
- $tmpl = new Text::Template::Preprocess
- (TYPE => 'STRING', SOURCE => $t) or die;
- } else {
- open TF, "< $TMPFILE" or die "Couldn't open test file: $!; aborting";
- $tmpl = new Text::Template::Preprocess
- (TYPE => 'FILEHANDLE', SOURCE => \*TF) or die;
- }
- $tmpl->preprocessor($py) if ($test & 1) == 1;
- my @args = ((($test & 2) == 2) ? (PREPROCESSOR => $pz) : ());
- my $o = $tmpl->fill_in(@args,
- HASH => {x => 119, 'y' => 23, z => 5});
-# print STDERR "$o/$result[$test]\n";
- print +(($o eq $result[$test]) ? '' : 'not '), "ok $n\n";
- $n++;
- }
-}
-
-unlink $TMPFILE;
+++ /dev/null
-#!perl -T
-# Tests for taint-mode features
-
-use lib 'blib/lib';
-use Text::Template;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-my $r = int(rand(10000));
-my $file = "tt$r";
-
-# makes its arguments tainted
-sub taint {
- for (@_) {
- $_ .= substr($0,0,0); # LOD
- }
-}
-
-
-print "1..21\n";
-
-my $n =1;
-print "ok ", $n++, "\n";
-
-my $template = 'The value of $n is {$n}.';
-
-open T, "> $file" or die "Couldn't write temporary file $file: $!";
-print T $template, "\n";
-close T or die "Couldn't finish temporary file $file: $!";
-
-sub should_fail {
- my $obj = Text::Template->new(@_);
- eval {$obj->fill_in()};
- if ($@) {
- print "ok $n # $@\n";
- } else {
- print "not ok $n # (didn't fail)\n";
- }
- $n++;
-}
-
-sub should_work {
- my $obj = Text::Template->new(@_);
- eval {$obj->fill_in()};
- if ($@) {
- print "not ok $n # $@\n";
- } else {
- print "ok $n\n";
- }
- $n++;
-}
-
-sub should_be_tainted {
- if (Text::Template::_is_clean($_[0])) {
- print "not ok $n\n"; $n++; return;
- }
- print "ok $n\n"; $n++; return;
-}
-
-sub should_be_clean {
- unless (Text::Template::_is_clean($_[0])) {
- print "not ok $n\n"; $n++; return;
- }
- print "ok $n\n"; $n++; return;
-}
-
-# Tainted filename should die with and without UNTAINT option
-# untainted filename should die without UNTAINT option
-# filehandle should die without UNTAINT option
-# string and array with tainted data should die either way
-
-# (2)-(7)
-my $tfile = $file;
-taint($tfile);
-should_be_tainted($tfile);
-should_be_clean($file);
-should_fail TYPE => 'file', SOURCE => $tfile;
-should_fail TYPE => 'file', SOURCE => $tfile, UNTAINT => 1;
-should_fail TYPE => 'file', SOURCE => $file;
-should_work TYPE => 'file', SOURCE => $file, UNTAINT => 1;
-
-# (8-9)
-open H, "< $file" or die "Couldn't open $file for reading: $!; aborting";
-should_fail TYPE => 'filehandle', SOURCE => \*H;
-close H;
-open H, "< $file" or die "Couldn't open $file for reading: $!; aborting";
-should_work TYPE => 'filehandle', SOURCE => \*H, UNTAINT => 1;
-close H;
-
-# (10-15)
-my $ttemplate = $template;
-taint($ttemplate);
-should_be_tainted($ttemplate);
-should_be_clean($template);
-should_fail TYPE => 'string', SOURCE => $ttemplate;
-should_fail TYPE => 'string', SOURCE => $ttemplate, UNTAINT => 1;
-should_work TYPE => 'string', SOURCE => $template;
-should_work TYPE => 'string', SOURCE => $template, UNTAINT => 1;
-
-# (16-19)
-my $array = [ $template ];
-my $tarray = [ $ttemplate ];
-should_fail TYPE => 'array', SOURCE => $tarray;
-should_fail TYPE => 'array', SOURCE => $tarray, UNTAINT => 1;
-should_work TYPE => 'array', SOURCE => $array;
-should_work TYPE => 'array', SOURCE => $array, UNTAINT => 1;
-
-# (20-21) Test _unconditionally_untaint utility function
-Text::Template::_unconditionally_untaint($ttemplate);
-should_be_clean($ttemplate);
-Text::Template::_unconditionally_untaint($tfile);
-should_be_clean($tfile);
-
-END { unlink $file }
-
+++ /dev/null
-#!perl
-# test apparatus for Text::Template module
-
-use Text::Template;
-
-print "1..5\n";
-
-$n=1;
-
-die "This is the test program for Text::Template version 1.46.
-You are using version $Text::Template::VERSION instead.
-That does not make sense.\n
-Aborting"
- unless $Text::Template::VERSION == 1.46;
-
-# (1) basic error delivery
-{ my $r = Text::Template->new(TYPE => 'string',
- SOURCE => '{1/0}',
- )->fill_in();
- if ($r eq q{Program fragment delivered error ``Illegal division by zero at template line 1.''}) {
- print "ok $n\n";
- } else {
- print "not ok $n\n# $r\n";
- }
- $n++;
-}
-
-# (2) BROKEN sub called in ->new?
-{ my $r = Text::Template->new(TYPE => 'string',
- SOURCE => '{1/0}',
- BROKEN => sub {'---'},
- )->fill_in();
- if ($r eq q{---}) {
- print "ok $n\n";
- } else {
- print "not ok $n\n# $r\n";
- }
- $n++;
-}
-
-# (3) BROKEN sub called in ->fill_in?
-{ my $r = Text::Template->new(TYPE => 'string',
- SOURCE => '{1/0}',
- )->fill_in(BROKEN => sub {'---'});
- if ($r eq q{---}) {
- print "ok $n\n";
- } else {
- print "not ok $n\n# $r\n";
- }
- $n++;
-}
-
-# (4) BROKEN sub passed correct args when called in ->new?
-{ my $r = Text::Template->new(TYPE => 'string',
- SOURCE => '{1/0}',
- BROKEN => sub { my %a = @_;
- qq{$a{lineno},$a{error},$a{text}}
- },
- )->fill_in();
- if ($r eq qq{1,Illegal division by zero at template line 1.\n,1/0}) {
- print "ok $n\n";
- } else {
- print "not ok $n\n# $r\n";
- }
- $n++;
-}
-
-# (5) BROKEN sub passed correct args when called in ->fill_in?
-{ my $r = Text::Template->new(TYPE => 'string',
- SOURCE => '{1/0}',
- )->fill_in(BROKEN =>
- sub { my %a = @_;
- qq{$a{lineno},$a{error},$a{text}}
- });
- if ($r eq qq{1,Illegal division by zero at template line 1.\n,1/0}) {
- print "ok $n\n";
- } else {
- print "not ok $n\n# $r\n";
- }
- $n++;
-}
-
--- /dev/null
+Revision history for Text::Template
+
+1.56 2019-07-09
+ - Fix typos in Changes
+
+1.55 2019-02-25
+ - Improve AppVeyor tests for older Perls (Thanks Roy Ivy)
+ - Check for Test::More 0.94 and skip tests if not installed where
+ done_testing() is used (Thanks Roy Ivy).
+ - Improve workaround for broken Win32 File::Temp taint failure (Thanks Roy Ivy).
+ - Skip/todo tests which fail under Devel::Cover (Thanks Roy Ivy)
+ - Add checks and skip_all checks for non-core test modules (Thanks Roy Ivy)
+
+1.54 2019-01-13
+ - Fix tempfile creation during tests on Win32
+
+1.53 2018-05-02
+ - Add support for decoding template files via ENCODING constructor arg
+ [github #11]
+ - Docs cleanup: replace indirect-object style examples and use class method
+ style constructor calls in the POD docs
+ - Docs cleanup: remove hard tabs from POD, replace dated, unfair synopsis
+ [github #5], convert "THANKS" section to a POD list
+
+1.52 2018-03-19
+ - Fix possible 'Subroutine ... redefined' warning (Github #10)
+
+1.51 2018-03-04
+ - Add test for nested tags breakage that happened in v1.46
+ - Turn off strict+warnings in sections where template code is eval'ed
+ [github #9]
+
+1.50 2018-02-10
+ *** Revert support for identical start/end delimiters (e.g.: @@foo@@, XXfooXX)
+ due to breakage with nested tags (see
+ https://github.com/mschout/perl-text-template/issues/8). Will revisit
+ this in a future release.
+
+1.49 2018-02-07
+ - Fix failing tests in v1.48 under perl < 5.8.9
+
+1.48 2018-02-07
+ - remove COPYING and Artistic files from the dist. These are replaced by
+ the Dist::Zilla generated LICENSE file.
+ - use strict/warnings (thanks Mohammad S Anwar)
+ - remove $VERSION checks from tests. This makes it easier to run the test
+ with Dist::Zilla and avoids maintenance issue of updating the tests for
+ each release (Thanks Andrew Ruder).
+ - Allow precompiled templates to work with preprocessing [#29928] (Thanks
+ Nik LaBelle)
+ - Add "strict" option to fill_in(). This adds "use strict" and "use vars
+ (...)" to the prepend section, and only the keys of the HASH option are
+ allowed in the template. (Thanks Desmond Daignault, Kivanc Yazan, CJM)
+ [55696]
+ - Fix templates with inline comments without newline after comment for perl
+ < 5.18 [34292]
+ - Don't use bareword file handles
+ - use three arg form of open()
+ - Fix BROKEN behaviour so that it returns the text accumulated so far on
+ undef as documented [28974]
+ - Source code cleanups
+ - Minimum perl version is now 5.8.0
+ - Allow start/end delimiters to be identical (e.g.: @@foo@@, XXfooXX)
+ (Thanks mirod) [46639]
+ - Fix + document the FILENAME parameter to fill_in() (Thanks VDB) [106093]
+ - Test suite cleanups:
+ + turn on strict/warnings for all tests
+ + run tests through perltidy and formatting cleanup
+ + remove number prefixes from test names
+ + use Test::More instead of generating TAP by hand
+ + use three-arg form of open()
+ + don't use indirect object syntax
+ + don't use bareword file handles
+ + use File::Temp to generate temporary files
+
+1.47 2017-02-27
+ - Fix longstanding memory leak in _scrubpkg() [#22031]
+ - Fix various spelling errors [#86872]
+
+NOTE: Changes for versions prior to 1.47 have been imported from README
+
+1.46 2013-02-11
+ - Thanks to Rik Signes, there is a new
+ Text::Template->append_text_to_output method, which Text::Template always
+ uses whenever it wants to emit output. You can subclass this to get
+ control over the output, for example for postprocessing.
+ - A spurious warning is no longer emitted when the TYPE parameter to ->new
+ is omitted.
+
+1.45 2008-04-16
+
+1.44 2003-04-29
+ - This is a maintenance release. There are no feature changes.
+ - _scrubpkg, which was responsible for eptying out temporary packages after
+ the module had done with them, wasn't always working; the result was
+ memory leaks in long-running applications. This should be fixed now, and
+ there is a test in the test suite for it.
+ - Minor changes to the test suite to prevent spurious errors.
+ - Minor documentation changes.
+
+1.43 2002-03-25
+ - The ->new method now fails immediately and sets $Text::Template::ERROR if
+ the file that is named by a filename argument does not exist or cannot be
+ opened for some other reason. Formerly, the constructor would succeed
+ and the ->fill_in call would fail.
+
+1.42 2001-11-05
+ - This is a maintenance release. There are no feature changes.
+ - Fixed a bug relating to use of UNTAINT under perl 5.005_03 and possibly
+ other versions.
+ - Taint-related tests are now more comprehensive.
+
+1.41 2001-09-04
+ - This is a maintenance release. There are no feature changes.
+ - Tests now work correctly on Windows systems and possibly on other
+ non-unix systems.
+
+1.40 2001-08-30
+ *** INCOMPATIBLE CHANGE ***
+ - The format of the default error message has changed. It used to look
+ like:
+
+ Program fragment at line 30 delivered error ``Illegal division by zero''
+
+ It now looks like:
+
+ Program fragment delivered error ``Illegal division by zero at catalog.tmpl line 37''
+
+ Note that the default message used to report the line number at which the
+ program fragment began; it now reports the line number at which the error
+ actually occurred.
+
+ *** INCOMPATIBLE CHANGE ***
+ - The format of the default error message has changed. It used to look like:
+
+ Program fragment at line 30 delivered error ``Illegal division by zero''
+
+ It now looks like:
+
+ Program fragment delivered error ``Illegal division by zero at catalog.tmpl line 37''
+
+ - Note that the default message used to report the line number at which the
+ program fragment began; it now reports the line number at which the error
+ actually occurred.
+ - New UNTAINT option tells the module that it is safe to 'eval' code even
+ though it has come from a file or filehandle.
+ - Code added to prevent memory leaks when filling many templates. Thanks
+ to Itamar Almeida de Carvalho.
+ - Bug fix: $OUT was not correctly initialized when used in conjunction
+ with SAFE.
+ - You may now use a glob ref when passing a filehandle to the ->new
+ function. Formerly, a glob was required.
+ - New subclass: Text::Template::Preprocess. Just like Text::Template, but
+ you may supply a PREPROCESS option in the constructor or the fill_in
+ call; this is a function which receives each code fragment prior to
+ evaluation, and which may modify and return the fragment; the modified
+ fragment is what is evaluated.
+ - Error messages passed to BROKEN subroutines will now report the correct
+ line number of the template at which the error occurred:
+
+ Illegal division by zero at template line 37.
+
+ - If the template comes from a file, the filename will be reported as well:
+
+ Illegal division by zero at catalog.tmpl line 37.
+
+ - New UNTAINT option tells the module that it is safe to eval template code
+ even if it has come from a file or filehandle, disabling taint checking
+ in these cases.
+ - Code added to prevent memory leaks when filling many templates. Thanks to
+ Itamar Almeida de Carvalho.
+ - Bug fix: $OUT was not always correctly initialized when used in
+ conjunction with SAFE.
+ - You may now use a glob ref when passing a filehandle to the new function.
+ Formerly, a glob was required.
+ - Error messages passed to BROKEN subroutines will now report the correct
+ line number of the template at which the error occurred:
+
+ Illegal division by zero at template line 37.
+
+ If the template comes from a file, the filename will be reported as well:
+
+ Illegal division by zero at catalog.tmpl line 37.
+
+ - New subclass: Text::Template::Preprocess. Just like Text::Template, but
+ you may supply a PREPROCESS option in the fill_in call; this is a
+ function which receives each code fragment prior to evaluation, and which
+ may modify and return the fragment; the modified fragment is what is
+ evaluated.
+
+1.31 2001-02-05
+ - Maintenance and bug fix release
+ - fill_in_string was failing. Thanks to Donald L. Greer Jr. for the test case.
+
+1.23 1999-12-21
+ - Small bug fix: DELIMITER and other arguments were being ignored in calls
+ to fill_in_file and fill_this_in. (Thanks to Jonathan Roy for reporting
+ this.)
+
+1.22
+ - You can now specify that certain Perl statements be prepended to the
+ beginning of every program fragment in a template, either per template,
+ or for all templates, or for the duration of only one call to fill_in.
+ This is useful, for example, if you want to enable `strict' checks in
+ your templates but you don't want to manually add `use strict' to the
+ front of every program fragment everywhere.
+
+1.20 1999-03-08
+ - You can now specify that the program fragment delimiters are strings
+ other than { and }. This has three interesting effects: First, it
+ changes the delimiter strings. Second, it disables the special meaning
+ of \, so you have to be really, really sure that the delimiters will not
+ appear in your templates. And third, because of the simplifications
+ introduced by the elimination of \ processing, template parsing is 20-25%
+ faster. See the manual section on `Alternative Delimiters'.
+ - Fixed bug having to do with undefined values in HASH options. In
+ particular, Text::Template no longer generates a warning if you try to
+ give a variable an undefined value.
+
+1.12 1999-02-28
+ - I forgot to say that Text::Template ISA Exporter, so the exported
+ functions never got exported. Duhhh!
+ - Template TYPEs are now case-insensitive. The `new' method now diagnoses
+ attempts to use an invalid TYPE.
+ - More tests for these things.
+
+1.11 1999-02-25
+ - Fixed a bug in the way backslashes were processed. The 1.10 behavior was
+ incompatible with the beta versions and was also inconvenient. (`\n' in
+ templates was replaced with `n' before it was given to Perl for
+ evaluation.) The new behavior is also incompatible with the beta
+ versions, but it is only a little bit incompatible, and it is probably
+ better.
+ - Documentation for the new behavior, and tests for the bug.
+
+1.10 1999-02-13
+ - New OUTPUT option delivers template results directly to a filehandle
+ instead of making them into a string. Saves space and time.
+ - PACKAGE and HASH now work intelligently with SAFE.
+ - Fragments may now output data directly to the template, rather than
+ having to arrange to return it as a return value at the end. This means
+ that where you used to have to write this:
+
+ { my $blist = '';
+ foreach $i (@items) {
+ $blist .= qq{ * $i\n};
+ }
+ $blist;
+ }
+
+ You can now write this instead, because $OUT is special.
+
+ { foreach $i (@items) {
+ $OUT.= " * $i\n";
+ }
+ }
+
+ (`A spoonful of sugar makes the medicine go down.')
+ - Fixed some small bugs. Worked around a bug in Perl that does the wrong
+ thing with $x = <Y> when $x contains a glob.
+ - More documentation. Errors fixed.
+ - Lots more tests.
+
+1.03 1999-02-06
+ - Code added to support HASH option to fill_in. (Incl. `_gensym'
+ function.)
+ - Documentation for HASH.
+ - New test file for HASH.
+ - Note about failure of lexical variables to propagate into templates. Why
+ does this surprise people?
+ - Bug fix: program fragments are evaluated in an environment with `no
+ strict' by default. Otherwise, you get a lot of `Global symbol "$v"
+ requires explicit package name' failures. Why didn't the test program
+ pick this up? Because the only variable the test program ever used was
+ `$a', which is exempt. Duhhhhh.
+ - Fixed the test program.
+ - Various minor documentation fixes.
+
+1.00 1999-02-05
+ This is a complete rewrite. The new version delivers better functionality
+ but is only 2/3 as long, which I think is a good sign. It is supposed to be
+ 100% backward-compatible with the previous versions. With one cosmetic
+ change, it passes the test suite that the previous versions passed. If you
+ have compatibility problems, please mail me immediately.
+
+ - At least twice as fast
+ - Better support for filling out the same template more than once
+ - Now supports evaluation of program fragments in Safe compartments.
+ (Thanks, Jonathan!)
+ - Better argument syntax
+ - More convenience functions
+ - The parser is much better and simpler
+ - Once a template is parsed, the parsed version is stored so that
+ it needn't be parsed again.
+ - BROKEN function behavior is rationalized. You can now pass an
+ arbitrary argument to your BROKEN function, or return a value
+ from it to the main program.
+ - Documentation overhauled.
+
+Previous Versions
+ - Maintained by Mark Jason Dominus (MJD)
--- /dev/null
+
+To install:
+
+ perl Makefile.PL
+
+to construct the Makefile, then
+
+ make test
+
+to test the package. If it fails any tests, please send me the output
+of `make test' and `perl -V'. I'll tell you whether it is safe to go
+ahead, or I'll provide a fix.
+
+If it passes the tests, use
+
+ make install
+
+to install it.
+
+Detailed documentation is at the bottom of the lib/Text/Template.pm
+file. You may be able to view it with the following command:
+
+ perldoc Text::Template
+
+Or:
+
+ perldoc lib/Text/Template.pm
+
+If you have problems, send me mail:
+
+mjd-perl-template+@plover.com
--- /dev/null
+This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+Terms of the Perl programming language system itself
+
+a) the GNU General Public License as published by the Free
+ Software Foundation; either version 1, or (at your option) any
+ later version, or
+b) the "Artistic License"
+
+--- The GNU General Public License, Version 1, February 1989 ---
+
+This software is Copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
+
+This is free software, licensed under:
+
+ The GNU General Public License, Version 1, February 1989
+
+ GNU GENERAL PUBLIC LICENSE
+ Version 1, February 1989
+
+ Copyright (C) 1989 Free Software Foundation, Inc.
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The license agreements of most software companies try to keep users
+at the mercy of those companies. By contrast, our General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users. The
+General Public License applies to the Free Software Foundation's
+software and to any other program whose authors commit to using it.
+You can use it for your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Specifically, the General Public License is designed to make
+sure that you have the freedom to give away or sell copies of free
+software, that you receive source code or can get it if you want it,
+that you can change the software or use pieces of it in new free
+programs; and that you know you can do these things.
+
+ To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+ For example, if you distribute copies of a such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have. You must make sure that they, too, receive or can get the
+source code. And you must tell them their rights.
+
+ We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+ Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software. If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ GNU GENERAL PUBLIC LICENSE
+ TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+ 0. This License Agreement applies to any program or other work which
+contains a notice placed by the copyright holder saying it may be
+distributed under the terms of this General Public License. The
+"Program", below, refers to any such program or work, and a "work based
+on the Program" means either the Program or any work containing the
+Program or a portion of it, either verbatim or with modifications. Each
+licensee is addressed as "you".
+
+ 1. You may copy and distribute verbatim copies of the Program's source
+code as you receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice and
+disclaimer of warranty; keep intact all the notices that refer to this
+General Public License and to the absence of any warranty; and give any
+other recipients of the Program a copy of this General Public License
+along with the Program. You may charge a fee for the physical act of
+transferring a copy.
+
+ 2. You may modify your copy or copies of the Program or any portion of
+it, and copy and distribute such modifications under the terms of Paragraph
+1 above, provided that you also do the following:
+
+ a) cause the modified files to carry prominent notices stating that
+ you changed the files and the date of any change; and
+
+ b) cause the whole of any work that you distribute or publish, that
+ in whole or in part contains the Program or any part thereof, either
+ with or without modifications, to be licensed at no charge to all
+ third parties under the terms of this General Public License (except
+ that you may choose to grant warranty protection to some or all
+ third parties, at your option).
+
+ c) If the modified program normally reads commands interactively when
+ run, you must cause it, when started running for such interactive use
+ in the simplest and most usual way, to print or display an
+ announcement including an appropriate copyright notice and a notice
+ that there is no warranty (or else, saying that you provide a
+ warranty) and that users may redistribute the program under these
+ conditions, and telling the user how to view a copy of this General
+ Public License.
+
+ d) You may charge a fee for the physical act of transferring a
+ copy, and you may at your option offer warranty protection in
+ exchange for a fee.
+
+Mere aggregation of another independent work with the Program (or its
+derivative) on a volume of a storage or distribution medium does not bring
+the other work under the scope of these terms.
+
+ 3. You may copy and distribute the Program (or a portion or derivative of
+it, under Paragraph 2) in object code or executable form under the terms of
+Paragraphs 1 and 2 above provided that you also do one of the following:
+
+ a) accompany it with the complete corresponding machine-readable
+ source code, which must be distributed under the terms of
+ Paragraphs 1 and 2 above; or,
+
+ b) accompany it with a written offer, valid for at least three
+ years, to give any third party free (except for a nominal charge
+ for the cost of distribution) a complete machine-readable copy of the
+ corresponding source code, to be distributed under the terms of
+ Paragraphs 1 and 2 above; or,
+
+ c) accompany it with the information you received as to where the
+ corresponding source code may be obtained. (This alternative is
+ allowed only for noncommercial distribution and only if you
+ received the program in object code or executable form alone.)
+
+Source code for a work means the preferred form of the work for making
+modifications to it. For an executable file, complete source code means
+all the source code for all modules it contains; but, as a special
+exception, it need not include source code for modules which are standard
+libraries that accompany the operating system on which the executable
+file runs, or for standard header files or definitions files that
+accompany that operating system.
+
+ 4. You may not copy, modify, sublicense, distribute or transfer the
+Program except as expressly provided under this General Public License.
+Any attempt otherwise to copy, modify, sublicense, distribute or transfer
+the Program is void, and will automatically terminate your rights to use
+the Program under this License. However, parties who have received
+copies, or rights to use copies, from you under this General Public
+License will not have their licenses terminated so long as such parties
+remain in full compliance.
+
+ 5. By copying, distributing or modifying the Program (or any work based
+on the Program) you indicate your acceptance of this license to do so,
+and all its terms and conditions.
+
+ 6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the original
+licensor to copy, distribute or modify the Program subject to these
+terms and conditions. You may not impose any further restrictions on the
+recipients' exercise of the rights granted herein.
+
+ 7. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program
+specifies a version number of the license which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation. If the Program does not specify a version number of
+the license, you may choose any version ever published by the Free Software
+Foundation.
+
+ 8. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission. For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this. Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+ NO WARRANTY
+
+ 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+ 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+ END OF TERMS AND CONDITIONS
+
+ Appendix: How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to humanity, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these
+terms.
+
+ To do so, attach the following notices to the program. It is safest to
+attach them to the start of each source file to most effectively convey
+the exclusion of warranty; and each file should have at least the
+"copyright" line and a pointer to where the full notice is found.
+
+ <one line to give the program's name and a brief idea of what it does.>
+ Copyright (C) 19yy <name of author>
+
+ This program is free software; you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation; either version 1, or (at your option)
+ any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA
+
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+ Gnomovision version 69, Copyright (C) 19xx name of author
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the
+appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than `show w' and `show
+c'; they could even be mouse-clicks or menu items--whatever suits your
+program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary. Here a sample; alter the names:
+
+ Yoyodyne, Inc., hereby disclaims all copyright interest in the
+ program `Gnomovision' (a program to direct compilers to make passes
+ at assemblers) written by James Hacker.
+
+ <signature of Ty Coon>, 1 April 1989
+ Ty Coon, President of Vice
+
+That's all there is to it!
+
+
+--- The Artistic License 1.0 ---
+
+This software is Copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
+
+This is free software, licensed under:
+
+ The Artistic License 1.0
+
+The Artistic License
+
+Preamble
+
+The intent of this document is to state the conditions under which a Package
+may be copied, such that the Copyright Holder maintains some semblance of
+artistic control over the development of the package, while giving the users of
+the package the right to use and distribute the Package in a more-or-less
+customary fashion, plus the right to make reasonable modifications.
+
+Definitions:
+
+ - "Package" refers to the collection of files distributed by the Copyright
+ Holder, and derivatives of that collection of files created through
+ textual modification.
+ - "Standard Version" refers to such a Package if it has not been modified,
+ or has been modified in accordance with the wishes of the Copyright
+ Holder.
+ - "Copyright Holder" is whoever is named in the copyright or copyrights for
+ the package.
+ - "You" is you, if you're thinking about copying or distributing this Package.
+ - "Reasonable copying fee" is whatever you can justify on the basis of media
+ cost, duplication charges, time of people involved, and so on. (You will
+ not be required to justify it to the Copyright Holder, but only to the
+ computing community at large as a market that must bear the fee.)
+ - "Freely Available" means that no fee is charged for the item itself, though
+ there may be fees involved in handling the item. It also means that
+ recipients of the item may redistribute it under the same conditions they
+ received it.
+
+1. You may make and give away verbatim copies of the source form of the
+Standard Version of this Package without restriction, provided that you
+duplicate all of the original copyright notices and associated disclaimers.
+
+2. You may apply bug fixes, portability fixes and other modifications derived
+from the Public Domain or from the Copyright Holder. A Package modified in such
+a way shall still be considered the Standard Version.
+
+3. You may otherwise modify your copy of this Package in any way, provided that
+you insert a prominent notice in each changed file stating how and when you
+changed that file, and provided that you do at least ONE of the following:
+
+ a) place your modifications in the Public Domain or otherwise make them
+ Freely Available, such as by posting said modifications to Usenet or an
+ equivalent medium, or placing the modifications on a major archive site
+ such as ftp.uu.net, or by allowing the Copyright Holder to include your
+ modifications in the Standard Version of the Package.
+
+ b) use the modified Package only within your corporation or organization.
+
+ c) rename any non-standard executables so the names do not conflict with
+ standard executables, which must also be provided, and provide a separate
+ manual page for each non-standard executable that clearly documents how it
+ differs from the Standard Version.
+
+ d) make other distribution arrangements with the Copyright Holder.
+
+4. You may distribute the programs of this Package in object code or executable
+form, provided that you do at least ONE of the following:
+
+ a) distribute a Standard Version of the executables and library files,
+ together with instructions (in the manual page or equivalent) on where to
+ get the Standard Version.
+
+ b) accompany the distribution with the machine-readable source of the Package
+ with your modifications.
+
+ c) accompany any non-standard executables with their corresponding Standard
+ Version executables, giving the non-standard executables non-standard
+ names, and clearly documenting the differences in manual pages (or
+ equivalent), together with instructions on where to get the Standard
+ Version.
+
+ d) make other distribution arrangements with the Copyright Holder.
+
+5. You may charge a reasonable copying fee for any distribution of this
+Package. You may charge any fee you choose for support of this Package. You
+may not charge a fee for this Package itself. However, you may distribute this
+Package in aggregate with other (possibly commercial) programs as part of a
+larger (possibly commercial) software distribution provided that you do not
+advertise this Package as a product of your own.
+
+6. The scripts and library files supplied as input to or produced as output
+from the programs of this Package do not automatically fall under the copyright
+of this Package, but belong to whomever generated them, and may be sold
+commercially, and may be aggregated with this Package.
+
+7. C or perl subroutines supplied by you and linked into this Package shall not
+be considered part of this Package.
+
+8. The name of the Copyright Holder may not be used to endorse or promote
+products derived from this software without specific prior written permission.
+
+9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+The End
+
--- /dev/null
+# This file was automatically generated by Dist::Zilla::Plugin::Manifest v6.012.
+Changes
+INSTALL
+LICENSE
+MANIFEST
+META.json
+META.yml
+Makefile.PL
+README
+SIGNATURE
+lib/Text/Template.pm
+lib/Text/Template/Preprocess.pm
+t/author-pod-syntax.t
+t/author-signature.t
+t/basic.t
+t/broken.t
+t/delimiters.t
+t/error.t
+t/exported.t
+t/hash.t
+t/inline-comment.t
+t/nested-tags.t
+t/ofh.t
+t/out.t
+t/prepend.t
+t/preprocess.t
+t/rt29928.t
+t/safe.t
+t/safe2.t
+t/safe3.t
+t/strict.t
+t/taint.t
+t/template-encoding.t
+t/warnings.t
--- /dev/null
+{
+ "abstract" : "Expand template text with embedded Perl",
+ "author" : [
+ "Michael Schout <mschout@cpan.org>"
+ ],
+ "dynamic_config" : 0,
+ "generated_by" : "Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010",
+ "license" : [
+ "perl_5"
+ ],
+ "meta-spec" : {
+ "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
+ "version" : 2
+ },
+ "name" : "Text-Template",
+ "prereqs" : {
+ "configure" : {
+ "requires" : {
+ "ExtUtils::MakeMaker" : "0",
+ "perl" : "5.008"
+ }
+ },
+ "develop" : {
+ "requires" : {
+ "Dist::Zilla" : "5",
+ "Dist::Zilla::PluginBundle::MSCHOUT" : "0",
+ "Software::License::Perl_5" : "0",
+ "Test::Pod" : "1.41",
+ "Test::Signature" : "0"
+ }
+ },
+ "runtime" : {
+ "requires" : {
+ "Carp" : "0",
+ "Encode" : "0",
+ "Exporter" : "0",
+ "base" : "0",
+ "perl" : "5.008",
+ "strict" : "0",
+ "warnings" : "0"
+ }
+ },
+ "test" : {
+ "requires" : {
+ "File::Temp" : "0",
+ "Safe" : "0",
+ "Test::More" : "0",
+ "Test::More::UTF8" : "0",
+ "Test::Warnings" : "0",
+ "lib" : "0",
+ "perl" : "5.008",
+ "utf8" : "0",
+ "vars" : "0"
+ }
+ }
+ },
+ "provides" : {
+ "Text::Template" : {
+ "file" : "lib/Text/Template.pm",
+ "version" : "1.56"
+ },
+ "Text::Template::Preprocess" : {
+ "file" : "lib/Text/Template/Preprocess.pm",
+ "version" : "1.56"
+ }
+ },
+ "release_status" : "stable",
+ "resources" : {
+ "bugtracker" : {
+ "web" : "https://github.com/mschout/perl-text-template/issues"
+ },
+ "homepage" : "https://github.com/mschout/perl-text-template",
+ "repository" : {
+ "type" : "git",
+ "url" : "https://github.com/mschout/perl-text-template.git",
+ "web" : "https://github.com/mschout/perl-text-template"
+ }
+ },
+ "version" : "1.56",
+ "x_generated_by_perl" : "v5.26.2",
+ "x_serialization_backend" : "Cpanel::JSON::XS version 4.04"
+}
+
--- /dev/null
+---
+abstract: 'Expand template text with embedded Perl'
+author:
+ - 'Michael Schout <mschout@cpan.org>'
+build_requires:
+ File::Temp: '0'
+ Safe: '0'
+ Test::More: '0'
+ Test::More::UTF8: '0'
+ Test::Warnings: '0'
+ lib: '0'
+ perl: '5.008'
+ utf8: '0'
+ vars: '0'
+configure_requires:
+ ExtUtils::MakeMaker: '0'
+ perl: '5.008'
+dynamic_config: 0
+generated_by: 'Dist::Zilla version 6.012, CPAN::Meta::Converter version 2.150010'
+license: perl
+meta-spec:
+ url: http://module-build.sourceforge.net/META-spec-v1.4.html
+ version: '1.4'
+name: Text-Template
+provides:
+ Text::Template:
+ file: lib/Text/Template.pm
+ version: '1.56'
+ Text::Template::Preprocess:
+ file: lib/Text/Template/Preprocess.pm
+ version: '1.56'
+requires:
+ Carp: '0'
+ Encode: '0'
+ Exporter: '0'
+ base: '0'
+ perl: '5.008'
+ strict: '0'
+ warnings: '0'
+resources:
+ bugtracker: https://github.com/mschout/perl-text-template/issues
+ homepage: https://github.com/mschout/perl-text-template
+ repository: https://github.com/mschout/perl-text-template.git
+version: '1.56'
+x_generated_by_perl: v5.26.2
+x_serialization_backend: 'YAML::Tiny version 1.73'
--- /dev/null
+# This file was automatically generated by Dist::Zilla::Plugin::MakeMaker v6.012.
+use strict;
+use warnings;
+
+use 5.008;
+
+use ExtUtils::MakeMaker;
+
+my %WriteMakefileArgs = (
+ "ABSTRACT" => "Expand template text with embedded Perl",
+ "AUTHOR" => "Michael Schout <mschout\@cpan.org>",
+ "CONFIGURE_REQUIRES" => {
+ "ExtUtils::MakeMaker" => 0
+ },
+ "DISTNAME" => "Text-Template",
+ "LICENSE" => "perl",
+ "MIN_PERL_VERSION" => "5.008",
+ "NAME" => "Text::Template",
+ "PREREQ_PM" => {
+ "Carp" => 0,
+ "Encode" => 0,
+ "Exporter" => 0,
+ "base" => 0,
+ "strict" => 0,
+ "warnings" => 0
+ },
+ "TEST_REQUIRES" => {
+ "File::Temp" => 0,
+ "Safe" => 0,
+ "Test::More" => 0,
+ "Test::More::UTF8" => 0,
+ "Test::Warnings" => 0,
+ "lib" => 0,
+ "utf8" => 0,
+ "vars" => 0
+ },
+ "VERSION" => "1.56",
+ "test" => {
+ "TESTS" => "t/*.t"
+ }
+);
+
+
+my %FallbackPrereqs = (
+ "Carp" => 0,
+ "Encode" => 0,
+ "Exporter" => 0,
+ "File::Temp" => 0,
+ "Safe" => 0,
+ "Test::More" => 0,
+ "Test::More::UTF8" => 0,
+ "Test::Warnings" => 0,
+ "base" => 0,
+ "lib" => 0,
+ "strict" => 0,
+ "utf8" => 0,
+ "vars" => 0,
+ "warnings" => 0
+);
+
+
+unless ( eval { ExtUtils::MakeMaker->VERSION(6.63_03) } ) {
+ delete $WriteMakefileArgs{TEST_REQUIRES};
+ delete $WriteMakefileArgs{BUILD_REQUIRES};
+ $WriteMakefileArgs{PREREQ_PM} = \%FallbackPrereqs;
+}
+
+delete $WriteMakefileArgs{CONFIGURE_REQUIRES}
+ unless eval { ExtUtils::MakeMaker->VERSION(6.52) };
+
+WriteMakefile(%WriteMakefileArgs);
--- /dev/null
+
+Text::Template v1.46
+
+This is a library for generating form letters, building HTML pages, or
+filling in templates generally. A `template' is a piece of text that
+has little Perl programs embedded in it here and there. When you
+`fill in' a template, you evaluate the little programs and replace
+them with their values.
+
+Here's an example of a template:
+
+ Dear {$title} {$lastname},
+
+ It has come to our attention that you are delinquent in your
+ {$monthname[$last_paid_month]} payment. Please remit
+ ${sprintf("%.2f", $amount)} immediately, or your patellae may
+ be needlessly endangered.
+
+ Love,
+
+ Mark "{nickname(rand 20)}" Dominus
+
+
+The result of filling in this template is a string, which might look
+something like this:
+
+ Dear Mr. Gates,
+
+ It has come to our attention that you are delinquent in your
+ February payment. Please remit
+ $392.12 immediately, or your patellae may
+ be needlessly endangered.
+
+
+ Love,
+
+ Mark "Vizopteryx" Dominus
+
+You can store a template in a file outside your program. People can
+modify the template without modifying the program. You can separate
+the formatting details from the main code, and put the formatting
+parts of the program into the template. That prevents code bloat and
+encourages functional separation.
+
+You can fill in the template in a `Safe' compartment. This means that
+if you don't trust the person who wrote the code in the template, you
+won't have to worry that they are tampering with your program when you
+execute it.
+
+----------------------------------------------------------------
+
+Text::Template was originally released some time in late 1995 or early
+1996. After three years of study and investigation, I rewrote it from
+scratch in January 1999. The new version, 1.0, was much faster,
+delivered better functionality and was almost 100% backward-compatible
+with the previous beta versions.
+
+I have added a number of useful features and conveniences since the
+1.0 release, while still retaining backward compatibility. With one
+merely cosmetic change, the current version of Text::Template passes
+the test suite that the old beta versions passed.
+
--- /dev/null
+This file contains message digests of all files listed in MANIFEST,
+signed via the Module::Signature module, version 0.81.
+
+To verify the content in this distribution, first make sure you have
+Module::Signature installed, then type:
+
+ % cpansign -v
+
+It will check each file's integrity, as well as the signature's
+validity. If "==> Signature verified OK! <==" is not displayed,
+the distribution may already have been compromised, and you should
+not run its Makefile.PL or Build.PL.
+
+-----BEGIN PGP SIGNED MESSAGE-----
+Hash: SHA256
+
+SHA1 8ba1381d3fc8d81457c35e5aff52b8e55d57be7c Changes
+SHA1 b457bd56a70b838ccc55d183ab09de64b6996958 INSTALL
+SHA1 f12894289cb0f379f24b8d63e2e761dbcba1b216 LICENSE
+SHA1 2c21cb13f53da41c4b30011aca9014db2de46862 MANIFEST
+SHA1 ea82a70dfcffe05202868dfe02826aaf1f6e0229 META.json
+SHA1 9ad7419fb6209e81652da42967995c8fb8f1826b META.yml
+SHA1 f7634b46dde2cf8c6f31fe46327d15151d654a2c Makefile.PL
+SHA1 b94aaad0a0bf2c323061bfefb9cf1fd532f14e7b README
+SHA1 090d77972c087a8905fa85522854afbf4ccc999b lib/Text/Template.pm
+SHA1 ca5251a021e46b60603f10e757d689e52fde1feb lib/Text/Template/Preprocess.pm
+SHA1 8efad25309730a4d501fb40fc03eda4697303372 t/author-pod-syntax.t
+SHA1 19cc343f8a85c6805bbeb02580487483a6283887 t/author-signature.t
+SHA1 ae085010c9f08576ef8584f224e38e6a98c1c178 t/basic.t
+SHA1 006feb1a0b1e5780db52aa79bd38933664a8339a t/broken.t
+SHA1 dee8cef1fcd43ce5de462018f8539d4a0fbc460f t/delimiters.t
+SHA1 304955c4280159ec3a4c0f2717dcff9c887bb487 t/error.t
+SHA1 c862dfc08e00e76b3f2aee953583d3cc8e5524a2 t/exported.t
+SHA1 50ef92bda3b6b5cbd5a9307e6f17ce49ee8f245c t/hash.t
+SHA1 d5dc210684aec8bb2c4817af96597c86047169c1 t/inline-comment.t
+SHA1 31ff85f423178f2d6638d35edf859d73f63dd5c7 t/nested-tags.t
+SHA1 62ae0720aa86146bccfa23d2c903fa142cb86d50 t/ofh.t
+SHA1 68093417d49a2afdfcd4642bacea04466039b734 t/out.t
+SHA1 a8b21fdca0f1d243775a00758105e0fcc58022aa t/prepend.t
+SHA1 4e7e00eccede7c3231e93ef0f3cb011423be4eb5 t/preprocess.t
+SHA1 a52d61ef92e6a88d694db0be4893b88417a72f9c t/rt29928.t
+SHA1 5186ff459c6042af11bca92decd271887c7b2eae t/safe.t
+SHA1 aa0c9ff96d66c1f74fc7ac73ce173c9f741f552e t/safe2.t
+SHA1 b50a51577c0f2c13c9a48113dc7f061385a02219 t/safe3.t
+SHA1 16d3abf7588da4c0056c6c6b7818470c8601577c t/strict.t
+SHA1 f325ebf739e2aec3ae62427aef0c4e86de58ad29 t/taint.t
+SHA1 4dac28585388482f1719f404cc357991af77e345 t/template-encoding.t
+SHA1 ce1da9bf88d6ea62d7c756f0d730dfb3c5888b6e t/warnings.t
+-----BEGIN PGP SIGNATURE-----
+
+iQJFBAEBCAAvFiEE2EtuRfhGgngE8PsARAzvLrlUzY4FAl0kljYRHG1zY2hvdXRA
+Y3Bhbi5vcmcACgkQRAzvLrlUzY6BdRAAlu/LI+71ax6OJfn6O6SslZCKdIfef1+P
+UQ3eQCzbUOK1hP9p6TNOMFv0xPew7a1jSsM/wLjryXKLqGIclonBopRisZjCSaFa
+DSH+5k4A9TWKo7n08C3nydVZPTfHXLEO6tHIH2umDHjMyC1gDkApjvSqH53OCtoV
+vUTqQn9c6MxmuIWus1gjVynTvXWtBmaqrvTuQENFUXsGH5gVVbEr0VNIyt6Ip3p5
+HnRe8UdykFJZvfhEhH1pbt2j513m9Bqce0eSb/eshraFugx7coD3gk2EXqp8eVzK
+84vPEcNC8Moii8+qg48VDh9wBq1u/cba2U7PcVjj3lRk/pAni31XnlXLPWJ0dZLF
+fR4glE86ESTGSyI2wGDxyEdev+e64sk7geYmL388kqtpqkKWvALmQkKUJg0T0ppp
+LYv31DrsP4QM1duv46y3wVbqUPeQlKBOU81vfyAonrD02tRZjwRpCD67CZ9WSgZu
+el85yPneIIijYEOzV8GYHKNiiZKpu2uidKCe+MFGxBtXe9hyi9x95tuyi9/pu2FB
+YjbGJ8Wb4xhS7zdDWZb/axfwbcGMVml6a6xA98jVkwjHhPvKsf3qWVZZPtWneeN0
+pGNpMta73wQxrp5/W1GfvBfPVlsker6SAARg2NMwS9Wmp+ZuD6gdJ+aN0/PPtNUd
+HQJJFjr/xo4=
+=nx9E
+-----END PGP SIGNATURE-----
--- /dev/null
+# -*- perl -*-
+# Text::Template.pm
+#
+# Fill in `templates'
+#
+# Copyright 2013 M. J. Dominus.
+# You may copy and distribute this program under the
+# same terms as Perl itself.
+# If in doubt, write to mjd-perl-template+@plover.com for a license.
+#
+
+package Text::Template;
+$Text::Template::VERSION = '1.56';
+# ABSTRACT: Expand template text with embedded Perl
+
+use strict;
+use warnings;
+
+require 5.008;
+
+use base 'Exporter';
+
+our @EXPORT_OK = qw(fill_in_file fill_in_string TTerror);
+our $ERROR;
+
+my %GLOBAL_PREPEND = ('Text::Template' => '');
+
+sub Version {
+ $Text::Template::VERSION;
+}
+
+sub _param {
+ my ($k, %h) = @_;
+
+ for my $kk ($k, "\u$k", "\U$k", "-$k", "-\u$k", "-\U$k") {
+ return $h{$kk} if exists $h{$kk};
+ }
+
+ return undef;
+}
+
+sub always_prepend {
+ my $pack = shift;
+
+ my $old = $GLOBAL_PREPEND{$pack};
+
+ $GLOBAL_PREPEND{$pack} = shift;
+
+ $old;
+}
+
+{
+ my %LEGAL_TYPE;
+
+ BEGIN {
+ %LEGAL_TYPE = map { $_ => 1 } qw(FILE FILEHANDLE STRING ARRAY);
+ }
+
+ sub new {
+ my ($pack, %a) = @_;
+
+ my $stype = uc(_param('type', %a) || "FILE");
+ my $source = _param('source', %a);
+ my $untaint = _param('untaint', %a);
+ my $prepend = _param('prepend', %a);
+ my $alt_delim = _param('delimiters', %a);
+ my $broken = _param('broken', %a);
+ my $encoding = _param('encoding', %a);
+
+ unless (defined $source) {
+ require Carp;
+ Carp::croak("Usage: $ {pack}::new(TYPE => ..., SOURCE => ...)");
+ }
+
+ unless ($LEGAL_TYPE{$stype}) {
+ require Carp;
+ Carp::croak("Illegal value `$stype' for TYPE parameter");
+ }
+
+ my $self = {
+ TYPE => $stype,
+ PREPEND => $prepend,
+ UNTAINT => $untaint,
+ BROKEN => $broken,
+ ENCODING => $encoding,
+ (defined $alt_delim ? (DELIM => $alt_delim) : ())
+ };
+
+ # Under 5.005_03, if any of $stype, $prepend, $untaint, or $broken
+ # are tainted, all the others become tainted too as a result of
+ # sharing the expression with them. We install $source separately
+ # to prevent it from acquiring a spurious taint.
+ $self->{SOURCE} = $source;
+
+ bless $self => $pack;
+ return unless $self->_acquire_data;
+
+ $self;
+ }
+}
+
+# Convert template objects of various types to type STRING,
+# in which the template data is embedded in the object itself.
+sub _acquire_data {
+ my $self = shift;
+
+ my $type = $self->{TYPE};
+
+ if ($type eq 'STRING') {
+ # nothing necessary
+ }
+ elsif ($type eq 'FILE') {
+ my $data = _load_text($self->{SOURCE});
+ unless (defined $data) {
+
+ # _load_text already set $ERROR
+ return undef;
+ }
+
+ if ($self->{UNTAINT} && _is_clean($self->{SOURCE})) {
+ _unconditionally_untaint($data);
+ }
+
+ if (defined $self->{ENCODING}) {
+ require Encode;
+ $data = Encode::decode($self->{ENCODING}, $data, &Encode::FB_CROAK);
+ }
+
+ $self->{TYPE} = 'STRING';
+ $self->{FILENAME} = $self->{SOURCE};
+ $self->{SOURCE} = $data;
+ }
+ elsif ($type eq 'ARRAY') {
+ $self->{TYPE} = 'STRING';
+ $self->{SOURCE} = join '', @{ $self->{SOURCE} };
+ }
+ elsif ($type eq 'FILEHANDLE') {
+ $self->{TYPE} = 'STRING';
+ local $/;
+ my $fh = $self->{SOURCE};
+ my $data = <$fh>; # Extra assignment avoids bug in Solaris perl5.00[45].
+ if ($self->{UNTAINT}) {
+ _unconditionally_untaint($data);
+ }
+ $self->{SOURCE} = $data;
+ }
+ else {
+ # This should have been caught long ago, so it represents a
+ # drastic `can't-happen' sort of failure
+ my $pack = ref $self;
+ die "Can only acquire data for $pack objects of subtype STRING, but this is $type; aborting";
+ }
+
+ $self->{DATA_ACQUIRED} = 1;
+}
+
+sub source {
+ my $self = shift;
+
+ $self->_acquire_data unless $self->{DATA_ACQUIRED};
+
+ return $self->{SOURCE};
+}
+
+sub set_source_data {
+ my ($self, $newdata, $type) = @_;
+
+ $self->{SOURCE} = $newdata;
+ $self->{DATA_ACQUIRED} = 1;
+ $self->{TYPE} = $type || 'STRING';
+
+ 1;
+}
+
+sub compile {
+ my $self = shift;
+
+ return 1 if $self->{TYPE} eq 'PREPARSED';
+
+ return undef unless $self->_acquire_data;
+
+ unless ($self->{TYPE} eq 'STRING') {
+ my $pack = ref $self;
+
+ # This should have been caught long ago, so it represents a
+ # drastic `can't-happen' sort of failure
+ die "Can only compile $pack objects of subtype STRING, but this is $self->{TYPE}; aborting";
+ }
+
+ my @tokens;
+ my $delim_pats = shift() || $self->{DELIM};
+
+ my ($t_open, $t_close) = ('{', '}');
+ my $DELIM; # Regex matches a delimiter if $delim_pats
+
+ if (defined $delim_pats) {
+ ($t_open, $t_close) = @$delim_pats;
+ $DELIM = "(?:(?:\Q$t_open\E)|(?:\Q$t_close\E))";
+ @tokens = split /($DELIM|\n)/, $self->{SOURCE};
+ }
+ else {
+ @tokens = split /(\\\\(?=\\*[{}])|\\[{}]|[{}\n])/, $self->{SOURCE};
+ }
+
+ my $state = 'TEXT';
+ my $depth = 0;
+ my $lineno = 1;
+ my @content;
+ my $cur_item = '';
+ my $prog_start;
+
+ while (@tokens) {
+ my $t = shift @tokens;
+
+ next if $t eq '';
+
+ if ($t eq $t_open) { # Brace or other opening delimiter
+ if ($depth == 0) {
+ push @content, [ $state, $cur_item, $lineno ] if $cur_item ne '';
+ $cur_item = '';
+ $state = 'PROG';
+ $prog_start = $lineno;
+ }
+ else {
+ $cur_item .= $t;
+ }
+ $depth++;
+ }
+ elsif ($t eq $t_close) { # Brace or other closing delimiter
+ $depth--;
+ if ($depth < 0) {
+ $ERROR = "Unmatched close brace at line $lineno";
+ return undef;
+ }
+ elsif ($depth == 0) {
+ push @content, [ $state, $cur_item, $prog_start ] if $cur_item ne '';
+ $state = 'TEXT';
+ $cur_item = '';
+ }
+ else {
+ $cur_item .= $t;
+ }
+ }
+ elsif (!$delim_pats && $t eq '\\\\') { # precedes \\\..\\\{ or \\\..\\\}
+ $cur_item .= '\\';
+ }
+ elsif (!$delim_pats && $t =~ /^\\([{}])$/) { # Escaped (literal) brace?
+ $cur_item .= $1;
+ }
+ elsif ($t eq "\n") { # Newline
+ $lineno++;
+ $cur_item .= $t;
+ }
+ else { # Anything else
+ $cur_item .= $t;
+ }
+ }
+
+ if ($state eq 'PROG') {
+ $ERROR = "End of data inside program text that began at line $prog_start";
+ return undef;
+ }
+ elsif ($state eq 'TEXT') {
+ push @content, [ $state, $cur_item, $lineno ] if $cur_item ne '';
+ }
+ else {
+ die "Can't happen error #1";
+ }
+
+ $self->{TYPE} = 'PREPARSED';
+ $self->{SOURCE} = \@content;
+
+ 1;
+}
+
+sub prepend_text {
+ my $self = shift;
+
+ my $t = $self->{PREPEND};
+
+ unless (defined $t) {
+ $t = $GLOBAL_PREPEND{ ref $self };
+ unless (defined $t) {
+ $t = $GLOBAL_PREPEND{'Text::Template'};
+ }
+ }
+
+ $self->{PREPEND} = $_[1] if $#_ >= 1;
+
+ return $t;
+}
+
+sub fill_in {
+ my ($fi_self, %fi_a) = @_;
+
+ unless ($fi_self->{TYPE} eq 'PREPARSED') {
+ my $delims = _param('delimiters', %fi_a);
+ my @delim_arg = (defined $delims ? ($delims) : ());
+ $fi_self->compile(@delim_arg)
+ or return undef;
+ }
+
+ my $fi_varhash = _param('hash', %fi_a);
+ my $fi_package = _param('package', %fi_a);
+ my $fi_broken = _param('broken', %fi_a) || $fi_self->{BROKEN} || \&_default_broken;
+ my $fi_broken_arg = _param('broken_arg', %fi_a) || [];
+ my $fi_safe = _param('safe', %fi_a);
+ my $fi_ofh = _param('output', %fi_a);
+ my $fi_filename = _param('filename', %fi_a) || $fi_self->{FILENAME} || 'template';
+ my $fi_strict = _param('strict', %fi_a);
+ my $fi_prepend = _param('prepend', %fi_a);
+
+ my $fi_eval_package;
+ my $fi_scrub_package = 0;
+
+ unless (defined $fi_prepend) {
+ $fi_prepend = $fi_self->prepend_text;
+ }
+
+ if (defined $fi_safe) {
+ $fi_eval_package = 'main';
+ }
+ elsif (defined $fi_package) {
+ $fi_eval_package = $fi_package;
+ }
+ elsif (defined $fi_varhash) {
+ $fi_eval_package = _gensym();
+ $fi_scrub_package = 1;
+ }
+ else {
+ $fi_eval_package = caller;
+ }
+
+ my @fi_varlist;
+ my $fi_install_package;
+
+ if (defined $fi_varhash) {
+ if (defined $fi_package) {
+ $fi_install_package = $fi_package;
+ }
+ elsif (defined $fi_safe) {
+ $fi_install_package = $fi_safe->root;
+ }
+ else {
+ $fi_install_package = $fi_eval_package; # The gensymmed one
+ }
+ @fi_varlist = _install_hash($fi_varhash => $fi_install_package);
+ if ($fi_strict) {
+ $fi_prepend = "use vars qw(@fi_varlist);$fi_prepend" if @fi_varlist;
+ $fi_prepend = "use strict;$fi_prepend";
+ }
+ }
+
+ if (defined $fi_package && defined $fi_safe) {
+ no strict 'refs';
+
+ # Big fat magic here: Fix it so that the user-specified package
+ # is the default one available in the safe compartment.
+ *{ $fi_safe->root . '::' } = \%{ $fi_package . '::' }; # LOD
+ }
+
+ my $fi_r = '';
+ my $fi_item;
+ foreach $fi_item (@{ $fi_self->{SOURCE} }) {
+ my ($fi_type, $fi_text, $fi_lineno) = @$fi_item;
+ if ($fi_type eq 'TEXT') {
+ $fi_self->append_text_to_output(
+ text => $fi_text,
+ handle => $fi_ofh,
+ out => \$fi_r,
+ type => $fi_type,);
+ }
+ elsif ($fi_type eq 'PROG') {
+ no strict;
+
+ my $fi_lcomment = "#line $fi_lineno $fi_filename";
+ my $fi_progtext = "package $fi_eval_package; $fi_prepend;\n$fi_lcomment\n$fi_text;\n;";
+ my $fi_res;
+ my $fi_eval_err = '';
+
+ if ($fi_safe) {
+ no strict;
+ no warnings;
+
+ $fi_safe->reval(q{undef $OUT});
+ $fi_res = $fi_safe->reval($fi_progtext);
+ $fi_eval_err = $@;
+ my $OUT = $fi_safe->reval('$OUT');
+ $fi_res = $OUT if defined $OUT;
+ }
+ else {
+ no strict;
+ no warnings;
+
+ my $OUT;
+ $fi_res = eval $fi_progtext;
+ $fi_eval_err = $@;
+ $fi_res = $OUT if defined $OUT;
+ }
+
+ # If the value of the filled-in text really was undef,
+ # change it to an explicit empty string to avoid undefined
+ # value warnings later.
+ $fi_res = '' unless defined $fi_res;
+
+ if ($fi_eval_err) {
+ $fi_res = $fi_broken->(
+ text => $fi_text,
+ error => $fi_eval_err,
+ lineno => $fi_lineno,
+ arg => $fi_broken_arg,);
+ if (defined $fi_res) {
+ $fi_self->append_text_to_output(
+ text => $fi_res,
+ handle => $fi_ofh,
+ out => \$fi_r,
+ type => $fi_type,);
+ }
+ else {
+ return $fi_r; # Undefined means abort processing
+ }
+ }
+ else {
+ $fi_self->append_text_to_output(
+ text => $fi_res,
+ handle => $fi_ofh,
+ out => \$fi_r,
+ type => $fi_type,);
+ }
+ }
+ else {
+ die "Can't happen error #2";
+ }
+ }
+
+ _scrubpkg($fi_eval_package) if $fi_scrub_package;
+
+ defined $fi_ofh ? 1 : $fi_r;
+}
+
+sub append_text_to_output {
+ my ($self, %arg) = @_;
+
+ if (defined $arg{handle}) {
+ print { $arg{handle} } $arg{text};
+ }
+ else {
+ ${ $arg{out} } .= $arg{text};
+ }
+
+ return;
+}
+
+sub fill_this_in {
+ my ($pack, $text) = splice @_, 0, 2;
+
+ my $templ = $pack->new(TYPE => 'STRING', SOURCE => $text, @_)
+ or return undef;
+
+ $templ->compile or return undef;
+
+ my $result = $templ->fill_in(@_);
+
+ $result;
+}
+
+sub fill_in_string {
+ my $string = shift;
+
+ my $package = _param('package', @_);
+
+ push @_, 'package' => scalar(caller) unless defined $package;
+
+ Text::Template->fill_this_in($string, @_);
+}
+
+sub fill_in_file {
+ my $fn = shift;
+ my $templ = Text::Template->new(TYPE => 'FILE', SOURCE => $fn, @_) or return undef;
+
+ $templ->compile or return undef;
+
+ my $text = $templ->fill_in(@_);
+
+ $text;
+}
+
+sub _default_broken {
+ my %a = @_;
+
+ my $prog_text = $a{text};
+ my $err = $a{error};
+ my $lineno = $a{lineno};
+
+ chomp $err;
+
+ # $err =~ s/\s+at .*//s;
+ "Program fragment delivered error ``$err''";
+}
+
+sub _load_text {
+ my $fn = shift;
+
+ open my $fh, '<', $fn or do {
+ $ERROR = "Couldn't open file $fn: $!";
+ return undef;
+ };
+
+ local $/;
+
+ <$fh>;
+}
+
+sub _is_clean {
+ my $z;
+
+ eval { ($z = join('', @_)), eval '#' . substr($z, 0, 0); 1 } # LOD
+}
+
+sub _unconditionally_untaint {
+ for (@_) {
+ ($_) = /(.*)/s;
+ }
+}
+
+{
+ my $seqno = 0;
+
+ sub _gensym {
+ __PACKAGE__ . '::GEN' . $seqno++;
+ }
+
+ sub _scrubpkg {
+ my $s = shift;
+
+ $s =~ s/^Text::Template:://;
+
+ no strict 'refs';
+
+ my $hash = $Text::Template::{ $s . "::" };
+
+ foreach my $key (keys %$hash) {
+ undef $hash->{$key};
+ }
+
+ %$hash = ();
+
+ delete $Text::Template::{ $s . "::" };
+ }
+}
+
+# Given a hashful of variables (or a list of such hashes)
+# install the variables into the specified package,
+# overwriting whatever variables were there before.
+sub _install_hash {
+ my $hashlist = shift;
+ my $dest = shift;
+
+ if (UNIVERSAL::isa($hashlist, 'HASH')) {
+ $hashlist = [$hashlist];
+ }
+
+ my @varlist;
+
+ for my $hash (@$hashlist) {
+ for my $name (keys %$hash) {
+ my $val = $hash->{$name};
+
+ no strict 'refs';
+ no warnings 'redefine';
+
+ local *SYM = *{"$ {dest}::$name"};
+
+ if (!defined $val) {
+ delete ${"$ {dest}::"}{$name};
+ my $match = qr/^.\Q$name\E$/;
+ @varlist = grep { $_ !~ $match } @varlist;
+ }
+ elsif (ref $val) {
+ *SYM = $val;
+ push @varlist, do {
+ if (UNIVERSAL::isa($val, 'ARRAY')) { '@' }
+ elsif (UNIVERSAL::isa($val, 'HASH')) { '%' }
+ else { '$' }
+ }
+ . $name;
+ }
+ else {
+ *SYM = \$val;
+ push @varlist, '$' . $name;
+ }
+ }
+ }
+
+ @varlist;
+}
+
+sub TTerror { $ERROR }
+
+1;
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+Text::Template - Expand template text with embedded Perl
+
+=head1 VERSION
+
+version 1.56
+
+=head1 SYNOPSIS
+
+ use Text::Template;
+
+
+ $template = Text::Template->new(TYPE => 'FILE', SOURCE => 'filename.tmpl');
+ $template = Text::Template->new(TYPE => 'ARRAY', SOURCE => [ ... ] );
+ $template = Text::Template->new(TYPE => 'FILEHANDLE', SOURCE => $fh );
+ $template = Text::Template->new(TYPE => 'STRING', SOURCE => '...' );
+ $template = Text::Template->new(PREPEND => q{use strict;}, ...);
+
+ # Use a different template file syntax:
+ $template = Text::Template->new(DELIMITERS => [$open, $close], ...);
+
+ $recipient = 'King';
+ $text = $template->fill_in(); # Replaces `{$recipient}' with `King'
+ print $text;
+
+ $T::recipient = 'Josh';
+ $text = $template->fill_in(PACKAGE => T);
+
+ # Pass many variables explicitly
+ $hash = { recipient => 'Abed-Nego',
+ friends => [ 'me', 'you' ],
+ enemies => { loathsome => 'Saruman',
+ fearsome => 'Sauron' },
+ };
+ $text = $template->fill_in(HASH => $hash, ...);
+ # $recipient is Abed-Nego,
+ # @friends is ( 'me', 'you' ),
+ # %enemies is ( loathsome => ..., fearsome => ... )
+
+
+ # Call &callback in case of programming errors in template
+ $text = $template->fill_in(BROKEN => \&callback, BROKEN_ARG => $ref, ...);
+
+ # Evaluate program fragments in Safe compartment with restricted permissions
+ $text = $template->fill_in(SAFE => $compartment, ...);
+
+ # Print result text instead of returning it
+ $success = $template->fill_in(OUTPUT => \*FILEHANDLE, ...);
+
+ # Parse template with different template file syntax:
+ $text = $template->fill_in(DELIMITERS => [$open, $close], ...);
+ # Note that this is *faster* than using the default delimiters
+
+ # Prepend specified perl code to each fragment before evaluating:
+ $text = $template->fill_in(PREPEND => q{use strict 'vars';}, ...);
+
+ use Text::Template 'fill_in_string';
+ $text = fill_in_string( <<EOM, PACKAGE => 'T', ...);
+ Dear {$recipient},
+ Pay me at once.
+ Love,
+ G.V.
+ EOM
+
+ use Text::Template 'fill_in_file';
+ $text = fill_in_file($filename, ...);
+
+ # All templates will always have `use strict vars' attached to all fragments
+ Text::Template->always_prepend(q{use strict 'vars';});
+
+=head1 DESCRIPTION
+
+This is a library for generating form letters, building HTML pages, or
+filling in templates generally. A `template' is a piece of text that
+has little Perl programs embedded in it here and there. When you
+`fill in' a template, you evaluate the little programs and replace
+them with their values.
+
+You can store a template in a file outside your program. People can
+modify the template without modifying the program. You can separate
+the formatting details from the main code, and put the formatting
+parts of the program into the template. That prevents code bloat and
+encourages functional separation.
+
+=head2 Example
+
+Here's an example of a template, which we'll suppose is stored in the
+file C<formletter.tmpl>:
+
+ Dear {$title} {$lastname},
+
+ It has come to our attention that you are delinquent in your
+ {$monthname[$last_paid_month]} payment. Please remit
+ ${sprintf("%.2f", $amount)} immediately, or your patellae may
+ be needlessly endangered.
+
+ Love,
+
+ Mark "Vizopteryx" Dominus
+
+The result of filling in this template is a string, which might look
+something like this:
+
+ Dear Mr. Smith,
+
+ It has come to our attention that you are delinquent in your
+ February payment. Please remit
+ $392.12 immediately, or your patellae may
+ be needlessly endangered.
+
+
+ Love,
+
+ Mark "Vizopteryx" Dominus
+
+Here is a complete program that transforms the example
+template into the example result, and prints it out:
+
+ use Text::Template;
+
+ my $template = Text::Template->new(SOURCE => 'formletter.tmpl')
+ or die "Couldn't construct template: $Text::Template::ERROR";
+
+ my @monthname = qw(January February March April May June
+ July August September October November December);
+ my %vars = (title => 'Mr.',
+ firstname => 'John',
+ lastname => 'Smith',
+ last_paid_month => 1, # February
+ amount => 392.12,
+ monthname => \@monthname);
+
+ my $result = $template->fill_in(HASH => \%vars);
+
+ if (defined $result) { print $result }
+ else { die "Couldn't fill in template: $Text::Template::ERROR" }
+
+=head2 Philosophy
+
+When people make a template module like this one, they almost always
+start by inventing a special syntax for substitutions. For example,
+they build it so that a string like C<%%VAR%%> is replaced with the
+value of C<$VAR>. Then they realize the need extra formatting, so
+they put in some special syntax for formatting. Then they need a
+loop, so they invent a loop syntax. Pretty soon they have a new
+little template language.
+
+This approach has two problems: First, their little language is
+crippled. If you need to do something the author hasn't thought of,
+you lose. Second: Who wants to learn another language? You already
+know Perl, so why not use it?
+
+C<Text::Template> templates are programmed in I<Perl>. You embed Perl
+code in your template, with C<{> at the beginning and C<}> at the end.
+If you want a variable interpolated, you write it the way you would in
+Perl. If you need to make a loop, you can use any of the Perl loop
+constructions. All the Perl built-in functions are available.
+
+=head1 Details
+
+=head2 Template Parsing
+
+The C<Text::Template> module scans the template source. An open brace
+C<{> begins a program fragment, which continues until the matching
+close brace C<}>. When the template is filled in, the program
+fragments are evaluated, and each one is replaced with the resulting
+value to yield the text that is returned.
+
+A backslash C<\> in front of a brace (or another backslash that is in
+front of a brace) escapes its special meaning. The result of filling
+out this template:
+
+ \{ The sum of 1 and 2 is {1+2} \}
+
+is
+
+ { The sum of 1 and 2 is 3 }
+
+If you have an unmatched brace, C<Text::Template> will return a
+failure code and a warning about where the problem is. Backslashes
+that do not precede a brace are passed through unchanged. If you have
+a template like this:
+
+ { "String that ends in a newline.\n" }
+
+The backslash inside the string is passed through to Perl unchanged,
+so the C<\n> really does turn into a newline. See the note at the end
+for details about the way backslashes work. Backslash processing is
+I<not> done when you specify alternative delimiters with the
+C<DELIMITERS> option. (See L<"Alternative Delimiters">, below.)
+
+Each program fragment should be a sequence of Perl statements, which
+are evaluated the usual way. The result of the last statement
+executed will be evaluated in scalar context; the result of this
+statement is a string, which is interpolated into the template in
+place of the program fragment itself.
+
+The fragments are evaluated in order, and side effects from earlier
+fragments will persist into later fragments:
+
+ {$x = @things; ''}The Lord High Chamberlain has gotten {$x}
+ things for me this year.
+ { $diff = $x - 17;
+ $more = 'more'
+ if ($diff == 0) {
+ $diff = 'no';
+ } elsif ($diff < 0) {
+ $more = 'fewer';
+ }
+ '';
+ }
+ That is {$diff} {$more} than he gave me last year.
+
+The value of C<$x> set in the first line will persist into the next
+fragment that begins on the third line, and the values of C<$diff> and
+C<$more> set in the second fragment will persist and be interpolated
+into the last line. The output will look something like this:
+
+ The Lord High Chamberlain has gotten 42
+ things for me this year.
+
+ That is 25 more than he gave me last year.
+
+That is all the syntax there is.
+
+=head2 The C<$OUT> variable
+
+There is one special trick you can play in a template. Here is the
+motivation for it: Suppose you are going to pass an array, C<@items>,
+into the template, and you want the template to generate a bulleted
+list with a header, like this:
+
+ Here is a list of the things I have got for you since 1907:
+ * Ivory
+ * Apes
+ * Peacocks
+ * ...
+
+One way to do it is with a template like this:
+
+ Here is a list of the things I have got for you since 1907:
+ { my $blist = '';
+ foreach $i (@items) {
+ $blist .= qq{ * $i\n};
+ }
+ $blist;
+ }
+
+Here we construct the list in a variable called C<$blist>, which we
+return at the end. This is a little cumbersome. There is a shortcut.
+
+Inside of templates, there is a special variable called C<$OUT>.
+Anything you append to this variable will appear in the output of the
+template. Also, if you use C<$OUT> in a program fragment, the normal
+behavior, of replacing the fragment with its return value, is
+disabled; instead the fragment is replaced with the value of C<$OUT>.
+This means that you can write the template above like this:
+
+ Here is a list of the things I have got for you since 1907:
+ { foreach $i (@items) {
+ $OUT .= " * $i\n";
+ }
+ }
+
+C<$OUT> is reinitialized to the empty string at the start of each
+program fragment. It is private to C<Text::Template>, so
+you can't use a variable named C<$OUT> in your template without
+invoking the special behavior.
+
+=head2 General Remarks
+
+All C<Text::Template> functions return C<undef> on failure, and set the
+variable C<$Text::Template::ERROR> to contain an explanation of what
+went wrong. For example, if you try to create a template from a file
+that does not exist, C<$Text::Template::ERROR> will contain something like:
+
+ Couldn't open file xyz.tmpl: No such file or directory
+
+=head2 C<new>
+
+ $template = Text::Template->new( TYPE => ..., SOURCE => ... );
+
+This creates and returns a new template object. C<new> returns
+C<undef> and sets C<$Text::Template::ERROR> if it can't create the
+template object. C<SOURCE> says where the template source code will
+come from. C<TYPE> says what kind of object the source is.
+
+The most common type of source is a file:
+
+ Text::Template->new( TYPE => 'FILE', SOURCE => $filename );
+
+This reads the template from the specified file. The filename is
+opened with the Perl C<open> command, so it can be a pipe or anything
+else that makes sense with C<open>.
+
+The C<TYPE> can also be C<STRING>, in which case the C<SOURCE> should
+be a string:
+
+ Text::Template->new( TYPE => 'STRING',
+ SOURCE => "This is the actual template!" );
+
+The C<TYPE> can be C<ARRAY>, in which case the source should be a
+reference to an array of strings. The concatenation of these strings
+is the template:
+
+ Text::Template->new( TYPE => 'ARRAY',
+ SOURCE => [ "This is ", "the actual",
+ " template!",
+ ]
+ );
+
+The C<TYPE> can be FILEHANDLE, in which case the source should be an
+open filehandle (such as you got from the C<FileHandle> or C<IO::*>
+packages, or a glob, or a reference to a glob). In this case
+C<Text::Template> will read the text from the filehandle up to
+end-of-file, and that text is the template:
+
+ # Read template source code from STDIN:
+ Text::Template->new ( TYPE => 'FILEHANDLE',
+ SOURCE => \*STDIN );
+
+If you omit the C<TYPE> attribute, it's taken to be C<FILE>.
+C<SOURCE> is required. If you omit it, the program will abort.
+
+The words C<TYPE> and C<SOURCE> can be spelled any of the following ways:
+
+ TYPE SOURCE
+ Type Source
+ type source
+ -TYPE -SOURCE
+ -Type -Source
+ -type -source
+
+Pick a style you like and stick with it.
+
+=over 4
+
+=item C<DELIMITERS>
+
+You may also add a C<DELIMITERS> option. If this option is present,
+its value should be a reference to an array 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 L<"Alternative Delimiters">, below.
+
+=item C<ENCODING>
+
+You may also add a C<ENCODING> option. If this option is present, and the
+C<SOURCE> is a C<FILE>, then the data will be decoded from the given encoding
+using the L<Encode> module. You can use any encoding that L<Encode> recognizes.
+E.g.:
+
+ Text::Template->new(
+ TYPE => 'FILE',
+ ENCODING => 'UTF-8',
+ SOURCE => 'xyz.tmpl');
+
+=item C<UNTAINT>
+
+If your program is running in taint mode, you may have problems if
+your templates are stored in files. Data read from files is
+considered 'untrustworthy', and taint mode will not allow you to
+evaluate the Perl code in the file. (It is afraid that a malicious
+person might have tampered with the file.)
+
+In some environments, however, local files are trustworthy. You can
+tell C<Text::Template> that a certain file is trustworthy by supplying
+C<UNTAINT =E<gt> 1> in the call to C<new>. This will tell
+C<Text::Template> to disable taint checks on template code that has
+come from a file, as long as the filename itself is considered
+trustworthy. It will also disable taint checks on template code that
+comes from a filehandle. When used with C<TYPE =E<gt> 'string'> or C<TYPE
+=E<gt> 'array'>, it has no effect.
+
+See L<perlsec> for more complete information about tainting.
+
+Thanks to Steve Palincsar, Gerard Vreeswijk, and Dr. Christoph Baehr
+for help with this feature.
+
+=item C<PREPEND>
+
+This option is passed along to the C<fill_in> call unless it is
+overridden in the arguments to C<fill_in>. See L<C<PREPEND> feature
+and using C<strict> in templates> below.
+
+=item C<BROKEN>
+
+This option is passed along to the C<fill_in> call unless it is
+overridden in the arguments to C<fill_in>. See L<C<BROKEN>> below.
+
+=back
+
+=head2 C<compile>
+
+ $template->compile()
+
+Loads all the template text from the template's source, parses and
+compiles it. If successful, returns true; otherwise returns false and
+sets C<$Text::Template::ERROR>. If the template is already compiled,
+it returns true and does nothing.
+
+You don't usually need to invoke this function, because C<fill_in>
+(see below) compiles the template if it isn't compiled already.
+
+If there is an argument to this function, it must be a reference to an
+array containing alternative delimiter strings. See C<"Alternative
+Delimiters">, below.
+
+=head2 C<fill_in>
+
+ $template->fill_in(OPTIONS);
+
+Fills in a template. Returns the resulting text if successful.
+Otherwise, returns C<undef> and sets C<$Text::Template::ERROR>.
+
+The I<OPTIONS> are a hash, or a list of key-value pairs. You can
+write the key names in any of the six usual styles as above; this
+means that where this manual says C<PACKAGE> (for example) you can
+actually use any of
+
+ PACKAGE Package package -PACKAGE -Package -package
+
+Pick a style you like and stick with it. The all-lowercase versions
+may yield spurious warnings about
+
+ Ambiguous use of package => resolved to "package"
+
+so you might like to avoid them and use the capitalized versions.
+
+At present, there are eight legal options: C<PACKAGE>, C<BROKEN>,
+C<BROKEN_ARG>, C<FILENAME>, C<SAFE>, C<HASH>, C<OUTPUT>, and C<DELIMITERS>.
+
+=over 4
+
+=item C<PACKAGE>
+
+C<PACKAGE> specifies the name of a package in which the program
+fragments should be evaluated. The default is to use the package from
+which C<fill_in> was called. For example, consider this template:
+
+ The value of the variable x is {$x}.
+
+If you use C<$template-E<gt>fill_in(PACKAGE =E<gt> 'R')> , then the C<$x> in
+the template is actually replaced with the value of C<$R::x>. If you
+omit the C<PACKAGE> option, C<$x> will be replaced with the value of
+the C<$x> variable in the package that actually called C<fill_in>.
+
+You should almost always use C<PACKAGE>. If you don't, and your
+template makes changes to variables, those changes will be propagated
+back into the main program. Evaluating the template in a private
+package helps prevent this. The template can still modify variables
+in your program if it wants to, but it will have to do so explicitly.
+See the section at the end on `Security'.
+
+Here's an example of using C<PACKAGE>:
+
+ Your Royal Highness,
+
+ Enclosed please find a list of things I have gotten
+ for you since 1907:
+
+ { foreach $item (@items) {
+ $item_no++;
+ $OUT .= " $item_no. \u$item\n";
+ }
+ }
+
+ Signed,
+ Lord High Chamberlain
+
+We want to pass in an array which will be assigned to the array
+C<@items>. Here's how to do that:
+
+ @items = ('ivory', 'apes', 'peacocks', );
+ $template->fill_in();
+
+This is not very safe. The reason this isn't as safe is that if you
+had a variable named C<$item_no> in scope in your program at the point
+you called C<fill_in>, its value would be clobbered by the act of
+filling out the template. The problem is the same as if you had
+written a subroutine that used those variables in the same way that
+the template does. (C<$OUT> is special in templates and is always
+safe.)
+
+One solution to this is to make the C<$item_no> variable private to the
+template by declaring it with C<my>. If the template does this, you
+are safe.
+
+But if you use the C<PACKAGE> option, you will probably be safe even
+if the template does I<not> declare its variables with C<my>:
+
+ @Q::items = ('ivory', 'apes', 'peacocks', );
+ $template->fill_in(PACKAGE => 'Q');
+
+In this case the template will clobber the variable C<$Q::item_no>,
+which is not related to the one your program was using.
+
+Templates cannot affect variables in the main program that are
+declared with C<my>, unless you give the template references to those
+variables.
+
+=item C<HASH>
+
+You may not want to put the template variables into a package.
+Packages can be hard to manage: You can't copy them, for example.
+C<HASH> provides an alternative.
+
+The value for C<HASH> should be a reference to a hash that maps
+variable names to values. For example,
+
+ $template->fill_in(
+ HASH => {
+ recipient => "The King",
+ items => ['gold', 'frankincense', 'myrrh'],
+ object => \$self,
+ }
+ );
+
+will fill out the template and use C<"The King"> as the value of
+C<$recipient> and the list of items as the value of C<@items>. Note
+that we pass an array reference, but inside the template it appears as
+an array. In general, anything other than a simple string or number
+should be passed by reference.
+
+We also want to pass an object, which is in C<$self>; note that we
+pass a reference to the object, C<\$self> instead. Since we've passed
+a reference to a scalar, inside the template the object appears as
+C<$object>.
+
+The full details of how it works are a little involved, so you might
+want to skip to the next section.
+
+Suppose the key in the hash is I<key> and the value is I<value>.
+
+=over 4
+
+=item *
+
+If the I<value> is C<undef>, then any variables named C<$key>,
+C<@key>, C<%key>, etc., are undefined.
+
+=item *
+
+If the I<value> is a string or a number, then C<$key> is set to that
+value in the template.
+
+=item *
+
+For anything else, you must pass a reference.
+
+If the I<value> is a reference to an array, then C<@key> is set to
+that array. If the I<value> is a reference to a hash, then C<%key> is
+set to that hash. Similarly if I<value> is any other kind of
+reference. This means that
+
+ var => "foo"
+
+and
+
+ var => \"foo"
+
+have almost exactly the same effect. (The difference is that in the
+former case, the value is copied, and in the latter case it is
+aliased.)
+
+=item *
+
+In particular, if you want the template to get an object or any kind,
+you must pass a reference to it:
+
+ $template->fill_in(HASH => { database_handle => \$dbh, ... });
+
+If you do this, the template will have a variable C<$database_handle>
+which is the database handle object. If you leave out the C<\>, the
+template will have a hash C<%database_handle>, which exposes the
+internal structure of the database handle object; you don't want that.
+
+=back
+
+Normally, the way this works is by allocating a private package,
+loading all the variables into the package, and then filling out the
+template as if you had specified that package. A new package is
+allocated each time. However, if you I<also> use the C<PACKAGE>
+option, C<Text::Template> loads the variables into the package you
+specified, and they stay there after the call returns. Subsequent
+calls to C<fill_in> that use the same package will pick up the values
+you loaded in.
+
+If the argument of C<HASH> is a reference to an array instead of a
+reference to a hash, then the array should contain a list of hashes
+whose contents are loaded into the template package one after the
+other. You can use this feature if you want to combine several sets
+of variables. For example, one set of variables might be the defaults
+for a fill-in form, and the second set might be the user inputs, which
+override the defaults when they are present:
+
+ $template->fill_in(HASH => [\%defaults, \%user_input]);
+
+You can also use this to set two variables with the same name:
+
+ $template->fill_in(
+ HASH => [
+ { v => "The King" },
+ { v => [1,2,3] }
+ ]
+ );
+
+This sets C<$v> to C<"The King"> and C<@v> to C<(1,2,3)>.
+
+=item C<BROKEN>
+
+If any of the program fragments fails to compile or aborts for any
+reason, and you have set the C<BROKEN> option to a function reference,
+C<Text::Template> will invoke the function. This function is called
+the I<C<BROKEN> function>. The C<BROKEN> function will tell
+C<Text::Template> what to do next.
+
+If the C<BROKEN> function returns C<undef>, C<Text::Template> will
+immediately abort processing the template and return the text that it
+has accumulated so far. If your function does this, it should set a
+flag that you can examine after C<fill_in> returns so that you can
+tell whether there was a premature return or not.
+
+If the C<BROKEN> function returns any other value, that value will be
+interpolated into the template as if that value had been the return
+value of the program fragment to begin with. For example, if the
+C<BROKEN> function returns an error string, the error string will be
+interpolated into the output of the template in place of the program
+fragment that cased the error.
+
+If you don't specify a C<BROKEN> function, C<Text::Template> supplies
+a default one that returns something like
+
+ Program fragment delivered error ``Illegal division by 0 at
+ template line 37''
+
+(Note that the format of this message has changed slightly since
+version 1.31.) The return value of the C<BROKEN> function is
+interpolated into the template at the place the error occurred, so
+that this template:
+
+ (3+4)*5 = { 3+4)*5 }
+
+yields this result:
+
+ (3+4)*5 = Program fragment delivered error ``syntax error at template line 1''
+
+If you specify a value for the C<BROKEN> attribute, it should be a
+reference to a function that C<fill_in> can call instead of the
+default function.
+
+C<fill_in> will pass a hash to the C<broken> function.
+The hash will have at least these three members:
+
+=over 4
+
+=item C<text>
+
+The source code of the program fragment that failed
+
+=item C<error>
+
+The text of the error message (C<$@>) 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.
+
+=item C<lineno>
+
+The line number of the template at which the program fragment began.
+
+=back
+
+There may also be an C<arg> member. See C<BROKEN_ARG>, below
+
+=item C<BROKEN_ARG>
+
+If you supply the C<BROKEN_ARG> option to C<fill_in>, the value of the
+option is passed to the C<BROKEN> function whenever it is called. The
+default C<BROKEN> function ignores the C<BROKEN_ARG>, but you can
+write a custom C<BROKEN> function that uses the C<BROKEN_ARG> to get
+more information about what went wrong.
+
+The C<BROKEN> function could also use the C<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 = '';
+
+ sub my_broken {
+ my %args = @_;
+ my $err_ref = $args{arg};
+ ...
+ $$err_ref = "Some error message";
+ return undef;
+ }
+
+ $template->fill_in(
+ BROKEN => \&my_broken,
+ BROKEN_ARG => \$error
+ );
+
+ if ($error) {
+ die "It didn't work: $error";
+ }
+
+If one of the program fragments in the template fails, it will call
+the C<BROKEN> function, C<my_broken>, and pass it the C<BROKEN_ARG>,
+which is a reference to C<$error>. C<my_broken> can store an error
+message into C<$error> this way. Then the function that called
+C<fill_in> can see if C<my_broken> has left an error message for it
+to find, and proceed accordingly.
+
+=item C<FILENAME>
+
+If you give C<fill_in> a C<FILENAME> option, then this is the file name that
+you loaded the template source from. This only affects the error message that
+is given for template errors. If you loaded the template from C<foo.txt> for
+example, and pass C<foo.txt> as the C<FILENAME> parameter, errors will look
+like C<... at foo.txt line N> rather than C<... at template line N>.
+
+Note that this does NOT have anything to do with loading a template from the
+given filename. See C<fill_in_file()> for that.
+
+For example:
+
+ my $template = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => 'The value is {1/0}');
+
+ $template->fill_in(FILENAME => 'foo.txt') or die $Text::Template::ERROR;
+
+will die with an error that contains
+
+ Illegal division by zero at at foo.txt line 1
+
+=item C<SAFE>
+
+If you give C<fill_in> a C<SAFE> option, its value should be a safe
+compartment object from the C<Safe> package. All evaluation of
+program fragments will be performed in this compartment. See L<Safe>
+for full details about such compartments and how to restrict the
+operations that can be performed in them.
+
+If you use the C<PACKAGE> option with C<SAFE>, the package you specify
+will be placed into the safe compartment and evaluation will take
+place in that package as usual.
+
+If not, C<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 C<SAFE> mode the evaluation occurs inside the safe compartment
+and cannot affect the calling package. Normally, if you use C<HASH>
+without C<PACKAGE>, the hash variables are imported into a private,
+one-use-only package. But if you use C<HASH> and C<SAFE> together
+without C<PACKAGE>, the hash variables will just be loaded into the
+root namespace of the C<Safe> compartment.
+
+=item C<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
+C<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 C<OUTPUT> option to C<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, ...);
+
+fills in the C<$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 C<OUTPUT>, the return value from C<fill_in> is still true on
+success and false on failure, but the complete text is not returned to
+the caller.
+
+=item C<PREPEND>
+
+You can have some Perl code prepended automatically to the beginning
+of every program fragment. See L<C<PREPEND> feature and using
+C<strict> in templates> below.
+
+=item C<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
+L<"Alternative Delimiters">, below.
+
+If you specify C<DELIMITERS> in the call to C<fill_in>, they override
+any delimiters you set when you created the template object with
+C<new>.
+
+=back
+
+=head1 Convenience Functions
+
+=head2 C<fill_this_in>
+
+The basic way to fill in a template is to create a template object and
+then call C<fill_in> on it. This is useful if you want to fill in
+the same template more than once.
+
+In some programs, this can be cumbersome. C<fill_this_in> accepts a
+string, which contains the template, and a list of options, which are
+passed to C<fill_in> as above. It constructs the template object for
+you, fills it in as specified, and returns the results. It returns
+C<undef> and sets C<$Text::Template::ERROR> if it couldn't generate
+any results.
+
+An example:
+
+ $Q::name = 'Donald';
+ $Q::amount = 141.61;
+ $Q::part = 'hyoid bone';
+
+ $text = Text::Template->fill_this_in( <<'EOM', PACKAGE => Q);
+ Dear {$name},
+ You owe me \\${sprintf('%.2f', $amount)}.
+ Pay or I will break your {$part}.
+ Love,
+ Grand Vizopteryx of Irkutsk.
+ EOM
+
+Notice how we included the template in-line in the program by using a
+`here document' with the C<E<lt>E<lt>> notation.
+
+C<fill_this_in> is a deprecated feature. It is only here for
+backwards compatibility, and may be removed in some far-future version
+in C<Text::Template>. You should use C<fill_in_string> instead. It
+is described in the next section.
+
+=head2 C<fill_in_string>
+
+It is stupid that C<fill_this_in> is a class method. It should have
+been just an imported function, so that you could omit the
+C<Text::Template-E<gt>> in the example above. But I made the mistake
+four years ago and it is too late to change it.
+
+C<fill_in_string> is exactly like C<fill_this_in> except that it is
+not a method and you can omit the C<Text::Template-E<gt>> and just say
+
+ print fill_in_string(<<'EOM', ...);
+ Dear {$name},
+ ...
+ EOM
+
+To use C<fill_in_string>, you need to say
+
+ use Text::Template 'fill_in_string';
+
+at the top of your program. You should probably use
+C<fill_in_string> instead of C<fill_this_in>.
+
+=head2 C<fill_in_file>
+
+If you import C<fill_in_file>, you can say
+
+ $text = fill_in_file(filename, ...);
+
+The C<...> are passed to C<fill_in> as above. The filename is the
+name of the file that contains the template you want to fill in. It
+returns the result text. or C<undef>, as usual.
+
+If you are going to fill in the same file more than once in the same
+program you should use the longer C<new> / C<fill_in> sequence instead.
+It will be a lot faster because it only has to read and parse the file
+once.
+
+=head2 Including files into templates
+
+People always ask for this. ``Why don't you have an include
+function?'' they want to know. The short answer is this is Perl, and
+Perl already has an include function. If you want it, you can just put
+
+ {qx{cat filename}}
+
+into your template. VoilE<agrave>.
+
+If you don't want to use C<cat>, you can write a little four-line
+function that opens a file and dumps out its contents, and call it
+from the template. I wrote one for you. In the template, you can say
+
+ {Text::Template::_load_text(filename)}
+
+If that is too verbose, here is a trick. Suppose the template package
+that you are going to be mentioning in the C<fill_in> call is package
+C<Q>. Then in the main program, write
+
+ *Q::include = \&Text::Template::_load_text;
+
+This imports the C<_load_text> function into package C<Q> with the
+name C<include>. From then on, any template that you fill in with
+package C<Q> can say
+
+ {include(filename)}
+
+to insert the text from the named file at that point. If you are
+using the C<HASH> option instead, just put C<include =E<gt>
+\&Text::Template::_load_text> into the hash instead of importing it
+explicitly.
+
+Suppose you don't want to insert a plain text file, but rather you
+want to include one template within another? Just use C<fill_in_file>
+in the template itself:
+
+ {Text::Template::fill_in_file(filename)}
+
+You can do the same importing trick if this is too much to type.
+
+=head1 Miscellaneous
+
+=head2 C<my> variables
+
+People are frequently surprised when this doesn't work:
+
+ my $recipient = 'The King';
+ my $text = fill_in_file('formletter.tmpl');
+
+The text C<The King> doesn't get into the form letter. Why not?
+Because C<$recipient> is a C<my> variable, and the whole point of
+C<my> variables is that they're private and inaccessible except in the
+scope in which they're declared. The template is not part of that
+scope, so the template can't see C<$recipient>.
+
+If that's not the behavior you want, don't use C<my>. C<my> means a
+private variable, and in this case you don't want the variable to be
+private. Put the variables into package variables in some other
+package, and use the C<PACKAGE> option to C<fill_in>:
+
+ $Q::recipient = $recipient;
+ my $text = fill_in_file('formletter.tmpl', PACKAGE => 'Q');
+
+or pass the names and values in a hash with the C<HASH> option:
+
+ my $text = fill_in_file('formletter.tmpl', HASH => { recipient => $recipient });
+
+=head2 Security Matters
+
+All variables are evaluated in the package you specify with the
+C<PACKAGE> option of C<fill_in>. if you use this option, and if your
+templates don't do anything egregiously stupid, you won't have to
+worry that evaluation of the little programs will creep out into the
+rest of your program and wreck something.
+
+Nevertheless, there's really no way (except with C<Safe>) to protect
+against a template that says
+
+ { $Important::Secret::Security::Enable = 0;
+ # Disable security checks in this program
+ }
+
+or
+
+ { $/ = "ho ho ho"; # Sabotage future uses of <FH>.
+ # $/ is always a global variable
+ }
+
+or even
+
+ { system("rm -rf /") }
+
+so B<don't> go filling in templates unless you're sure you know what's
+in them. If you're worried, or you can't trust the person who wrote
+the template, use the C<SAFE> option.
+
+A final warning: program fragments run a small risk of accidentally
+clobbering local variables in the C<fill_in> function itself. These
+variables all have names that begin with C<$fi_>, so if you stay away
+from those names you'll be safe. (Of course, if you're a real wizard
+you can tamper with them deliberately for exciting effects; this is
+actually how C<$OUT> works.) I can fix this, but it will make the
+package slower to do it, so I would prefer not to. If you are worried
+about this, send me mail and I will show you what to do about it.
+
+=head2 Alternative Delimiters
+
+Lorenzo Valdettaro pointed out that if you are using C<Text::Template>
+to generate TeX output, the choice of braces as the program fragment
+delimiters makes you suffer suffer suffer. Starting in version 1.20,
+you can change the choice of delimiters to something other than curly
+braces.
+
+In either the C<new()> call or the C<fill_in()> call, you can specify
+an alternative set of delimiters with the C<DELIMITERS> option. For
+example, if you would like code fragments to be delimited by C<[@-->
+and C<--@]> instead of C<{> and C<}>, use
+
+ ... DELIMITERS => [ '[@--', '--@]' ], ...
+
+Note that these delimiters are I<literal strings>, not regexes. (I
+tried for regexes, but it complicates the lexical analysis too much.)
+Note also that C<DELIMITERS> disables the special meaning of the
+backslash, so if you want to include the delimiters in the literal
+text of your template file, you are out of luck---it is up to you to
+choose delimiters that do not conflict with what you are doing. The
+delimiter strings may still appear inside of program fragments as long
+as they nest properly. This means that if for some reason you
+absolutely must have a program fragment that mentions one of the
+delimiters, like this:
+
+ [@--
+ print "Oh no, a delimiter: --@]\n"
+ --@]
+
+you may be able to make it work by doing this instead:
+
+ [@--
+ # Fake matching delimiter in a comment: [@--
+ print "Oh no, a delimiter: --@]\n"
+ --@]
+
+It may be safer to choose delimiters that begin with a newline
+character.
+
+Because the parsing of templates is simplified by the absence of
+backslash escapes, using alternative C<DELIMITERS> may speed up the
+parsing process by 20-25%. This shows that my original choice of C<{>
+and C<}> was very bad.
+
+=head2 C<PREPEND> feature and using C<strict> in templates
+
+Suppose you would like to use C<strict> in your templates to detect
+undeclared variables and the like. But each code fragment is a
+separate lexical scope, so you have to turn on C<strict> at the top of
+each and every code fragment:
+
+ { use strict;
+ use vars '$foo';
+ $foo = 14;
+ ...
+ }
+
+ ...
+
+ { # we forgot to put `use strict' here
+ my $result = $boo + 12; # $boo is misspelled and should be $foo
+ # No error is raised on `$boo'
+ }
+
+Because we didn't put C<use strict> at the top of the second fragment,
+it was only active in the first fragment, and we didn't get any
+C<strict> checking in the second fragment. Then we misspelled C<$foo>
+and the error wasn't caught.
+
+C<Text::Template> version 1.22 and higher has a new feature to make
+this easier. You can specify that any text at all be automatically
+added to the beginning of each program fragment.
+
+When you make a call to C<fill_in>, you can specify a
+
+ PREPEND => 'some perl statements here'
+
+option; the statements will be prepended to each program fragment for
+that one call only. Suppose that the C<fill_in> call included a
+
+ PREPEND => 'use strict;'
+
+option, and that the template looked like this:
+
+ { use vars '$foo';
+ $foo = 14;
+ ...
+ }
+
+ ...
+
+ { my $result = $boo + 12; # $boo is misspelled and should be $foo
+ ...
+ }
+
+The code in the second fragment would fail, because C<$boo> has not
+been declared. C<use strict> was implied, even though you did not
+write it explicitly, because the C<PREPEND> option added it for you
+automatically.
+
+There are three other ways to do this. At the time you create the
+template object with C<new>, you can also supply a C<PREPEND> option,
+in which case the statements will be prepended each time you fill in
+that template. If the C<fill_in> call has its own C<PREPEND> option,
+this overrides the one specified at the time you created the
+template. Finally, you can make the class method call
+
+ Text::Template->always_prepend('perl statements');
+
+If you do this, then call calls to C<fill_in> for I<any> template will
+attach the perl statements to the beginning of each program fragment,
+except where overridden by C<PREPEND> options to C<new> or C<fill_in>.
+
+An alternative to adding "use strict;" to the PREPEND option, you can
+pass STRICT => 1 to fill_in when also passing the HASH option.
+
+Suppose that the C<fill_in> call included both
+
+ HASH => {$foo => ''} and
+ STRICT => 1
+
+options, and that the template looked like this:
+
+ {
+ $foo = 14;
+ ...
+ }
+
+ ...
+
+ { my $result = $boo + 12; # $boo is misspelled and should be $foo
+ ...
+ }
+
+The code in the second fragment would fail, because C<$boo> has not
+been declared. C<use strict> was implied, even though you did not
+write it explicitly, because the C<STRICT> option added it for you
+automatically. Any variable referenced in the template that is not in the
+C<HASH> option will be an error.
+
+=head2 Prepending in Derived Classes
+
+This section is technical, and you should skip it on the first few
+readings.
+
+Normally there are three places that prepended text could come from.
+It could come from the C<PREPEND> option in the C<fill_in> call, from
+the C<PREPEND> option in the C<new> call that created the template
+object, or from the argument of the C<always_prepend> call.
+C<Text::Template> looks for these three things in order and takes the
+first one that it finds.
+
+In a subclass of C<Text::Template>, this last possibility is
+ambiguous. Suppose C<S> is a subclass of C<Text::Template>. Should
+
+ Text::Template->always_prepend(...);
+
+affect objects in class C<Derived>? The answer is that you can have it
+either way.
+
+The C<always_prepend> value for C<Text::Template> is normally stored
+in a hash variable named C<%GLOBAL_PREPEND> under the key
+C<Text::Template>. When C<Text::Template> looks to see what text to
+prepend, it first looks in the template object itself, and if not, it
+looks in C<$GLOBAL_PREPEND{I<class>}> where I<class> is the class to
+which the template object belongs. If it doesn't find any value, it
+looks in C<$GLOBAL_PREPEND{'Text::Template'}>. This means that
+objects in class C<Derived> I<will> be affected by
+
+ Text::Template->always_prepend(...);
+
+I<unless> there is also a call to
+
+ Derived->always_prepend(...);
+
+So when you're designing your derived class, you can arrange to have
+your objects ignore C<Text::Template::always_prepend> calls by simply
+putting C<Derived-E<gt>always_prepend('')> at the top of your module.
+
+Of course, there is also a final escape hatch: Templates support a
+C<prepend_text> that is used to look up the appropriate text to be
+prepended at C<fill_in> time. Your derived class can override this
+method to get an arbitrary effect.
+
+=head2 JavaScript
+
+Jennifer D. St Clair asks:
+
+ > Most of my pages contain JavaScript and Stylesheets.
+ > How do I change the template identifier?
+
+Jennifer is worried about the braces in the JavaScript being taken as
+the delimiters of the Perl program fragments. Of course, disaster
+will ensue when perl tries to evaluate these as if they were Perl
+programs. The best choice is to find some unambiguous delimiter
+strings that you can use in your template instead of curly braces, and
+then use the C<DELIMITERS> option. However, if you can't do this for
+some reason, there are two easy workarounds:
+
+1. You can put C<\> in front of C<{>, C<}>, or C<\> to remove its
+special meaning. So, for example, instead of
+
+ if (br== "n3") {
+ // etc.
+ }
+
+you can put
+
+ if (br== "n3") \{
+ // etc.
+ \}
+
+and it'll come out of the template engine the way you want.
+
+But here is another method that is probably better. To see how it
+works, first consider what happens if you put this into a template:
+
+ { 'foo' }
+
+Since it's in braces, it gets evaluated, and obviously, this is going
+to turn into
+
+ foo
+
+So now here's the trick: In Perl, C<q{...}> is the same as C<'...'>.
+So if we wrote
+
+ {q{foo}}
+
+it would turn into
+
+ foo
+
+So for your JavaScript, just write
+
+ {q{if (br== "n3") {
+ // etc.
+ }}
+ }
+
+and it'll come out as
+
+ if (br== "n3") {
+ // etc.
+ }
+
+which is what you want.
+
+head2 Shut Up!
+
+People sometimes try to put an initialization section at the top of
+their templates, like this:
+
+ { ...
+ $var = 17;
+ }
+
+Then they complain because there is a C<17> at the top of the output
+that they didn't want to have there.
+
+Remember that a program fragment is replaced with its own return
+value, and that in Perl the return value of a code block is the value
+of the last expression that was evaluated, which in this case is 17.
+If it didn't do that, you wouldn't be able to write C<{$recipient}>
+and have the recipient filled in.
+
+To prevent the 17 from appearing in the output is very simple:
+
+ { ...
+ $var = 17;
+ '';
+ }
+
+Now the last expression evaluated yields the empty string, which is
+invisible. If you don't like the way this looks, use
+
+ { ...
+ $var = 17;
+ ($SILENTLY);
+ }
+
+instead. Presumably, C<$SILENTLY> has no value, so nothing will be
+interpolated. This is what is known as a `trick'.
+
+=head2 Compatibility
+
+Every effort has been made to make this module compatible with older
+versions. The only known exceptions follow:
+
+The output format of the default C<BROKEN> subroutine has changed
+twice, most recently between versions 1.31 and 1.40.
+
+Starting in version 1.10, the C<$OUT> variable is arrogated for a
+special meaning. If you had templates before version 1.10 that
+happened to use a variable named C<$OUT>, you will have to change them
+to use some other variable or all sorts of strangeness will result.
+
+Between versions 0.1b and 1.00 the behavior of the \ metacharacter
+changed. In 0.1b, \\ was special everywhere, and the template
+processor always replaced it with a single backslash before passing
+the code to Perl for evaluation. The rule now is more complicated but
+probably more convenient. See the section on backslash processing,
+below, for a full discussion.
+
+=head2 Backslash Processing
+
+In C<Text::Template> beta versions, the backslash was special whenever
+it appeared before a brace or another backslash. That meant that
+while C<{"\n"}> did indeed generate a newline, C<{"\\"}> did not
+generate a backslash, because the code passed to Perl for evaluation
+was C<"\"> which is a syntax error. If you wanted a backslash, you
+would have had to write C<{"\\\\"}>.
+
+In C<Text::Template> versions 1.00 through 1.10, there was a bug:
+Backslash was special everywhere. In these versions, C<{"\n"}>
+generated the letter C<n>.
+
+The bug has been corrected in version 1.11, but I did not go back to
+exactly the old rule, because I did not like the idea of having to
+write C<{"\\\\"}> to get one backslash. The rule is now more
+complicated to remember, but probably easier to use. The rule is now:
+Backslashes are always passed to Perl unchanged I<unless> they occur
+as part of a sequence like C<\\\\\\{> or C<\\\\\\}>. In these
+contexts, they are special; C<\\> is replaced with C<\>, and C<\{> and
+C<\}> signal a literal brace.
+
+Examples:
+
+ \{ foo \}
+
+is I<not> evaluated, because the C<\> before the braces signals that
+they should be taken literally. The result in the output looks like this:
+
+ { foo }
+
+This is a syntax error:
+
+ { "foo}" }
+
+because C<Text::Template> thinks that the code ends at the first C<}>,
+and then gets upset when it sees the second one. To make this work
+correctly, use
+
+ { "foo\}" }
+
+This passes C<"foo}"> to Perl for evaluation. Note there's no C<\> in
+the evaluated code. If you really want a C<\> in the evaluated code,
+use
+
+ { "foo\\\}" }
+
+This passes C<"foo\}"> to Perl for evaluation.
+
+Starting with C<Text::Template> version 1.20, backslash processing is
+disabled if you use the C<DELIMITERS> option to specify alternative
+delimiter strings.
+
+=head2 A short note about C<$Text::Template::ERROR>
+
+In the past some people have fretted about `violating the package
+boundary' by examining a variable inside the C<Text::Template>
+package. Don't feel this way. C<$Text::Template::ERROR> is part of
+the published, official interface to this package. It is perfectly OK
+to inspect this variable. The interface is not going to change.
+
+If it really, really bothers you, you can import a function called
+C<TTerror> that returns the current value of the C<$ERROR> variable.
+So you can say:
+
+ use Text::Template 'TTerror';
+
+ my $template = Text::Template->new(SOURCE => $filename);
+ unless ($template) {
+ my $err = TTerror;
+ die "Couldn't make template: $err; aborting";
+ }
+
+I don't see what benefit this has over just doing this:
+
+ use Text::Template;
+
+ my $template = Text::Template->new(SOURCE => $filename)
+ or die "Couldn't make template: $Text::Template::ERROR; aborting";
+
+But if it makes you happy to do it that way, go ahead.
+
+=head2 Sticky Widgets in Template Files
+
+The C<CGI> module provides functions for `sticky widgets', which are
+form input controls that retain their values from one page to the
+next. Sometimes people want to know how to include these widgets
+into their template output.
+
+It's totally straightforward. Just call the C<CGI> functions from
+inside the template:
+
+ { $q->checkbox_group(NAME => 'toppings',
+ LINEBREAK => true,
+ COLUMNS => 3,
+ VALUES => \@toppings,
+ );
+ }
+
+=head2 Automatic preprocessing of program fragments
+
+It may be useful to preprocess the program fragments before they are
+evaluated. See C<Text::Template::Preprocess> for more details.
+
+=head2 Automatic postprocessing of template hunks
+
+It may be useful to process hunks of output before they are appended to
+the result text. For this, subclass and replace the C<append_text_to_result>
+method. It is passed a list of pairs with these entries:
+
+ handle - a filehandle to which to print the desired output
+ out - a ref to a string to which to append, to use if handle is not given
+ text - the text that will be appended
+ type - where the text came from: TEXT for literal text, PROG for code
+
+=head1 HISTORY
+
+Originally written by Mark Jason Dominus, Plover Systems (versions 0.01 - 1.46)
+
+Maintainership transferred to Michael Schout E<lt>mschout@cpan.orgE<gt> in version
+1.47
+
+=head1 THANKS
+
+Many thanks to the following people for offering support,
+encouragement, advice, bug reports, and all the other good stuff.
+
+=over 4
+
+=item *
+
+Andrew G Wood
+
+=item *
+
+Andy Wardley
+
+=item *
+
+António Aragão
+
+=item *
+
+Archie Warnock
+
+=item *
+
+Bek Oberin
+
+=item *
+
+Bob Dougherty
+
+=item *
+
+Brian C. Shensky
+
+=item *
+
+Chris Nandor
+
+=item *
+
+Chris Wesley
+
+=item *
+
+Chris.Brezil
+
+=item *
+
+Daini Xie
+
+=item *
+
+Dan Franklin
+
+=item *
+
+Daniel LaLiberte
+
+=item *
+
+David H. Adler
+
+=item *
+
+David Marshall
+
+=item *
+
+Dennis Taylor
+
+=item *
+
+Donald L. Greer Jr.
+
+=item *
+
+Dr. Frank Bucolo
+
+=item *
+
+Fred Steinberg
+
+=item *
+
+Gene Damon
+
+=item *
+
+Hans Persson
+
+=item *
+
+Hans Stoop
+
+=item *
+
+Itamar Almeida de Carvalho
+
+=item *
+
+James H. Thompson
+
+=item *
+
+James Mastros
+
+=item *
+
+Jarko Hietaniemi
+
+=item *
+
+Jason Moore
+
+=item *
+
+Jennifer D. St Clair
+
+=item *
+
+Joel Appelbaum
+
+=item *
+
+Joel Meulenberg
+
+=item *
+
+Jonathan Roy
+
+=item *
+
+Joseph Cheek
+
+=item *
+
+Juan E. Camacho
+
+=item *
+
+Kevin Atteson
+
+=item *
+
+Kevin Madsen
+
+=item *
+
+Klaus Arnhold
+
+=item *
+
+Larry Virden
+
+=item *
+
+Lieven Tomme
+
+=item *
+
+Lorenzo Valdettaro
+
+=item *
+
+Marek Grac
+
+=item *
+
+Matt Womer
+
+=item *
+
+Matt X. Hunter
+
+=item *
+
+Michael G Schwern
+
+=item *
+
+Michael J. Suzio
+
+=item *
+
+Michaely Yeung
+
+=item *
+
+Michelangelo Grigni
+
+=item *
+
+Mike Brodhead
+
+=item *
+
+Niklas Skoglund
+
+=item *
+
+Randal L. Schwartz
+
+=item *
+
+Reuven M. Lerner
+
+=item *
+
+Robert M. Ioffe
+
+=item *
+
+Ron Pero
+
+=item *
+
+San Deng
+
+=item *
+
+Sean Roehnelt
+
+=item *
+
+Sergey Myasnikov
+
+=item *
+
+Shabbir J. Safdar
+
+=item *
+
+Shad Todd
+
+=item *
+
+Steve Palincsar
+
+=item *
+
+Tim Bunce
+
+=item *
+
+Todd A. Green
+
+=item *
+
+Tom Brown
+
+=item *
+
+Tom Henry
+
+=item *
+
+Tom Snee
+
+=item *
+
+Trip Lilley
+
+=item *
+
+Uwe Schneider
+
+=item *
+
+Val Luck
+
+=item *
+
+Yannis Livassof
+
+=item *
+
+Yonat Sharon
+
+=item *
+
+Zac Hansen
+
+=item *
+
+gary at dls.net
+
+=back
+
+Special thanks to:
+
+=over 2
+
+=item Jonathan Roy
+
+for telling me how to do the C<Safe> support (I spent two years
+worrying about it, and then Jonathan pointed out that it was trivial.)
+
+=item Ranjit Bhatnagar
+
+for demanding less verbose fragments like they have in ASP, for
+helping me figure out the Right Thing, and, especially, for talking me
+out of adding any new syntax. These discussions resulted in the
+C<$OUT> feature.
+
+=back
+
+=head2 Bugs and Caveats
+
+C<my> variables in C<fill_in> are still susceptible to being clobbered
+by template evaluation. They all begin with C<fi_>, so avoid those
+names in your templates.
+
+The line number information will be wrong if the template's lines are
+not terminated by C<"\n">. You should let me know if this is a
+problem. If you do, I will fix it.
+
+The C<$OUT> variable has a special meaning in templates, so you cannot
+use it as if it were a regular variable.
+
+There are not quite enough tests in the test suite.
+
+=head1 SOURCE
+
+The development version is on github at L<https://https://github.com/mschout/perl-text-template>
+and may be cloned from L<git://https://github.com/mschout/perl-text-template.git>
+
+=head1 BUGS
+
+Please report any bugs or feature requests on the bugtracker website
+L<https://github.com/mschout/perl-text-template/issues>
+
+When submitting a bug or request, please include a test-file or a
+patch to an existing test-file that illustrates the bug or desired
+feature.
+
+=head1 AUTHOR
+
+Michael Schout <mschout@cpan.org>
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
--- /dev/null
+
+package Text::Template::Preprocess;
+$Text::Template::Preprocess::VERSION = '1.56';
+# ABSTRACT: Expand template text with embedded Perl
+
+use strict;
+use warnings;
+
+use Text::Template;
+our @ISA = qw(Text::Template);
+
+sub fill_in {
+ my $self = shift;
+ my (%args) = @_;
+
+ my $pp = $args{PREPROCESSOR} || $self->{PREPROCESSOR};
+
+ if ($pp) {
+ local $_ = $self->source();
+ my $type = $self->{TYPE};
+
+ # print "# fill_in: before <$_>\n";
+ &$pp;
+
+ # print "# fill_in: after <$_>\n";
+ $self->set_source_data($_, $type);
+ }
+
+ $self->SUPER::fill_in(@_);
+}
+
+sub preprocessor {
+ my ($self, $pp) = @_;
+
+ my $old_pp = $self->{PREPROCESSOR};
+
+ $self->{PREPROCESSOR} = $pp if @_ > 1; # OK to pass $pp=undef
+
+ $old_pp;
+}
+
+1;
+
+__END__
+
+=pod
+
+=encoding UTF-8
+
+=head1 NAME
+
+Text::Template::Preprocess - Expand template text with embedded Perl
+
+=head1 VERSION
+
+version 1.56
+
+=head1 SYNOPSIS
+
+ use Text::Template::Preprocess;
+
+ my $t = Text::Template::Preprocess->new(...); # identical to Text::Template
+
+ # Fill in template, but preprocess each code fragment with pp().
+ my $result = $t->fill_in(..., PREPROCESSOR => \&pp);
+
+ my $old_pp = $t->preprocessor(\&new_pp);
+
+=head1 DESCRIPTION
+
+C<Text::Template::Preprocess> provides a new C<PREPROCESSOR> option to
+C<fill_in>. If the C<PREPROCESSOR> option is supplied, it must be a
+reference to a preprocessor subroutine. When filling out a template,
+C<Text::Template::Preprocessor> will use this subroutine to preprocess
+the program fragment prior to evaluating the code.
+
+The preprocessor subroutine will be called repeatedly, once for each
+program fragment. The program fragment will be in C<$_>. The
+subroutine should modify the contents of C<$_> and return.
+C<Text::Template::Preprocess> will then execute contents of C<$_> and
+insert the result into the appropriate part of the template.
+
+C<Text::Template::Preprocess> objects also support a utility method,
+C<preprocessor()>, which sets a new preprocessor for the object. This
+preprocessor is used for all subsequent calls to C<fill_in> except
+where overridden by an explicit C<PREPROCESSOR> option.
+C<preprocessor()> returns the previous default preprocessor function,
+or undefined if there wasn't one. When invoked with no arguments,
+C<preprocessor()> returns the object's current default preprocessor
+function without changing it.
+
+In all other respects, C<Text::Template::Preprocess> is identical to
+C<Text::Template>.
+
+=head1 WHY?
+
+One possible purpose: If your files contain a lot of JavaScript, like
+this:
+
+ Plain text here...
+ { perl code }
+ <script language=JavaScript>
+ if (br== "n3") {
+ // etc.
+ }
+ </script>
+ { more perl code }
+ More plain text...
+
+You don't want C<Text::Template> to confuse the curly braces in the
+JavaScript program with executable Perl code. One strategy:
+
+ sub quote_scripts {
+ s(<script(.*?)</script>)(q{$1})gsi;
+ }
+
+Then use C<PREPROCESSOR =E<gt> \"e_scripts>. This will transform
+
+=head1 SEE ALSO
+
+L<Text::Template>
+
+=head1 SOURCE
+
+The development version is on github at L<https://https://github.com/mschout/perl-text-template>
+and may be cloned from L<git://https://github.com/mschout/perl-text-template.git>
+
+=head1 BUGS
+
+Please report any bugs or feature requests on the bugtracker website
+L<https://github.com/mschout/perl-text-template/issues>
+
+When submitting a bug or request, please include a test-file or a
+patch to an existing test-file that illustrates the bug or desired
+feature.
+
+=head1 AUTHOR
+
+Mark Jason Dominus, Plover Systems
+
+Please send questions and other remarks about this software to
+C<mjd-perl-template+@plover.com>
+
+You can join a very low-volume (E<lt>10 messages per year) mailing
+list for announcements about this package. Send an empty note to
+C<mjd-perl-template-request@plover.com> to join.
+
+For updates, visit C<http://www.plover.com/~mjd/perl/Template/>.
+
+=head1 COPYRIGHT AND LICENSE
+
+This software is copyright (c) 2013 by Mark Jason Dominus <mjd@cpan.org>.
+
+This is free software; you can redistribute it and/or modify it under
+the same terms as the Perl 5 programming language system itself.
+
+=cut
--- /dev/null
+#!perl
+
+BEGIN {
+ unless ($ENV{AUTHOR_TESTING}) {
+ print qq{1..0 # SKIP these tests are for testing by the author\n};
+ exit
+ }
+}
+
+# This file was automatically generated by Dist::Zilla::Plugin::PodSyntaxTests.
+use strict; use warnings;
+use Test::More;
+use Test::Pod 1.41;
+
+all_pod_files_ok();
--- /dev/null
+#!perl -w
+
+BEGIN {
+ unless ($ENV{AUTHOR_TESTING}) {
+ print qq{1..0 # SKIP these tests are for testing by the author\n};
+ exit
+ }
+}
+
+# This file was automatically generated by Dist::Zilla::Plugin::AuthorSignatureTest
+
+use strict;
+use warnings;
+use Test::More;
+
+unless (eval { require Test::Signature; 1 }) {
+ plan skip_all => 'Test::Signature is required for this test';
+}
+
+Test::Signature::signature_ok();
+done_testing;
--- /dev/null
+#!perl
+#
+# Tests of basic, essential functionality
+#
+
+use strict;
+use warnings;
+use Test::More tests => 34;
+use File::Temp;
+
+my $tmpfile = File::Temp->new;
+
+use_ok 'Text::Template' or exit 1;
+
+$X::v = $Y::v = 0; # Suppress `var used only once'
+
+my $template_1 = <<EOM;
+We will put value of \$v (which is "abc") here -> {\$v}
+We will evaluate 1+1 here -> {1 + 1}
+EOM
+
+# (1) Construct temporary template file for testing
+# file operations
+my $TEMPFILE = $tmpfile->filename;
+
+eval {
+ open my $tmp, '>', $TEMPFILE
+ or die "Couldn't write tempfile $TEMPFILE: $!";
+
+ print $tmp $template_1;
+ close $tmp;
+
+ pass;
+};
+if ($@) {
+ fail $@;
+}
+
+# (2) Build template from file
+my $template = Text::Template->new('type' => 'FILE', 'source' => $TEMPFILE);
+ok(defined $template) or diag $Text::Template::ERROR;
+
+# (3) Fill in template from file
+$X::v = "abc";
+my $resultX = <<EOM;
+We will put value of \$v (which is "abc") here -> abc
+We will evaluate 1+1 here -> 2
+EOM
+$Y::v = "ABC";
+my $resultY = <<EOM;
+We will put value of \$v (which is "abc") here -> ABC
+We will evaluate 1+1 here -> 2
+EOM
+
+my $text = $template->fill_in('package' => 'X');
+is $text, $resultX;
+
+# (4) Fill in same template again
+$text = $template->fill_in('package' => 'Y');
+is $text, $resultY;
+
+# (5) Simple test of `fill_this_in'
+$text = Text::Template->fill_this_in($template_1, 'package' => 'X');
+is $text, $resultX;
+
+# (6) test creation of template from filehandle
+open my $tmpl, '<', $TEMPFILE or die "failed to open $TEMPFILE: $!";
+
+$template = Text::Template->new(type => 'FILEHANDLE', source => $tmpl);
+ok defined $template or diag $Text::Template::ERROR;
+
+# (7) test filling in of template from filehandle
+$text = $template->fill_in('package' => 'X');
+is $text, $resultX;
+
+# (8) test second fill_in on same template object
+$text = $template->fill_in('package' => 'Y');
+is $text, $resultY;
+
+close $tmpl;
+
+# (9) test creation of template from array
+$template = Text::Template->new(
+ type => 'ARRAY',
+ source => [
+ 'We will put value of $v (which is "abc") here -> {$v}', "\n",
+ 'We will evaluate 1+1 here -> {1+1}', "\n"
+ ]
+);
+
+ok defined $template; # or diag $Text::Template::ERROR;
+
+# (10) test filling in of template from array
+$text = $template->fill_in('package' => 'X');
+is $text, $resultX;
+
+# (11) test second fill_in on same array template object
+$text = $template->fill_in('package' => 'Y');
+is $text, $resultY;
+
+# (12) Make sure \ is working properly
+# Test added for version 1.11
+$tmpl = Text::Template->new(TYPE => 'STRING', SOURCE => 'B{"\\}"}C{"\\{"}D');
+
+# This should fail if the \ are not interpreted properly.
+$text = $tmpl->fill_in();
+is $text, 'B}C{D';
+
+# (13) Make sure \ is working properly
+# Test added for version 1.11
+$tmpl = Text::Template->new(TYPE => 'STRING', SOURCE => qq{A{"\t"}B});
+
+# Symptom of old problem: ALL \ were special in templates, so
+# The lexer would return (A, PROGTEXT("t"), B), and the
+# result text would be AtB instead of A(tab)B.
+$text = $tmpl->fill_in();
+
+is $text, "A\tB";
+
+# (14-27) Make sure \ is working properly
+# Test added for version 1.11
+# This is a sort of general test.
+my @tests = (
+ '{""}' => '', # (14)
+ '{"}"}' => undef, # (15)
+ '{"\\}"}' => '}', # One backslash
+ '{"\\\\}"}' => undef, # Two backslashes
+ '{"\\\\\\}"}' => '}', # Three backslashes
+ '{"\\\\\\\\}"}' => undef, # Four backslashes
+ '{"\\\\\\\\\\}"}' => '\}', # Five backslashes (20)
+ '{"x20"}' => 'x20',
+ '{"\\x20"}' => ' ', # One backslash
+ '{"\\\\x20"}' => '\\x20', # Two backslashes
+ '{"\\\\\\x20"}' => '\\ ', # Three backslashes
+ '{"\\\\\\\\x20"}' => '\\\\x20', # Four backslashes (25)
+ '{"\\\\\\\\\\x20"}' => '\\\\ ', # Five backslashes
+ '{"\\x20\\}"}' => ' }', # (27)
+);
+
+while (my ($test, $result) = splice @tests, 0, 2) {
+ my $tmpl = Text::Template->new(TYPE => 'STRING', SOURCE => $test);
+ my $text = $tmpl->fill_in;
+
+ ok(!defined $text && !defined $result || $text eq $result)
+ or diag "expected .$result. got .$text.";
+}
+
+# (28-30) I discovered that you can't pass a glob ref as your filehandle.
+# MJD 20010827
+# (28) test creation of template from filehandle
+$tmpl = undef;
+ok(open $tmpl, '<', $TEMPFILE) or diag "Couldn't open $TEMPFILE: $!";
+$template = Text::Template->new(type => 'FILEHANDLE', source => $tmpl);
+ok(defined $template) or diag $Text::Template::ERROR;
+
+# (29) test filling in of template from filehandle
+$text = $template->fill_in('package' => 'X');
+is $text, $resultX;
+
+# (30) test second fill_in on same template object
+$text = $template->fill_in('package' => 'Y');
+is $text, $resultY;
+
+close $tmpl;
+
+# (31) Test _scrubpkg for leakiness
+$Text::Template::GEN0::test = 1;
+Text::Template::_scrubpkg('Text::Template::GEN0');
+ok !($Text::Template::GEN0::test
+ || exists $Text::Template::GEN0::{test}
+ || exists $Text::Template::{'GEN0::'});
+
+# that filename parameter works. we use BROKEN to verify this
+$text = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => 'Hello {1/0}'
+)->fill_in(FILENAME => 'foo.txt');
+
+like $text, qr/division by zero at foo\.txt line 1/;
--- /dev/null
+#!perl
+# test apparatus for Text::Template module
+
+use strict;
+use warnings;
+use Test::More tests => 7;
+
+use_ok 'Text::Template' or exit 1;
+
+# (1) basic error delivery
+{
+ my $r = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => '{1/0}',)->fill_in();
+ is $r, q{Program fragment delivered error ``Illegal division by zero at template line 1.''};
+}
+
+# (2) BROKEN sub called in ->new?
+{
+ my $r = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => '{1/0}',
+ BROKEN => sub { '---' },)->fill_in();
+ is $r, q{---};
+}
+
+# (3) BROKEN sub called in ->fill_in?
+{
+ my $r = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => '{1/0}',)->fill_in(BROKEN => sub { '---' });
+ is $r, q{---};
+}
+
+# (4) BROKEN sub passed correct args when called in ->new?
+{
+ my $r = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => '{1/0}',
+ BROKEN => sub {
+ my %a = @_;
+ qq{$a{lineno},$a{error},$a{text}};
+ },)->fill_in();
+ is $r, qq{1,Illegal division by zero at template line 1.\n,1/0};
+}
+
+# (5) BROKEN sub passed correct args when called in ->fill_in?
+{
+ my $r = Text::Template->new(
+ TYPE => 'string',
+ SOURCE => '{1/0}',
+ )->fill_in(
+ BROKEN => sub {
+ my %a = @_;
+ qq{$a{lineno},$a{error},$a{text}};
+ });
+ is $r, qq{1,Illegal division by zero at template line 1.\n,1/0};
+}
+
+# BROKEN sub handles undef
+{
+ my $r = Text::Template->new(TYPE => 'string', SOURCE => 'abc{1/0}defg')
+ ->fill_in(BROKEN => sub { undef });
+
+ is $r, 'abc';
+}
--- /dev/null
+#!perl
+#
+# Tests for user-specified delimiter functions
+# These tests first appeared in version 1.20.
+
+use strict;
+use warnings;
+use Test::More tests => 19;
+
+use_ok 'Text::Template' or exit 1;
+
+# (1) Try a simple delimiter: <<..>>
+# First with the delimiters specified at object creation time
+our $V = $V = 119;
+my $template = q{The value of $V is <<$V>>.};
+my $result = q{The value of $V is 119.};
+my $template1 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $template,
+ DELIMITERS => [ '<<', '>>' ])
+ or die "Couldn't construct template object: $Text::Template::ERROR; aborting";
+
+my $text = $template1->fill_in();
+is $text, $result;
+
+# (2) Now with delimiter choice deferred until fill-in time.
+$template1 = Text::Template->new(TYPE => 'STRING', SOURCE => $template);
+$text = $template1->fill_in(DELIMITERS => [ '<<', '>>' ]);
+is $text, $result;
+
+# (3) Now we'll try using regex metacharacters
+# First with the delimiters specified at object creation time
+$template = q{The value of $V is [$V].};
+$template1 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $template,
+ DELIMITERS => [ '[', ']' ])
+ or die "Couldn't construct template object: $Text::Template::ERROR; aborting";
+
+$text = $template1->fill_in();
+is $text, $result;
+
+# (4) Now with delimiter choice deferred until fill-in time.
+$template1 = Text::Template->new(TYPE => 'STRING', SOURCE => $template);
+$text = $template1->fill_in(DELIMITERS => [ '[', ']' ]);
+is $text, $result;
+
+# (5-18) Make sure \ is working properly
+# (That is to say, it is ignored.)
+# These tests are similar to those in 01-basic.t.
+my @tests = (
+ '{""}' => '', # (5)
+
+ # Backslashes don't matter
+ '{"}"}' => undef,
+ '{"\\}"}' => undef, # One backslash
+ '{"\\\\}"}' => undef, # Two backslashes
+ '{"\\\\\\}"}' => undef, # Three backslashes
+ '{"\\\\\\\\}"}' => undef, # Four backslashes (10)
+ '{"\\\\\\\\\\}"}' => undef, # Five backslashes
+
+ # Backslashes are always passed directly to Perl
+ '{"x20"}' => 'x20',
+ '{"\\x20"}' => ' ', # One backslash
+ '{"\\\\x20"}' => '\\x20', # Two backslashes
+ '{"\\\\\\x20"}' => '\\ ', # Three backslashes (15)
+ '{"\\\\\\\\x20"}' => '\\\\x20', # Four backslashes
+ '{"\\\\\\\\\\x20"}' => '\\\\ ', # Five backslashes
+ '{"\\x20\\}"}' => undef, # (18)
+);
+
+while (my ($test, $result) = splice @tests, 0, 2) {
+ my $tmpl = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $test,
+ DELIMITERS => [ '{', '}' ]);
+
+ my $text = $tmpl->fill_in;
+
+ my $ok = (!defined $text && !defined $result || $text eq $result);
+
+ ok($ok) or diag "expected .$result., got .$text.";
+}
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+use Test::More tests => 6;
+
+use_ok 'Text::Template' or exit 1;
+
+# (1-2) Missing source
+eval {
+ Text::Template->new();
+ pass;
+};
+
+like $@, qr/^\QUsage: Text::Template::new(TYPE => ..., SOURCE => ...)/;
+
+eval { Text::Template->new(TYPE => 'FILE'); };
+like $@, qr/^\QUsage: Text::Template::new(TYPE => ..., SOURCE => ...)/;
+
+# (3) Invalid type
+eval { Text::Template->new(TYPE => 'wlunch', SOURCE => 'fish food'); };
+like $@, qr/^\QIllegal value `WLUNCH' for TYPE parameter/;
+
+# (4-5) File does not exist
+my $o = Text::Template->new(
+ TYPE => 'file',
+ SOURCE => 'this file does not exist');
+ok !defined $o;
+
+ok defined($Text::Template::ERROR)
+ && $Text::Template::ERROR =~ /^Couldn't open file/;
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+use Test::More tests => 7;
+use File::Temp;
+
+use_ok 'Text::Template' or exit 1;
+
+my $tfh = File::Temp->new;
+
+Text::Template->import('fill_in_file', 'fill_in_string');
+
+$Q::n = $Q::n = 119;
+
+# (1) Test fill_in_string
+my $out = fill_in_string('The value of $n is {$n}.', PACKAGE => 'Q');
+is $out, 'The value of $n is 119.';
+
+# (2) Test fill_in_file
+my $TEMPFILE = $tfh->filename;
+
+print $tfh 'The value of $n is {$n}.', "\n";
+close $tfh or die "Couldn't write test file: $!; aborting";
+
+$R::n = $R::n = 8128;
+
+$out = fill_in_file($TEMPFILE, PACKAGE => 'R');
+is $out, "The value of \$n is 8128.\n";
+
+# (3) Jonathan Roy reported this bug:
+open my $ofh, '>', $TEMPFILE or die "Couldn't open test file: $!; aborting";
+print $ofh "With a message here? [% \$var %]\n";
+close $ofh or die "Couldn't close test file: $!; aborting";
+$out = fill_in_file($TEMPFILE,
+ DELIMITERS => [ '[%', '%]' ],
+ HASH => { "var" => \"It is good!" });
+is $out, "With a message here? It is good!\n";
+
+# (4) It probably occurs in fill_this_in also:
+$out = Text::Template->fill_this_in("With a message here? [% \$var %]\n",
+ DELIMITERS => [ '[%', '%]' ],
+ HASH => { "var" => \"It is good!" });
+is $out, "With a message here? It is good!\n";
+
+# (5) This test failed in 1.25. It was supplied by Donald L. Greer Jr.
+# Note that it's different from (1) in that there's no explicit
+# package=> argument.
+use vars qw($string $foo $r);
+$string = 'Hello {$foo}';
+$foo = "Don";
+$r = fill_in_string($string);
+is $r, 'Hello Don';
+
+# (6) This test failed in 1.25. It's a variation on (5)
+package Q2;
+use Text::Template 'fill_in_string';
+use vars qw($string $foo $r);
+$string = 'Hello {$foo}';
+$foo = "Don";
+$r = fill_in_string($string);
+
+package main;
+
+is $Q2::r, 'Hello Don';
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+use Test::More tests => 13;
+
+use_ok 'Text::Template' or exit 1;
+
+my $template = 'We will put value of $v (which is "good") here -> {$v}';
+
+my $v = 'oops (main)';
+$Q::v = 'oops (Q)';
+
+my $vars = { 'v' => \'good' };
+
+# (1) Build template from string
+$template = Text::Template->new('type' => 'STRING', 'source' => $template);
+isa_ok $template, 'Text::Template';
+
+# (2) Fill in template in anonymous package
+my $result2 = 'We will put value of $v (which is "good") here -> good';
+my $text = $template->fill_in(HASH => $vars);
+is $text, $result2;
+
+# (3) Did we clobber the main variable?
+is $v, 'oops (main)';
+
+# (4) Fill in same template again
+my $result4 = 'We will put value of $v (which is "good") here -> good';
+$text = $template->fill_in(HASH => $vars);
+is $text, $result4;
+
+# (5) Now with a package
+my $result5 = 'We will put value of $v (which is "good") here -> good';
+$text = $template->fill_in(HASH => $vars, PACKAGE => 'Q');
+is $text, $result5;
+
+# (6) We expect to have clobbered the Q variable.
+is $Q::v, 'good';
+
+# (7) Now let's try it without a package
+my $result7 = 'We will put value of $v (which is "good") here -> good';
+$text = $template->fill_in(HASH => $vars);
+is $text, $result7;
+
+# (8-11) Now what does it do when we pass a hash with undefined values?
+# Roy says it does something bad. (Added for 1.20.)
+my $WARNINGS = 0;
+{
+ local $SIG{__WARN__} = sub { $WARNINGS++ };
+ local $^W = 1; # Make sure this is on for this test
+ my $template8 = 'We will put value of $v (which is "good") here -> {defined $v ? "bad" : "good"}';
+ my $result8 = 'We will put value of $v (which is "good") here -> good';
+ my $template = Text::Template->new('type' => 'STRING', 'source' => $template8);
+ my $text = $template->fill_in(HASH => { 'v' => undef });
+
+ # (8) Did we generate a warning?
+ cmp_ok $WARNINGS, '==', 0;
+
+ # (9) Was the output correct?
+ is $text, $result8;
+
+ # (10-11) Let's try that again, with a twist this time
+ $WARNINGS = 0;
+ $text = $template->fill_in(HASH => [ { 'v' => 17 }, { 'v' => undef } ]);
+
+ # (10) Did we generate a warning?
+ cmp_ok $WARNINGS, '==', 0;
+
+ # (11) Was the output correct?
+ SKIP: {
+ skip 'not supported before 5.005', 1 unless $] >= 5.005;
+
+ is $text, $result8;
+ }
+}
+
+# (12) Now we'll test the multiple-hash option (Added for 1.20.)
+$text = Text::Template::fill_in_string(q{$v: {$v}. @v: [{"@v"}].},
+ HASH => [
+ { 'v' => 17 },
+ { 'v' => [ 'a', 'b', 'c' ] },
+ { 'v' => \23 }
+ ]
+);
+
+my $result = q{$v: 23. @v: [a b c].};
+is $text, $result;
--- /dev/null
+#!perl
+#
+# Test for comments within an inline code block
+
+use strict;
+use warnings;
+use Test::More tests => 2;
+
+use_ok 'Text::Template' or exit 1;
+
+my $tmpl = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => "Hello {\$name#comment}");
+
+my $vars = { name => 'Bob' };
+
+is $tmpl->fill_in(HASH => $vars), 'Hello Bob';
--- /dev/null
+#!perl
+#
+# Test for breakage of Dist::Milla in v1.46
+#
+
+use strict;
+use warnings;
+use Text::Template;
+
+BEGIN {
+ # Minimum Test::More version; 0.94+ is required for `done_testing`
+ unless (eval { require Test::More; "$Test::More::VERSION" >= 0.94; }) {
+ Test::More::plan(skip_all => '[ Test::More v0.94+ ] is required for testing');
+ }
+
+ Test::More->import;
+}
+
+my $tmpl = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => q| {{ '{{$NEXT}}' }} |,
+ DELIMITERS => [ '{{', '}}' ]);
+
+is $tmpl->fill_in, ' {{$NEXT}} ';
+
+done_testing;
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+use Test::More tests => 3;
+use File::Temp;
+
+use_ok 'Text::Template' or exit 1;
+
+my $template = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => q{My process ID is {$$}});
+
+my $of = File::Temp->new;
+
+my $text = $template->fill_in(OUTPUT => $of);
+
+# (1) No $text should have been constructed. Return value should be true.
+is $text, '1';
+
+close $of or die "close(): $!";
+
+open my $ifh, '<', $of->filename or die "open($of): $!";
+
+my $t;
+{ local $/; $t = <$ifh> }
+close $ifh;
+
+# (2) The text should have been printed to the file
+is $t, "My process ID is $$";
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+#
+
+use strict;
+use warnings;
+use Test::More tests => 4;
+
+use_ok 'Text::Template' or exit 1;
+
+my $templateIN = q{
+This line should have a 3: {1+2}
+
+This line should have several numbers:
+{ $t = ''; foreach $n (1 .. 20) { $t .= $n . ' ' } $t }
+};
+
+my $templateOUT = q{
+This line should have a 3: { $OUT = 1+2 }
+
+This line should have several numbers:
+{ foreach $n (1 .. 20) { $OUT .= $n . ' ' } }
+};
+
+# Build templates from string
+my $template = Text::Template->new('type' => 'STRING', 'source' => $templateIN);
+isa_ok $template, 'Text::Template';
+
+$templateOUT = Text::Template->new('type' => 'STRING', 'source' => $templateOUT);
+isa_ok $templateOUT, 'Text::Template';
+
+# Fill in templates
+my $text = $template->fill_in();
+my $textOUT = $templateOUT->fill_in();
+
+# (1) They should be the same
+is $text, $textOUT;
+
+# Missing: Test this feature in Safe compartments;
+# it's a totally different code path.
+# Decision: Put that into safe.t, because that file should
+# be skipped when Safe.pm is unavailable.
+
+exit;
--- /dev/null
+#!perl
+#
+# Tests for PREPEND features
+# These tests first appeared in version 1.22.
+
+use strict;
+use warnings;
+use Test::More tests => 10;
+
+use_ok 'Text::Template' or exit 1;
+
+@Emptyclass1::ISA = 'Text::Template';
+@Emptyclass2::ISA = 'Text::Template';
+
+my $tin = q{The value of $foo is: {$foo}};
+
+Text::Template->always_prepend(q{$foo = "global"});
+
+my $tmpl1 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $tin);
+
+my $tmpl2 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $tin,
+ PREPEND => q{$foo = "template"});
+
+$tmpl1->compile;
+$tmpl2->compile;
+
+my $t1 = $tmpl1->fill_in(PACKAGE => 'T1');
+my $t2 = $tmpl2->fill_in(PACKAGE => 'T2');
+my $t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T3');
+
+is $t1, 'The value of $foo is: global';
+is $t2, 'The value of $foo is: template';
+is $t3, 'The value of $foo is: fillin';
+
+Emptyclass1->always_prepend(q{$foo = 'Emptyclass global';});
+$tmpl1 = Emptyclass1->new(
+ TYPE => 'STRING',
+ SOURCE => $tin);
+
+$tmpl2 = Emptyclass1->new(
+ TYPE => 'STRING',
+ SOURCE => $tin,
+ PREPEND => q{$foo = "template"});
+
+$tmpl1->compile;
+$tmpl2->compile;
+
+$t1 = $tmpl1->fill_in(PACKAGE => 'T4');
+$t2 = $tmpl2->fill_in(PACKAGE => 'T5');
+$t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T6');
+
+is $t1, 'The value of $foo is: Emptyclass global';
+is $t2, 'The value of $foo is: template';
+is $t3, 'The value of $foo is: fillin';
+
+$tmpl1 = Emptyclass2->new(
+ TYPE => 'STRING',
+ SOURCE => $tin);
+
+$tmpl2 = Emptyclass2->new(
+ TYPE => 'STRING',
+ SOURCE => $tin,
+ PREPEND => q{$foo = "template"});
+
+$tmpl1->compile;
+$tmpl2->compile;
+
+$t1 = $tmpl1->fill_in(PACKAGE => 'T4');
+$t2 = $tmpl2->fill_in(PACKAGE => 'T5');
+$t3 = $tmpl2->fill_in(PREPEND => q{$foo = "fillin"}, PACKAGE => 'T6');
+
+is $t1, 'The value of $foo is: global';
+is $t2, 'The value of $foo is: template';
+is $t3, 'The value of $foo is: fillin';
--- /dev/null
+#!perl
+#
+# Tests for PREPROCESSOR features
+# These tests first appeared in version 1.25.
+
+use strict;
+use warnings;
+use Test::More tests => 9;
+use File::Temp;
+
+use_ok 'Text::Template::Preprocess' or exit 1;
+
+my $tmpfile = File::Temp->new;
+my $TMPFILE = $tmpfile->filename;
+
+my $py = sub { tr/x/y/ };
+my $pz = sub { tr/x/z/ };
+
+my $t = 'xxx The value of $x is {$x}';
+my $outx = 'xxx The value of $x is 119';
+my $outy = 'yyy The value of $y is 23';
+my $outz = 'zzz The value of $z is 5';
+open my $tfh, '>', $TMPFILE or die "Couldn't open test file: $!; aborting";
+print $tfh $t;
+close $tfh;
+
+my @result = ($outx, $outy, $outz, $outz);
+for my $trial (1, 0) {
+ for my $test (0 .. 3) {
+ my $tmpl;
+ if ($trial == 0) {
+ $tmpl = Text::Template::Preprocess->new(TYPE => 'STRING', SOURCE => $t) or die;
+ }
+ else {
+ open $tfh, '<', $TMPFILE or die "Couldn't open test file: $!; aborting";
+ $tmpl = Text::Template::Preprocess->new(TYPE => 'FILEHANDLE', SOURCE => $tfh) or die;
+ }
+ $tmpl->preprocessor($py) if ($test & 1) == 1;
+ my @args = ((($test & 2) == 2) ? (PREPROCESSOR => $pz) : ());
+ my $o = $tmpl->fill_in(@args, HASH => { x => 119, 'y' => 23, z => 5 });
+ is $o, $result[$test];
+ }
+}
--- /dev/null
+#!perl
+#
+# Test for RT Bug 29928 fix
+# https://rt.cpan.org/Public/Bug/Display.html?id=29928
+
+use strict;
+use warnings;
+use Test::More tests => 2;
+
+use_ok 'Text::Template::Preprocess' or exit 1;
+
+my $tin = q{The value of $foo is: {$foo}.};
+
+sub tester {
+ 1; # dummy preprocessor to cause the bug described.
+}
+
+my $tmpl1 = Text::Template::Preprocess->new(TYPE => 'STRING', SOURCE => $tin);
+
+$tmpl1->compile;
+
+my $t1 = $tmpl1->fill_in(
+ HASH => { foo => 'things' },
+ PREPROCESSOR => \&tester);
+
+is $t1, 'The value of $foo is: things.';
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+
+use Test::More;
+
+unless (eval { require Safe; 1 }) {
+ plan skip_all => 'Safe.pm is required for this test';
+}
+else {
+ plan tests => 20;
+}
+
+use_ok 'Text::Template' or exit 1;
+
+my ($BADOP, $FAILURE);
+if ($^O eq 'MacOS') {
+ $BADOP = qq{};
+ $FAILURE = q{};
+}
+else {
+ $BADOP = qq{kill 0};
+ $FAILURE = q{Program fragment at line 1 delivered error ``kill trapped by operation mask''};
+}
+
+our $v = 119;
+
+my $c = Safe->new or die;
+
+my $goodtemplate = q{This should succeed: { $v }};
+my $goodoutput = q{This should succeed: 119};
+
+my $template1 = Text::Template->new(type => 'STRING', source => $goodtemplate);
+my $template2 = Text::Template->new(type => 'STRING', source => $goodtemplate);
+
+my $text1 = $template1->fill_in();
+ok defined $text1;
+
+my $text2 = $template1->fill_in(SAFE => $c);
+ok defined $text2;
+
+my $text3 = $template2->fill_in(SAFE => $c);
+ok defined $text3;
+
+# (4) Safe and non-safe fills of different template objects with the
+# same template text should yield the same result.
+# print +($text1 eq $text3 ? '' : 'not '), "ok $n\n";
+# (4) voided this test: it's not true, because the unsafe fill
+# uses package main, while the safe fill uses the secret safe package.
+# We could alias the secret safe package to be identical to main,
+# but that wouldn't be safe. If you want the aliasing, you have to
+# request it explicitly with `PACKAGE'.
+
+# (5) Safe and non-safe fills of the same template object
+# should yield the same result.
+# (5) voided this test for the same reason as #4.
+# print +($text1 eq $text2 ? '' : 'not '), "ok $n\n";
+
+# (6) Make sure the output was actually correct
+is $text1, $goodoutput;
+
+my $badtemplate = qq{This should fail: { $BADOP; 'NOFAIL' }};
+my $badnosafeoutput = q{This should fail: NOFAIL};
+my $badsafeoutput =
+ q{This should fail: Program fragment delivered error ``kill trapped by operation mask at template line 1.''};
+
+$template1 = Text::Template->new('type' => 'STRING', 'source' => $badtemplate);
+isa_ok $template1, 'Text::Template';
+
+$template2 = Text::Template->new('type' => 'STRING', 'source' => $badtemplate);
+isa_ok $template2, 'Text::Template';
+
+# none of these should fail
+$text1 = $template1->fill_in();
+ok defined $text1;
+
+$text2 = $template1->fill_in(SAFE => $c);
+ok defined $text2;
+
+$text3 = $template2->fill_in(SAFE => $c);
+ok defined $text3;
+
+my $text4 = $template1->fill_in();
+ok defined $text4;
+
+# (11) text1 and text4 should be the same (using safe in between
+# didn't change anything.)
+is $text1, $text4;
+
+# (12) text2 and text3 should be the same (same template text in different
+# objects
+is $text2, $text3;
+
+# (13) text1 should yield badnosafeoutput
+is $text1, $badnosafeoutput;
+
+# (14) text2 should yield badsafeoutput
+$text2 =~ s/'kill'/kill/; # 5.8.1 added quote marks around the op name
+is $text2, $badsafeoutput;
+
+my $template = q{{$x=1}{$x+1}};
+
+$template1 = Text::Template->new('type' => 'STRING', 'source' => $template);
+isa_ok $template1, 'Text::Template';
+
+$template2 = Text::Template->new('type' => 'STRING', 'source' => $template);
+isa_ok $template2, 'Text::Template';
+
+$text1 = $template1->fill_in();
+$text2 = $template1->fill_in(SAFE => Safe->new);
+
+# (15) Do effects persist in safe compartments?
+is $text1, $text2;
+
+# (16) Try the BROKEN routine in safe compartments
+sub my_broken {
+ my %a = @_;
+ $a{error} =~ s/ at.*//s;
+ "OK! text:$a{text} error:$a{error} lineno:$a{lineno} arg:$a{arg}";
+}
+
+my $templateB = Text::Template->new(TYPE => 'STRING', SOURCE => '{die}');
+isa_ok $templateB, 'Text::Template';
+
+$text1 = $templateB->fill_in(
+ BROKEN => \&my_broken,
+ BROKEN_ARG => 'barg',
+ SAFE => Safe->new);
+
+my $result1 = qq{OK! text:die error:Died lineno:1 arg:barg};
+is $text1, $result1;
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+# still incomplete.
+
+use strict;
+use warnings;
+use Test::More;
+
+unless (eval { require Safe; 1 }) {
+ plan skip_all => 'Safe.pm is required for this test';
+}
+else {
+ plan tests => 12;
+}
+
+use_ok 'Text::Template' or exit 1;
+
+my $c = Safe->new or die;
+
+# Test handling of packages and importing.
+$c->reval('$P = "safe root"');
+our $P = 'main';
+$Q::P = $Q::P = 'Q';
+
+# How to effectively test the gensymming?
+
+my $t = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => 'package is {$P}') or die;
+
+# (1) Default behavior: Inherit from calling package, `main' in this case.
+my $text = $t->fill_in();
+is $text, 'package is main';
+
+# (2) When a package is specified, we should use that package instead.
+$text = $t->fill_in(PACKAGE => 'Q');
+is $text, 'package is Q';
+
+# (3) When no package is specified in safe mode, we should use the
+# default safe root.
+$text = $t->fill_in(SAFE => $c);
+is $text, 'package is safe root';
+
+# (4) When a package is specified in safe mode, we should use the
+# default safe root, after aliasing to the specified package
+TODO: {
+ local $TODO = "test fails when tested with TAP/Devel::Cover" if defined $Devel::Cover::VERSION;
+ $text = $t->fill_in(SAFE => $c, PACKAGE => 'Q');
+ is $text, 'package is Q';
+}
+
+# Now let's see if hash vars are installed properly into safe templates
+$t = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => 'hash is {$H}') or die;
+
+# (5) First in default mode
+$text = $t->fill_in(HASH => { H => 'good5' });
+is $text, 'hash is good5';
+
+# suppress "once" warnings
+$Q::H = $Q2::H = undef;
+
+# (6) Now in packages
+$text = $t->fill_in(HASH => { H => 'good6' }, PACKAGE => 'Q');
+is $text, 'hash is good6';
+
+# (7) Now in the default root of the safe compartment
+TODO: {
+ local $TODO = "test fails when tested with TAP/Devel::Cover" if defined $Devel::Cover::VERSION;
+ $text = $t->fill_in(HASH => { H => 'good7' }, SAFE => $c);
+ is $text, 'hash is good7';
+}
+
+# (8) Now in the default root after aliasing to a package that
+# got the hash stuffed in
+our $H;
+TODO: {
+ local $TODO = "test fails when tested with TAP/Devel::Cover" if defined $Devel::Cover::VERSION;
+ $text = $t->fill_in(HASH => { H => 'good8' }, SAFE => $c, PACKAGE => 'Q2');
+ is $text, 'hash is good8';
+}
+
+# Now let's make sure that none of the packages leaked on each other.
+# (9) This var should NOT have been installed into the main package
+ok !defined $H;
+$H = $H;
+
+# (11) this value overwrote the one from test 6.
+is $Q::H, 'good7';
+
+# (12)
+is $Q2::H, 'good8';
--- /dev/null
+#!perl
+#
+# test apparatus for Text::Template module
+
+use strict;
+use warnings;
+use Test::More;
+
+unless (eval { require Safe; 1 }) {
+ plan skip_all => 'Safe.pm is required for this test';
+}
+else {
+ plan tests => 4;
+}
+
+use_ok 'Text::Template' or exit 1;
+
+# Test the OUT feature with safe compartments
+
+my $template = q{
+This line should have a 3: {1+2}
+
+This line should have several numbers:
+{ $t = ''; foreach $n (1 .. 20) { $t .= $n . ' ' } $t }
+};
+
+my $templateOUT = q{
+This line should have a 3: { $OUT = 1+2 }
+
+This line should have several numbers:
+{ foreach $n (1 .. 20) { $OUT .= $n . ' ' } }
+};
+
+my $c = Safe->new;
+
+# Build templates from string
+$template = Text::Template->new(
+ type => 'STRING',
+ source => $template,
+ SAFE => $c) or die;
+
+$templateOUT = Text::Template->new(
+ type => 'STRING',
+ source => $templateOUT,
+ SAFE => $c) or die;
+
+# Fill in templates
+my $text = $template->fill_in()
+ or die;
+my $textOUT = $templateOUT->fill_in()
+ or die;
+
+# (1) They should be the same
+is $text, $textOUT;
+
+# (2-3) "Joel Appelbaum" <joel@orbz.com> <000701c0ac2c$aed1d6e0$0201a8c0@prime>
+# "Contrary to the documentation the $OUT variable is not always
+# undefined at the start of each program fragment. The $OUT variable
+# is never undefined after it is used once if you are using the SAFE
+# option. The result is that every fragment after the fragment that
+# $OUT was used in is replaced by the old $OUT value instead of the
+# result of the fragment. This holds true even after the
+# Text::Template object goes out of scope and a new one is created!"
+#
+# Also reported by Daini Xie.
+
+{
+ my $template = q{{$OUT = 'x'}y{$OUT .= 'z'}};
+ my $expected = "xyz";
+ my $s = Safe->new;
+ my $o = Text::Template->new(
+ type => 'string',
+ source => $template);
+
+ for (1 .. 2) {
+ my $r = $o->fill_in(SAFE => $s);
+
+ is $r, $expected;
+ }
+}
--- /dev/null
+#!perl
+#
+# Tests for STRICT features
+# These tests first appeared in version 1.48.
+
+use strict;
+use warnings;
+use Test::More tests => 4;
+
+use_ok 'Text::Template' or exit 1;
+
+@Emptyclass1::ISA = 'Text::Template';
+@Emptyclass2::ISA = 'Text::Template';
+
+my $tin = q{The value of $foo is: {$foo}};
+
+Text::Template->always_prepend(q{$foo = "global"});
+
+my $tmpl1 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $tin);
+
+my $tmpl2 = Text::Template->new(
+ TYPE => 'STRING',
+ SOURCE => $tin,
+ PREPEND => q{$foo = "template"});
+
+$tmpl1->compile;
+$tmpl2->compile;
+
+# strict should cause t1 to contain an error message if wrong variable is used in template
+my $t1 = $tmpl1->fill_in(PACKAGE => 'T1', STRICT => 1, HASH => { bar => 'baz' });
+
+# non-strict still works
+my $t2 = $tmpl2->fill_in(PACKAGE => 'T2', HASH => { bar => 'baz' });
+
+# prepend overrides the hash values
+my $t3 = $tmpl2->fill_in(
+ PREPEND => q{$foo = "fillin"},
+ PACKAGE => 'T3',
+ STRICT => 1,
+ HASH => { foo => 'hashval2' });
+
+like $t1, qr/Global symbol "\$foo" requires explicit package/;
+is $t2, 'The value of $foo is: template', "non-strict hash still works";
+is $t3, "The value of \$foo is: fillin", "hash values with prepend, prepend wins, even under strict.";
--- /dev/null
+#!perl -T
+# Tests for taint-mode features
+
+use strict;
+use warnings;
+use lib 'blib/lib';
+use Test::More tests => 21;
+use File::Temp;
+
+use_ok 'Text::Template' or exit 1;
+
+if ($^O eq 'MSWin32') {
+ # File::Temp (for all versions up to at least 0.2308) is currently bugged under MSWin32/taint mode [as of 2018-09]
+ # ... fails unless "/tmp" on the current windows drive is a writable directory OR either $ENV{TMP} or $ENV{TEMP} are untainted and point to a writable directory
+ # ref: [File-Temp: Fails under -T, Windows 7, Strawberry Perl 5.12.1](https://rt.cpan.org/Public/Bug/Display.html?id=60340)
+ ($ENV{TEMP}) = $ENV{TEMP} =~ m/^.*$/gmsx; # untaint $ENV{TEMP}
+ ($ENV{TMP}) = $ENV{TMP} =~ m/^.*$/gmsx; # untaint $ENV{TMP}
+}
+
+my $tmpfile = File::Temp->new;
+my $file = $tmpfile->filename;
+
+# makes its arguments tainted
+sub taint {
+ for (@_) {
+ $_ .= substr($0, 0, 0); # LOD
+ }
+}
+
+my $template = 'The value of $n is {$n}.';
+
+open my $fh, '>', $file or die "Couldn't write temporary file $file: $!";
+print $fh $template, "\n";
+close $fh or die "Couldn't finish temporary file $file: $!";
+
+sub should_fail {
+ my $obj = Text::Template->new(@_);
+ eval { $obj->fill_in() };
+ if ($@) {
+ pass $@;
+ }
+ else {
+ fail q[didn't fail];
+ }
+}
+
+sub should_work {
+ my $obj = Text::Template->new(@_);
+ eval { $obj->fill_in() };
+ if ($@) {
+ fail $@;
+ }
+ else {
+ pass;
+ }
+}
+
+sub should_be_tainted {
+ ok !Text::Template::_is_clean($_[0]);
+}
+
+sub should_be_clean {
+ ok Text::Template::_is_clean($_[0]);
+}
+
+# Tainted filename should die with and without UNTAINT option
+# untainted filename should die without UNTAINT option
+# filehandle should die without UNTAINT option
+# string and array with tainted data should die either way
+
+# (2)-(7)
+my $tfile = $file;
+taint($tfile);
+should_be_tainted($tfile);
+should_be_clean($file);
+should_fail TYPE => 'file', SOURCE => $tfile;
+should_fail TYPE => 'file', SOURCE => $tfile, UNTAINT => 1;
+should_fail TYPE => 'file', SOURCE => $file;
+should_work TYPE => 'file', SOURCE => $file, UNTAINT => 1;
+
+# (8-9)
+open $fh, '<', $file or die "Couldn't open $file for reading: $!; aborting";
+should_fail TYPE => 'filehandle', SOURCE => $fh;
+close $fh;
+
+open $fh, '<', $file or die "Couldn't open $file for reading: $!; aborting";
+should_work TYPE => 'filehandle', SOURCE => $fh, UNTAINT => 1;
+close $fh;
+
+# (10-15)
+my $ttemplate = $template;
+taint($ttemplate);
+should_be_tainted($ttemplate);
+should_be_clean($template);
+should_fail TYPE => 'string', SOURCE => $ttemplate;
+should_fail TYPE => 'string', SOURCE => $ttemplate, UNTAINT => 1;
+should_work TYPE => 'string', SOURCE => $template;
+should_work TYPE => 'string', SOURCE => $template, UNTAINT => 1;
+
+# (16-19)
+my $array = [$template];
+my $tarray = [$ttemplate];
+should_fail TYPE => 'array', SOURCE => $tarray;
+should_fail TYPE => 'array', SOURCE => $tarray, UNTAINT => 1;
+should_work TYPE => 'array', SOURCE => $array;
+should_work TYPE => 'array', SOURCE => $array, UNTAINT => 1;
+
+# (20-21) Test _unconditionally_untaint utility function
+Text::Template::_unconditionally_untaint($ttemplate);
+should_be_clean($ttemplate);
+Text::Template::_unconditionally_untaint($tfile);
+should_be_clean($tfile);
--- /dev/null
+#!perl
+
+use utf8;
+use strict;
+use warnings;
+use Test::More;
+use Encode;
+use File::Temp;
+
+# Non-CORE module(s)
+unless (eval { require Test::More::UTF8; 1; } ) {
+ plan skip_all => '[ Test::More::UTF8 ] is required for testing';
+}
+
+plan tests => 3;
+
+use_ok 'Text::Template' or exit 1;
+
+my $tmp_fh = File::Temp->new;
+
+print $tmp_fh encode('UTF-8', "\x{4f60}\x{597d} {{\$name}}");
+
+$tmp_fh->flush;
+
+# UTF-8 encoded template file
+my $str = Text::Template->new(
+ TYPE => 'FILE',
+ SOURCE => $tmp_fh->filename,
+ ENCODING => 'UTF-8'
+)->fill_in(HASH => { name => 'World' });
+
+is $str, "\x{4f60}\x{597d} World";
+
+$tmp_fh = File::Temp->new;
+
+print $tmp_fh encode('iso-8859-1', "Ol\x{e1} {{\$name}}");
+
+$tmp_fh->flush;
+
+# ISO-8859-1 encoded template file
+$str = Text::Template->new(
+ TYPE => 'FILE',
+ SOURCE => $tmp_fh->filename,
+ ENCODING => 'iso-8859-1'
+)->fill_in(HASH => { name => 'World' });
+
+is $str, "Ol\x{e1} World";
--- /dev/null
+#!perl
+
+use strict;
+use warnings;
+use Text::Template;
+
+# Minimum Test::More version; 0.94+ is required for `done_testing`
+BEGIN {
+ unless (eval { require Test::More; "$Test::More::VERSION" >= 0.94; }) {
+ Test::More::plan(skip_all => '[ Test::More v0.94+ ] is required for testing');
+ }
+
+ Test::More->import;
+
+ # Non-CORE module(s)
+ unless (eval { require Test::Warnings; 1; }) {
+ plan(skip_all => '[ Test::Warnings ] is required for testing');
+ }
+
+ Test::Warnings->import;
+}
+
+my $template = <<'EOT';
+{{
+if ($good =~ /good/) {
+ 'This template should not produce warnings.'.$bad;
+}
+}}
+EOT
+
+$template = Text::Template->new(type => 'STRING', source => $template);
+isa_ok $template, 'Text::Template';
+
+my $result = $template->fill_in(HASH => { good => 'good' });
+
+$result =~ s/(?:^\s+)|(?:\s+$)//gs;
+is $result, 'This template should not produce warnings.';
+
+# see https://github.com/mschout/perl-text-template/issues/10
+$template = Text::Template->new(type => 'STRING', package => 'MY', source => '');
+$template->fill_in(package => 'MY', hash => { include => sub { 'XX' } });
+
+$template = Text::Template->new(type => 'STRING', package => 'MY', source => '');
+$template->fill_in(package => 'MY', hash => { include => sub { 'XX' } });
+
+done_testing;
projects / oweals / openssl.git / commitdiff