NAME
TVL::PXC - Parse XML Configuration files - version 0.01
SYNOPSIS
use TVL::PXC;
# Parse some XML
my $p = new TVL::PXC ( $filename );
# display the XML that was just read
print $p->dumpTree(1);
# get the top tag
my $tree = $p->getTree;
# Parse some XML and retrieve the top tag in one swoop
my $p2 = new TVL::PXC ( '<?xml ?><myTag name="not important">...</myTag>' )->getTree;
# Set debug levels
TVL::PXC->debug(1); # module-wide, including derived modules (such
# as TVL::PXC::Tag)
$p->debug(1); # for this object only - does not shadow
# the global level, but can increase it.
DESCRIPTION
This module creates an object which will parse an XML configuration file and present the result as a TVL::PXC::Tag object. The object be retrieved or object modules can be used to traverse it.
The XML file must not have more than MAXLVL nested tags, currently 10. A fatal error will be raised if nesting is deeper than the configured maxium. This is an arbitrary level and may be adjusted for individual installations by specifying a different value for the constant MAXLVL in the top of the module file. Each nested tag will cause several recursions, so the size of the stack is ultimately limiting.
The following elements are recognised:
- XML tags - the value of the XML tag is used to name the TVL::PXC::Tag object.
- Tag attributes - will be stored in the attributes field of the TVL::PXC::Tag object as a hash in which the attribute names are the keys.
- Plain text and CDATA sections - stored in the text field of the TVL::PXC::Tag object.
- Enclosed XML tags - each XML tag within a containing tag is stored in its own TVL::PXC::Tag object, which is added to an array in the tag attribute of the master tag object.
Depends only on XML::Parser.
Methods
new($)
Constructor. The constructor takes one argument, which must be the name of een existing XML file, or a string containing valid XML. The file or string will be parsed by XML::Parser using the Tree style. The returned object has the result of the parse operation in a TVL::PXC::Tag object, which can be accessed as $p->{xmltree}.
debug(;$)
Debug can be called as a static method and as an object method. In the first case it will work on the package-wide debug level and in the latter it works on the calling instance only. When called with a numeric argument, the debug level will be set to that value. The return value is the current debug level set for the package or instance respectively.
Increasing values will produce increasing amounts of debug information, to the point of verbal diarreah. All debug information is printed to STDERR.
Example:
- Package debug level
print "Package wide debug level is: " . TVL::PXC->debug(); TVL::PXC->debug(2); - Set the debug level a bit higher just for instance $p:
print "Instance debug level is: " . $p->debug(); $p->debug(4);
dumpTree(;$)
Dump the tag to STDOUT as a readable tree or an XML document. The optional argument, when set to a true value (i.e. something else than 0), causes the output to be XML.
The XML produced by this method may differ from the original, as XML::Parser seems to add newlines and whitespace when a CDATA section is encountered. Also, this dump will wrap any text that contains characters that may be interpreted as XML characters in a CDATA section, even when the original document was valid and dit not have such sections. This is a safety measure. Currently the set of characters that trigger a CDATA section includes:
- single characters: < > \
- Oracle line comment character: --
getTree
Retrieve the tree object. This returns the top object on the tree, which is of type TVL::PXC::Tag. This will have the root level name of your XML file. See the documentation of TVL::PXC::Tag on methods to manipulate the tree.
AUTHOR
Tony van Lingen (tony.vanlingen@pacificdbms.com.au)
BUGS AND IRRITATIONS
As this is not yet tested by others, no bugs and only minor irritations have been identified. ^_^
SEE ALSO
TVL::PXC::Tag, XML::Parser::Style::Tree
NAME
TVL::PXC::Tag - Parse XML Configuration Tag - version 0.01
SYNOPSIS
use TVL::PXC;
# parse a file and retrieve the top tag
my $pxc = new TVL::PXC( 'gurulist.xml' ) ;
my $t = $pxc->getTree;
# get a second-level tag and print it
$t = $t->tag('allround') ;
print $t->as_string;
DESCRIPTION
A tag contains the representation of one XML tag, and an array with references to tags which are contained within the current one, in the order in which they were read. The representation consists of:
- name of the XML tag
- attribute hash, the keys of which are the tag's attributes
- parent array, containing the names of all containing tags with the present one i n last place.
- text contained within the tag, either bare or in a CDATA block.
Depends on XML::Parser and TVL::PXC.
Methods
new($;$$)
Constructor. Parameters:
- name - name of the XML tag to be stored
- parent - optional: TVL::PXC::Tag object which is the parent of the new object, or any scalar or undef value if none. Only parent objects will be used, scalar values are ignored.
- attributeRef - optional: reference to a HASH containing the attributes of this tag. The attribute name should be the key. XML::Parser, when used with the Tree style, returns the attributes in this way.
addKids(*)
Add a new TVL::PXC::Tag child object or replace the child object array with a new one. If an array is passed, the contents should consist exclusively of TVL::PXC::Tag objects. No checking is done on the contents. After all, the consequences will show soon enough, when the children are used.
as_string
Returns a representation of the tag object as a string. The string is formatted as in the following fictuous example:
----- TVL::PXC::Tag=ARRAY(0x25f8bc8) ------
name : cooldude
path : gurus/allround/cooldude
subtags: 0
-----------------------
Attributes:
wait = forever
-----------------------
Text:
select me
from who_s_a_cool_dude
where appreciation like '%astronomical%'
attrib($;$)
get and optionally set the value of an attribute. The parameters are:
- name - attribute name
- value - new value for the attribute
attributes
Retrieve the attribute hash.
hasAttrib
Boolean to indicate the existance of attributes. The return value is the actual number of attributes in the hash.
hasTags
Boolean to indicate the existance of children. The return value is the actual number.
name
Returns the name of the XML tag that the object represents.
parents
Returns an array of parent names.
path
Returns the array of parent names as a string with the / as a separator symbol.
tag($)
Returns a child tag with the specified name. Caution: this will return only the first instance of such a tag. When there are multiple instances of a tag in the child array, it is best to use the tags method to retrieve the entire array.
tags
Returns the child array as a list.
text(;$)
Get and optionally set the text of this tag. The optional variable is the new text, which will replace the existing text (if any).
AUTHOR
Tony van Lingen (tony.vanlingen@pacificdbms.com.au)
BUGS AND IRRITATIONS
As this is not yet tested by others, no bugs and only minor irritations have been identified. ^_^
SEE ALSO
TVL::PXC, XML::Parser::Style::Tree