``:lenient:`` Causes the exit code for the subprocess to be ignored. ``:file: <filename>`` Takes the perl code from file <filename>. ``:literal:`` Interpret the returned value as a literal block.

If this option is not present, the return value is interpreted based on its type. If you return a text string, the text is interpreted as reStructuredText and is parsed again. If you return an internal DOM object (or list of them), the object is included directly into the parsed DOM structure. (This latter option requires knowledge of trip internals, but is the only way to create a pending DOM object for execution at transformation time rather than parse time.)

The perl directive makes the following global variables available for use within the perl code:

``$SOURCE`` The name of the source file containing the perl directive. ``$LINENO`` The line number of the perl directive within $SOURCE. ``$DIRECTIVE`` The literal text of the perl directive. ``$SUBSTITUTION`` The name of a substitution definition being defined by the perl directive, or undefined if not within a substitution definition ``@INCLUDES`` Array of [filename, linenumber] pairs of files which have included this one. ``$opt_<x>`` or ``$opt{x}`` The ``<x>`` option from the command line. Changing one of these variables has no effect upon the parser. However, you can effectively set the ``-D x=y`` option, possibly affecting subsequent parsing, by assigning ``y`` to ``$PARSER->{opt}{D}{x}``. ``$PARSER`` The Text::Restructured parser object to allow text parsing within a perl directive. ``$TOP_FILE`` The name of the top-level file. ``$VERSION`` The version of prest (${main::VERSION}).

The following defines are processed by the perl directive:

-D perl='perl-code' Specifies some perl code that is executed prior to evaluating the first perl directive. This option can be used to specify variables on the command line; for example::

  -D perl='$a=1; $b=2'

defines constants ``$a`` and ``$b`` that can
be used in a perl block.
-D trusted      Must be specified for perl directives to use any
operators normally masked out in a Safe environment.
This requirement is to prevent a perl directive in a
file written elsewhere from doing destructive things
on your computer.
=end Description
=end reST