The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-PerlPP-0.4.0
River stage zero No dependents
++
/ perlpp

NAME

perlpp - Perl preprocessor: process Perl code within any text file

USAGE

        perlpp [options] [--] [filename]

If no [filename] is given, input will be read from stdin.

Run perlpp --help for a quick reference, or perlpp --man for full docs.

OPTIONS

-o, --output filename

Output to filename instead of STDOUT.

-D, --define name[=value]

In the generated script, set $D{name} to value. The hash %D always exists, but is empty if no -D options are given on the command line.

The name will also be replaced with the value in the text of the file. If value cannot be evaluated, no substitution is made for name.

If you omit the =value, the value will be the constant true (see "The generated script", below), and no text substitution will be performed.

This also saves the value, or undef, in the generation-time hash %Text::PerlPP::Defs. This can be used, e.g., to select include filenames depending on -D arguments.

See "Definitions", below, for more information.

-e, --eval statement

Evaluate the statement before any other Perl code in the generated script.

-E, --debug (or -d for backwards compatibility)

Don't evaluate Perl code, just write the generated code to STDOUT. By analogy with the -E option of gcc.

--Elines

In case of an error in the input, perlpp normally tries to report a file and line number close to the location of the error in the source file. However, the match isn't always perfect. If --Elines is given, errors will be reported at the line number in the generated script. The generated script will still include ## sync markers showing you about where the input files/lines are, for ease of reference.

-k, --keep-going

Normally, errors in a !command sequence will terminate further processing. If -k is given, an error message will be printed to stderr, but the script will keep running.

-s, --set name[=value]

As -D, but:

  • Does not substitute text in the body of the document;

  • Saves into %Text::PerlPP::Sets at generation time; and

  • Saves into %S in the generated script.

--man

Full documentation, viewed in your default pager if configured.

-h, --help

Usage help, printed to STDOUT.

-?, --usage

Shows just the usage summary

--version

Show the version number of perlpp

DEFINITIONS

-D and -s items may be evaluated in any order --- do not rely on left-to-right evaluation in the order given on the command line.

If your shell strips quotes, you may need to escape them: value must be a valid Perl expression. So, under bash, this works:

        perlpp -D name=\"Hello, world!\"

The backslashes (\" instead of ") are required to prevent bash from removing the double-quotes. Alternatively, this works:

        perlpp -D 'name="Hello, World"'

with the whole argument to -D in single quotes.

Also note that the space after -D is optional, so

        perlpp -Dfoo
        perlpp -Dbar=42

both work.

INPUT FORMAT

All text from the input is passed literally to the output unless enclosed in the delimiters <? and ?>. This is similar to PHP's rule. The first character after the opening delimiter selects one of the modes, and defines the content between the delimiters.

PerlPP first generates a script based on the input ("generation time"), then evaluates that script ("eval time") to produce the output. All Perl code is run when the script is evaluated, except for commands notes as occuring at generation time.

For double-quotes adjacent to the delimiters, add whitespace between the quote and the delimiter. For example, use <? " and " ?> instead of <?" and "?>. The exception is if you want to invoke capturing, described below.

Modes

Code mode: <? arbitrary Perl code ?>

The content is whatever Perl code you want. It will be executed at evaluation time. It is up to you to make sure things are properly nested.

Echo mode: <?= Perl expression ?>

<?= expr ?> is shorthand for <? print expr ; ?>.

Code mode with newline: <?/ arbitrary Perl code ?>

The same as <? ?>, but sticks a print "\n"; in front of the code you provide.

Comment mode: <?# arbitrary text not including '?>' ?>

Everything in a comment is ignored, suprisingly enough!

External mode: <?! command [args...] ?>

Runs the given string using qx//. If the command fails (returns nonzero), execution halts unless -k was given. The stdout of the command is include with the rest of the output of the script.

Command mode: <?:command_name [optional args] ?>

Runs a PerlPP command.

PerlPP Commands

<?:include filename ?>

Include the contents of the file called filename at generation time. The included file is processed as if its contents occurred inline in the calling file.

If the filename includes spaces, use double-quotes:

        <?:include "some long filename" ?>

Make sure to include the space after the closing double-quote.

<?:prefix foo bar ?>

After the prefix command, if a word starts with foo, change the foo to bar.

<?:macro some_perl_code ?>

Run some_perl_code at the time of script generation. Whatever output the perl code produces will be included verbatim in the script output. See "README.md" for examples.

C preprocessor emulation

The following work similarly to the corresponding functions of the C preprocessor: <?:define NAME ?>, <?:undef NAME ?>, <?:ifdef NAME ?>, <?:ifndef NAME ?>, <?:else ?>, <?:endif ?>, <?:if NAME CONDITION ?>, and <?:elsif NAME CONDITION ?> (or elif or elseif).

Capturing

Capturing permits you to express single-quoted strings without having to quote and escape. For example, <? print "?>some $text "string"<?" ; ?> outputs some $text "string" literally, without substituting $text and without the need to escape the double-quotes. That way you don't have to express long blocks of text as Perl string literals.

Capturing can be used anywhere a Perl string expression is valid.

PerlPP commands can be nested within captured strings. For example, running the script

        <?= "!" . "?>foo<?= 42 ?><?" . "bar" ?>

will output !foo42bar. The 42 is generated by the nested <?= 42 ?> expression.

THE GENERATED SCRIPT

The code you specify in the input file is in a Perl environment with the following definitions in place:

        package PPP_foo;
        use 5.010001;
        use strict;
        use warnings;
        use constant { true => !!1, false => !!0 };

where foo is the input filename, if any, transformed to only include [A-Za-z0-9_].

This preamble requires Perl 5.10.1, which perlpp itself requires. On the plus side, requring v5.10.1 gives you // (the defined-or operator) and the builtin say. The preamble also keeps you safe from some basic issues.

BUGS

Please report any bugs or feature requests through GitHub, via https://github.com/interpreters/perlpp/issues.

SUPPORT

You can find documentation for this module with the perldoc command.

        perldoc Text::PerlPP

You can also look for information at:

ALTERNATIVES

Turns out there are about 2^googol modules that do similar things. We think this one works pretty nicely, but here are some others in case you disagree. In no particular order: Text::EP3, Text::Template, Basset::Template, ExtUtils::PerlPP, HTML::EP, PML, Preproc::Tiny, ePerl, iperl.

AUTHORS

Andrey Shubin (d-ash at Github; andrey.shubin@gmail.com) and Chris White (cxw42 at Github; cxwembedded@gmail.com).

LICENSE AND COPYRIGHT

Copyright 2013-2018 Andrey Shubin and Christopher White.

This program is distributed under the MIT (X11) License: http://www.opensource.org/licenses/mit-license.php

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.