NAME
XML::API - Perl extension for writing XML
VERSION
0.30 (2016-04-11)
SYNOPSIS
use XML::API;
my $x = XML::API->new(doctype => 'xhtml');
$x->_comment('My --First-- XML::API document');
$x->html_open();
$x->head_open();
$x->title('Test Page');
$x->head_close();
$x->body_open();
$x->div_open(-id => 'content');
$x->p(-class => 'test', 'Some <> input');
$x->ns__p(-class => 'test', '& some other &stuff;');
$x->div_close();
$x->body_close();
$x->html_close();
print $x;
Will produce this nice output:
Test Page
Some <<odd>> input
& some other &stuff;
DESCRIPTION
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.
TUTORIAL
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:
$x->html_open;
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->head_open;
$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:
$x->head_close();
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->div_open();
$x->_add('Content added after the _open');
The final thing is to close out the elements and render the docment.
$x->div_close();
$x->body_close();
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();
$h->head_open
...
my $x = XML::API::XHTML->new();
$x->html_open;
$x->_add($h);
$x->html_close;
print $x;
Note that it is also possible to call the XML::API:: class
directly.
CLASS SUBROUTINES
new
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.
CONTENT
$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:
<---- 'current' element
<---- future elements/content goes here
then $x->head_open(-attribute => $value) means the tree is now:
<---- 'current' element
<---- future elements/content goes here
$x->_open('element', -attribute => $value, {attr2 => 'val2'}, $content)
The generic/underlying implementation of $x->element_open. Useful if
your element names are not suitable as Perl method calls, or are
otherwise funny (eg starting with '_').
$x->_add($content)
Add $content to the 'current' element. If there is no current element
then this method will croak.
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 croak if you attempt to add $x to itself or if $x
is an empty XML::API object.
$x->_raw($content)
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:
<---- 'current' element
$content
<---- future elements/content goes here
then $x->p_close() means the tree is now:
<---- 'current' element
$content
<---- 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->_close('element')
The generic/underlying implementation of $x->element_close. Useful if
your element names are not suitable as Perl method calls, or are
otherwise funny (eg starting with '_').
$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');
$x->_add($content);
$x->element_close;
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:
$x->_element('element',...)
The generic implementation of $x->element. Useful if your element names
are not suitable as Perl method calls, or are otherwise funny (eg
starting with '_').
$x->element_raw('raw content',...)
Adds unescaped content inside an element named 'element'. This is a
shortcut for the case where you find yourself doing the following:
$x->element_open();
$x->_raw($content);
$x->element_close();
$x->ns__element_open(...)
Same as $x->element_open but prefixed with an XML namespace. Equivalent
to the following.
$x->_ns('ns');
$x->element_open(...);
...
$x->element_close;
$x->_ns(undef);
$x->ns__element(...)
Same as $x->element but prefixed with an XML namespace. Equivalent to
the following.
$x->_ns('ns');
$x->element(...);
$x->_ns(undef);
$x->_comment($comment)
Add an XML comment to $x. Is almost the same as this:
$x->_raw("\n')
Except that indentation is correct. Any occurences of '--' in $content
will be replaced with '- -'.
$x->_cdata($content)
A shortcut for $x->_raw("\n");
$x->_css($content )
Adds $content inside a pair of CDATA tags which are encapsulated inside
CSS comments. Similar to:
$x->_raw('/**/');
$x->_javascript($script )
A shortcut for adding $script inside a pair of