The <perl-use/> command

TopLeaf perl calls are by means of user defined subroutines. These subroutines are declared using perl module (.pm) files.

To invoke a perl module, use a command such as:

<perl-use lib="LIB" module="MOD" endsub="SUB"/>


  • LIB (optional) is a pathname pointing to a Perl library.

  • MOD (optional) is the name of a standard or user defined module.

  • SUB (optional) is the name of a subroutine within the MOD module that is called when a composition run is complete. No arguments are passed to the subroutine, and its return value is not checked (in particular, no error will be indicated if it does not exist). The subroutine must exist in the MAIN package.

If neither LIB nor MOD is present the command is ignored.

By default, user defined modules must be located in a Perl subfolder of either the current partition folder, the current publication folder or the folder containing mappings.tlx. For example, the command:

<perl-use module="Test"/>

will invoke the module PartPub\Perl\ where PartPub is either the partition folder or the publication folder. If a module is found in both locations, the partition takes precedence. If you need to reference Perl modules from any other location, you must specify the appropriate path in the LIB attribute of the current (or some previous) <perl-use/>.

Note that module invocations are for purposes of declaration and initialization only. Reading from STDIN is disabled and printing to STDOUT or STDERR is ignored. In addition, a module will only be executed once. Subsequent <perl-use/> commands on the same module will be ignored.

Most TopLeaf Perl modules will consist of simple subroutine definitions. A subroutine called from TopLeaf must exist in the MAIN package, though it is free to call other subroutines and methods in other packages. The following section shows how such a subroutine can be called from within TopLeaf.

[Warning] Warning

The current Perl interface does not support dynamic loading. In other words only modules that consist solely of Perl code may be called. Attempting to use modules that have compiled components will give a run-time error.