Help-Site Computer Manuals
  Algorithms & Data Structures   Programming Languages   Revision Control
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Perl extension for writing XML

XML::API - Perl extension for writing XML


XML::API - Perl extension for writing XML




  use XML::API;

  my $x = XML::API->new(doctype => 'xhtml');

  $x->_comment('My --First-- XML::API document');




  $x->title('Test Page');



  $x->div_open(-id => 'content');

  $x->p(-class => 'test', 'Some <<odd>> input');

  $x->p(-class => 'test', '& some other &stuff;');




  print $x;

Will produce this nice output:

  <?xml version="1.0" encoding="UTF-8" ?>

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict...>

  <!-- My - -First- - XML::API document -->

  <html xmlns="">


      <title>Test Page</title>



      <div id="content">

        <p class="test">Some &lt;&lt;odd&gt;&gt; input</p>

        <p class="test">&amp; some other &stuff;</p>





XML::API is a class for creating XML documents using object method calls. This class is meant for generating XML programatically and not for reading or parsing it.

A document author calls the desired methods (representing elements) to create an XML tree in memory which can then be rendered or saved as desired. The advantage of having the in-memory tree is that you can be very flexible about when different parts of the document are created and the final output is always nicely rendered.


The first step is to create an object. The 'doctype' attribute is mandatory. Known values (ie - distributed with XML::API) are 'xhtml' and 'rss'. The encoding is not mandatory and will default to 'UTF-8'.

  use XML::API;

  my $x = XML::API->new(doctype => 'xhtml', encoding => 'UTF-8');

$x is the only object we need for our entire XHTML document. It starts out empty so we want to open up the html element:


Because we have called a *_open() function the 'current' or 'containing' element is now 'html'. All further elements will be added inside the 'html' element. So lets add head and title elements and the title content ('Document Title') to our object:


  $x->title('Document Title');

The 'title()' method on its own (ie not 'title_open()') indicates that we are specifiying the entire title element. Further method calls will continue to place elements inside the 'head' element until we specifiy we want to move on by calling the _close method:


This sets the current element back to 'html'.

So, basic elements seem relatively easy. How do we create elements with attributes? When either the element() or element_open() methods are called with a hashref argument the keys and values of the hashref become the attributes:

  $x->body_open({id => 'bodyid'}, 'Content', 'more content');

or if you want, you can also use CGI-style attributes which I prefer because it takes less typing:

  $x->body_open(-id => 'bodyid', 'Content', 'more content');

By the way, both the element() and element_open() methods take arbitrary numbers of content arguments as shown above. However if you don't want to specify the content of the element at the time you open it up you can use the _add() utility method later on:


  $x->_add('Content added after the _open');

The final thing is to close out the elements and render the docment.



  print $x->_as_string();

Because we are not adding any more elements or content it is not strictly necessary to close out all elements, but consider it good practice.

You can add XML::API object to other objects, which lets you create for instance the head and body parts separately, and just bring them all together just before printing:

  my $h = XML::API::XHTML->new();



  my $x = XML::API::XHTML->new();




  print $x;

Note that it is also possible to call the XML::API::<doctype> class directly.



Create a new XML::API based object. The object is initialized as empty (ie contains no elements). Takes the following optional arguments:

  doctype  => '(xhtml|rss|WIX2)'

  encoding => 'xxx'

  debug    => 1|0

If a valid (ie known to XML::API) doctype is given then an object of class XML::API::DOCTYPE will be returned instead. This method will die if doctype is unknown. You can also call XML::API::DOCTYPE->new() directly.

For the effects of the encoding and debug parameters see the documentation for '_encoding' and '_debug' below.


$x->element_open(-attribute => $value, {attr2 => 'val2'}, $content)

Add a new element to the 'current' element, and set the current element to be the element just created. Returns a reference (private data type) to the new element which can be used in the _goto function below.

Ie given that $x currently represents:

  <html>  <---- 'current' element

          <---- future elements/content goes here


then $x->head_open(-attribute => $value) means the tree is now:


    <head attribute="$value">  <---- 'current' element

                               <---- future elements/content goes here




Add $content to the 'current' element. If there is no current element then this method will carp.

If $content is a scalar (ie plain text or numbers) then the characters '<&``>' will be XML-escaped. If $content is another XML::API object the elements of that object will be added to content tree.

This method will also carp if you attempt to add $x to itself or if $x is an empty XML::API object.


Adds unescaped content to the 'current' element. You need to be careful of characters that mean something in XML such as '<','&' and '>'. This method will die if $content is an XML::API derivative or if $x does not have a current element.

$x->element_close( )

This does not actually modify the tree but simply tells the object that future elements will be added to the parent of the current element. Ie given that $x currently represents:


    <p>  <---- 'current' element


           <---- future elements/content goes here



then $x->p_close() means the tree is now:

  <div>    <---- 'current' element




           <---- future elements go here


If you try to call a _close() method that doesn't match the current element a warning will be issued and the call will fail.

$x->element(-attribute => $value, {attr2 => 'val2'}, $content)

Add a new element to the 'current' element but keep the 'current' element the same. Returns a reference (private data type) to the new element which can be used in the _goto function below.

This is effectively the same as the following:

    $x->element_open(-attribute => $value, -attr2=>'val2');



If $content is not given (or never added with the _add method) for an element then it will be rendered as empty. Ie, $x->br() produces:

    <br />


Add an XML comment to $x. Is almost the same as this:




Except that indentation is correct. Any occurences of '--' in $content will be replaced with '- -'.


A shortcut for $x->_raw(``\n<![CDATA['', $content, `` ]]>'');

$x->_javascript($script )

A shortcut for adding $script inside a pair of <script type=``text/javascript''> elements and a _CDATA tag.


Adds content to the current element, but will parse it for xml elements and add them as method calls. Regardless of $content (missing end tags etc) the current element will remain the same. Relies on XML::SAX to do the parsing.


Sometimes you may want to just build some kind of abstract syntax tree structure and just feed it to XML::API without having to make all the method calls yourself. This method lets you do just that.

The following input:

  p => [

      label => 'Body',

      textarea => [

          -rows  => 10,

          -cols  => 50,

          -name  => 'body',

          'the body',



results in the following xml:



    <textarea cols="50" name="body" rows="10">the body</textarea>


$x->_attrs( )

Allows you to get/set the attributes of the current element. Accepts and returns and hashref.



Set the encoding definition produced in the xml declaration. Returns the current value if called without an argument. This is an alternative to defining the encoding in the call to 'new'.

The XML encoding definition for objects is determined by the following, in this order:

  * the last call to _encoding

  * the encoding parameter given at object creation

  * $XML::API::ENCODING, set by your script before calling new

  * UTF-8, the package default

If you _add one object to another with different encodings the top-level object's definition will be used.

$x->_set_lang($lang, [$dir])

Add an 'xml:lang' attribute, and an optional text direction $dir to the next element to be created. In terms of output created this means that:

  $x->_set_lang('de', 'ltr');

  $x->p('Was sagst du?');

is equivalent to:

  $x->p(-xml:lang => 'de', -dir => 'ltr', 'Was sagst du?');

with the added difference that _set_lang keeps track of each call and the list of languages set can be retrieved using the _langs method below.

The first time _set_lang is called the xml:lang attribute will be added to the root element instead of the next one, unless $x is a generic XML document. Without a XML::API::<class> object we don't know if we have the root element or not.


Returns the list of the languages that have been specified by _set_lang.


Turn on|off debugging from this point onwards. Debugging appears as xml comments in the rendered XML output.

$x->_current( )

Returns a reference (private data type) to the current element. Can be used in the _goto method to get back to the current element in the future.


Set an identifier for the current element. You can then use the value of $id in the _goto() method.


Change the 'current' element. $id is a value which has been previously used in the _set_id() method, or the return value of a _current() call.

This is useful if you create the basic structure of your document, but then later want to go back and modify it or fill in the details.


$x->_as_string( )

Returns the xml-rendered version of the object. If $x has the root element for the doctype, or if $x is a pure XML::API object then the string is prefixed by the XML declaration (with the encoding as defined in the '_encoding' method documentation):

  <?xml version="1.0" encoding="UTF-8" ?>

The xml is cached unless the object is modified so _as_string can be called mulitple times in a row with little cost.

$x->_fast_string( )

Returns the rendered version of the XML document without newlines or indentation.


See the source code of XML::API::XHTML for how to create a new doctype.

These are methods which may return interesting values if the XML::API::<class> module has overloaded them.


Returns the XML DOCTYPE declaration


Returns the root element


Returns a hashref containing default key/value attributes for the root element


Returns a string suitable for including in a HTTP 'Content-Type' header.


Since version 0.10 a call to new() does not automatically add the root element to the object. If it did so you wouldn't be able to add one object to another.

Version 0.13 made the doctype parameter to new() optional, so that generic (ie no DOCTYPE declaration) XML documents can be created.

Version 0.15 removed the pointless _print method.


You can see XML::API in action in NCGI.


Mark Lawrence <>

A small request: if you use this module I would appreciate hearing about it.


Copyright (C) 2004-2007 Mark Lawrence <>


This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.