Passing XML structure into and out of Perl extensions

The following command is used when you need to pass an arbitrary XML fragment into a Perl extension:

<perl-call sub="SUB" copy="VN1"/>

In particular the form:

<perl-call sub="SUB" copy="content" />

passes the current element content (provided Scan element content is in force).

Neither TopLeaf::set_var nor TopLeaf::custom_marker can be used to return XML fragments to TopLeaf. This is because both commands present the returned string as an attribute value, which cannot contain XML tags. If you need to return XML tags, custom markers or system commands to the TopLeaf composition engine, then use:

TopLeaf::emit_xml($frag, ...);

where $frag contains the XML fragment to be processed. The fragment must be well-formed with properly balanced start and end tags. If multiple fragments are specified, they are concatenated together before being returned.

Custom markers and system commands can also be included in the fragment. To distinguish them from ordinary document tags, the following convention is used:

  • use <tag> for document tags thus:

    <para>A paragraph.</para>
  • use <%Cust> for custom markers:

    <%Bold>some emphatic text</%Bold>
  • use <$cmd> for TopLeaf system commands:

    <$fill string="."/>

The system automatically converts custom markers and commands whenever XML is passed to or from Perl.

[Warning] Warning

Processing instructions are not allowed in the XML fragment. Attempting to return processing instructions may result in errors and/or unpredictable behavior.

[Note] Note

The above convention produces non-standard XML, as the % and $ characters are not valid tag name characters.

If you need to use standard utilities to parse or otherwise process your XML fragment, you should replace these characters, perhaps with an appropriate namespace (e.g. <cust:Bold>, <sys:fill>). Remember to restore the original forms before returning the fragment to TopLeaf.

[Note] Note

Use the TopLeaf::emit_xml function to return ordinary strings to TopLeaf if you need to avoid replacing special chars with entities (see previous section).

[Warning] Warning

It is the user's responsibility to ensure that any returned fragment is well-formed, and that tag, custom marker and command names are valid and appropriate. Returning an invalid XML fragment will either result in an immediate fatal error (if you are lucky), or obscure and peculiar behavior (if you are not).