/ 
XML-Code-0.3
River stage one • 1 direct dependent • 1 total dependent
++
/ XML::Code

NAME

XML::Code - Perl module for converting XML hash structures into plain text.

SYNOPSIS

   use XML::Code;

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

   $sub_content = new XML::Code ('sub-content');
   $content->add_child ($sub_content);
   $sub_content->set_text ('text node');

   print $content->code();

EXTENDED SYNOPSIS

   use XML::Code;

   # Creating top XML node.
   my $content = new XML::Code ('content');

   # Requesting <?xml?> and <?xml-stylesheet?> directives.   
   $content->version ('1.0');
   $content->encoding ('Windows-1251');
   $content->stylesheet ('test.xslt');

   # Adding attribute.
   $content->{'level'} = 'top';

   # Adding child node.    
   $sub_content = new XML::Code ('sub-content');
   $content->add_child ($sub_content);

   # Setting text content of a node.    
   $sub_content->set_text ('inner text');

   # Adding anonimous child node.   
   $content->add_child (XML::Code->new ('sub3'));

   # Inserting comments and processing instuctions.    
   $content->comment ('This is a comment & more');
   $content->pi ("instruction intro=\"hi\"");

   # Producing plain text XML code.
   print $content->code();

DESCRIPTION

XML::Code module is designed to enable simple object-oriented procedure of creating XML data. As soon as a programmer realizes that XML and OOP are kindred and have sibling connections he or she wants to use objects instead of plain text in the phase of producing XML files. XML::Code allows thinking of XML tags as of nested named objects and expects XML::Code::code() method be called to produce plain text XML.

XML::Code only produce code: that means the module does not provide methods of random access (like XPath does) to the XML structure though tree elements are fully accessible as nested hashes.

METHODS

Creating nodes

How to create XML::Code 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

Attributes

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.

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'));

Getting information

name()

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

Code formatting operations.

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.

Generating code

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.

AUTHOR

Andrew Shitov <andy@shitov.ru>