NAME

iperl - bring any text documents alive with bits of embedded Perl

USAGE

iperl[ option|file] ...

Options may be repeated and are processed in the order specified. This means that while processing a file, all options encountered further left are applied. Multiword option-names may be separated by an underscore instead of a dash.

If present, the environment variable $IPERL is processed as though the parameters in it were given at the beginning of the command-line. No Shell syntax is parsed, except that it is split on spaces.

The vitamins -- ahem! -- options -C, -d, -D, -E, -I, -o and -U are like in the C compiler or m4 macro processor.

-A, --auto, --autostyle

Revert to autostyle-detection.

-B, --bang, --unix

Set style useful among others for typical Unix files, i.e. comment-lines begin with #, lines of Perl begin with !, !{...}! is for bits of Perl, !<...>! for printing bits of Perl and an optional leading & for macro invocations.

-c, --cache[ flag]

If flag is 1 cache all files given on the command line or in include directives, such that they are not reread and recompiled when included again.

-C, --comment-level[ flag]

Without flag do not discard comments. If flag is 2, discard even if there is whitespace before or after the comment. If it is 3, discard all comments.

--control, --control-chars, --ctrl

Set style based on control characters, i.e. lines of Perl begin with ^A, ^B...^E is for bits of Perl and ^P...^E for printing bits of Perl.

-d, --debug flags

Output the generated intermediate programme, rather than executing it.

-D, --define macro[=definition]

Define macro as definition or as 1 if none.

-e, --eval expr

Evaluate expr as a Perl programme.

-E, --cpp (default when called as cpp)

Set style as in C preprocessor, i.e. lines of Perl begin with # and defined macros have no syntactic sugar.

-f, --file, --include file

Same as a file argument without option. This is useful when file starts with a -.

-G, --generic /comment/print/printend/perl/perlend/

Defines a simple style. Takes 5 regexps delimited by any character, / here. The style swallows anything that matches comment. Anything between print and printend is a printing bit of Perl, while anything between perl and perlend is simple Perl.

-i, --include-string string

Allows directly providing a document on the commandline. The variable @documents contains the string '<COMMANDLINE>' in this case.

-I, --include-dirs string

Appends to the list of directories where include first searches for files not found in the current directory.

-M, --m4 (default when called as m4)

Set style as in m4 preprocessor, i.e. perl({...}) is for bits of Perl, perl(<...>) for printing bits of Perl and many m4-macros are available.

-o, --output file

Redirect output for the following documents to file, which may be any valid argument to open for output. An initial > is however optional.

-O, --output-rule

When reading from stdin, a pipe or an --include-string document, the output is directed to a file named stdin.out, pipe.out or include-string.out. A number n is added before the dot and then incremented when in the same invocation another pipe or --include-string document is encountered, regardless whether such a file already exists.

When reading from a normal file, the output is directed to a file named similarly. If the filename has a suffix other than p[hlms], pdb, p[bgnp]m, php, php[1-4] or [ch]pp starting or else ending with a p that letter is eliminated. Otherwise .out is appended.

This option remains in effect until given again or an option --output overrides it.

-P, --pod[ flag]

If flag is 1 remove any pod from document. Else if flag is not present or 0 set style suitable for pod, i.e. paragraphs of Perl start with =for perl or are surrounded by =begin perl and =end perl, within paragraphs P<{...}> is for bits of Perl, P<...> for printing bits of Perl and defined macros are called as M<macro> or M<macro( arg, ... )>.

-S, --sgml, --html, --xml, --markup-language

Set style suitable for SGML based languages such as HTML or XML. Bits of Perl are embedded in <perl>...</perl> or <server>...</server> or <script runat=server>...</script>. Printing bits of Perl (entities) are &<...>; or `...` and macro entities are &macro; or &macro( arg, ... );.

-t, --trace macro

Trace macro when it will be defined.

-U, --undefine macro

-v, --version

-?, --help

An argument file may be any valid argument to open for input. If no file is given, nor an -f or -i option, standard input is read.

DESCRIPTION

This is the commandline frontend of an inverse Perl interpreter, where normal text gets printed as is, while Perl statements have to be specially marked as such. Loop or conditional blocks can surround normal text.

If no style is explicitly set, it is automatically determined from either an Emacs kind of local variables specification for iPerl-style, or the file-name if any, or by looking at the document-contents for constructs specific to some style.

SEE ALSO

Text::iPerl, web-iPerl, iPerl.el, perl, http://beam.to/iPerl/