Returning (Untagged) data from Perl

We have seen that TopLeaf can pass arguments to perl subroutines, but how do those subroutines return information to TopLeaf?

The TopLeaf perl environment includes two functions for this purpose. The first allows a subroutine to set a TopLeaf variable using the following syntax:

TopLeaf::set_var(VN => "STR");

where VN is the name of a TopLeaf variable, and STR is the string to be assigned. Because the call includes an explicit package name (TopLeaf), it can be invoked from within any other package, but will not clash with any other set_var functions or methods which may be defined.

The second supplied function invokes a user-defined custom marker as follows:

TopLeaf::custom_marker(CM [, ATTn => VALn] ...);

where CM is the marker name and ATTn/VALn are the name/value of the n-th user supplied attribute.

Thus the call:

TopLeaf::custom_marker(Guest, Name=>$name, Smoker=>"no");

will cause the custom marker:

<Guest Name="Fred" Smoker="no"/>

to be executed immediately when typesetting resumes. Note that the marker will be empty (no content) so any accompanying information must be supplied as attributes.

In all returned data (variables and attributes), the characters:

< > { } & "

will be converted to entities (such as &lt;). A value of undef will be converted to the empty string.

Any value returned by the called subroutine is silently discarded, so if neither set_var() or custom_marker() is called, then the subroutine will not pass any information back to TopLeaf at all. This can legitimately occur when the subroutine is setting up some aspect of the perl environment for use by a subsequent subroutine call.