Creating nodes

new() (Constructor)

Creates an XML node and return corresponding blessed reference. Call of new() expects that you give tag name as an argument of new().

comment() (Constructor)

Creates comment node. This method should be normally called as a method of existing XML::Code object.

pi() (Constructor)

Creates a node of prosession instruction. Preferably should be called with existing XML::Code object.

Creating attributes and content

If you have a node, you may access its attributes as if you have a hash reference:

   $tag = new XML::Code ('tag-name');
   $tag->{'tag-attribute'} = 'attribute value';
   print $tag->{'tag-attribute'};

set_text()

Sets some text value of the node. Note that you still may add children to the node. When you adds both plain text and child node, text value always appears before any child when calling code() method.

add_textnode()

If you need to construct mixed content of a node like this:

   <p><b>Selected</b> text <i>follows</i>.</p>

you may call add_textnode() to insert plain text at a certain position:

   $p->add_child ($b);
        $p->add_textnode (' text ');
        $p->add_child ($i);

escape()

Normally any content of the node will be escaped during rendering (i. e. special symbols like '&' will be replaced by corresponding entities). Call escape() with zero argument to prevent it:

   my $p = new XML::Code ('p');
        $p->set_text ("—");
        $p->escape (0);
        print $p->code(); # prints <p>&#8212;</p>
        $p->escape (1);
        print $p->code(); # prints <p>&amp;#8212;</p>

Escape action set by calling escape() affects tag attributes as well.

add_child()

Adds a child to the current XML node. This method takes a reference to existing XML::Code object. It is also possible to construct unreferenced child object while you call add_child(). Thus two following lines of Perl code are equivalent (the difference is that you can still manipulate child object in the first case):

   1. my $child = new XML::Code ('child'); $parent->add_child ($child);
   2. $parent->add_child (new XML::Code ('child'));

add_empty()

It is too boring to call constructor XML::Code() and add_child() to add an empty tag into resulting tree. Method add_empty() created an empty tag and inserts it into the current position:

   $p->add_empty ('br'); # adds <br/> within <p>...</p>.

Getting information

Returns a tag name of a node.

text()

If the node is a text-node, returns its text value. Note that this method does not evaluate text value of child nodes if they are present.

XML extras

version() and encoding()

When some value is passed to one (or both) of these methods you will get XML header directives in the resulting code (i. e. code generated by code()).

The following Perl code

   my $xml = new XML::Code ('top');
   $xml->version ("1.0");
   $xml->encoding ("Windows-1251");
   print $xml->code;

will produce this XML code:

   <?xml version="1.0" encoding="Windows-1251"?>
   <top/>

Note that setting version number may be omitted, in such a case it will be set to "1.0". Nevertheless you have to set at least either version number or encoding name to have <?xml?> prolog in the output. Normally these methods shold be applied to a top-level tag.

stylesheet()

Inserts <?xml-stylesheet?> instruction into resulting code so that resulting XML file may be transformed with some external XSLT-file.

doctype()

Adds !DOCTYPE instruction into output code.

        my $xml = new XML::Code ('wml');
        $xml->version ("1.0");
        $xml->doctype ('wml PUBLIC "-//WAPFORUM//DTD WML 1.1//EN" "http://www.wapforum.org/DTD/wml_1.1.xml"');

Generating code

Generates plain text XML code.

   $xml->code() produces tab-formatted output while
   $xml->code (-1) suppresses any tab spaces in the beging of lines.

You can also pass $xml->code() method any positive integer number: is this case output code will be right-shifted to that number of "\t" characters.