Perl Code

Scalar variables (integers, strings, etc) that have been defined by your macro are automatically made available to the Perl code. Array and hash variables are also available. In general object variables (eg: the Date object) are not available in Perl. The only exception is for Text objects, which will be available to Perl as string values.

Changes made to the value of any variable inside the perl block are reflected outside of it. However the reverse is not true- variables defined in your Perl code are not available outside that block of Perl. If Perl code alters the value of a Text object, the attributes and identity of the object will be lost. For example, a variable containing a table cell’s text will no longer be considered as part of the table or document.

If a macro has many large text variables transferring the values into and out of Perl can become expensive. It may be beneficial to limit the variables seen by Perl using the command:

Set Exported Perl Variables [variableName1], ... [variableNameN] v1.1

Limits the variables that are seen by Perl blocks in the macro to only those named. If no names are given then Perl blocks will not have access to any variables outside their block. To restore the default behavior of allowing Perl unlimited access to all variables, use the special name ‘*’.

Set Include Perl UTF Preamble shouldInclude v1.1

By default each code block executed by Perl will be prepended with code that sets the input/output text encoding to UTF-8. This is required for the automatic variable transferring to work correctly. Under rare circumstances it may be desirable to suppress this preamble by calling this command with a false value. 

Warning: excluding the preamble is not recommended, as text variables may improperly change value, even if they are not modified by Perl.

Set Delete Temporary Perl Scripts shouldDelete v1.2

Whenever a Perl block is executed the relevant code is first written to a temporary file for Perl to interpret. Under normal circumstances this temporary script is deleted immediately after use. This command can be used to allow temporary script files to remain undeleted for debugging purposes.

The folder where temporary files are saved is governed by the system and usually resides in the hidden portion of the file system, eg: ‘/private/var’. The temporary scripts are named like ‘nisus.pl’, ‘nisus-1.pl’, etc.