|a filename||in which case the file is read and parsed;|
|a string of XML||in which case it is read and parsed. How do we tell if weve got a string or a filename? If it begins with _TINY_XML_STRING_ then its a string. That prefix is, of course, ignored when it comes to actually parsing the data. This is intended primarily for use by wrappers which want to retain compatibility with Ye Aunciente Perl. Normal users who want to pass in a string would be expected to use IO::Scalar.|
|a glob-ref or IO::Handle object||in which case again, the file is read and parsed.|
The remaining parameters are a list of key/value pairs to make a hash of options:
|fatal_declarations||If set to true, <!ENTITY...> and <!DOCTYPE...> declarations in the document are fatal errors - otherwise they are *ignored*.|
|no_entity_parsing||If set to true, the five built-in entities are passed through unparsed. Note that special characters in CDATA and attributes may have been turned into &, < and friends.|
If set to true, any unrecognised entities (ie, those outside the core five
plus numeric entities) cause a fatal error. If you set both this and
no_entity_parsing (but why would you do that?) then the latter takes
Obviously, if you want to maximise compliance with the XML spec, you should turn on fatal_declarations and strict_entity_parsing.
Element nodes are hashrefs with the following keys:
|type||The nodes type, represented by the letter e.|
|name||The elements name.|
|attrib||A hashref containing the elements attributes, as key/value pairs where the key is the attribute name.|
|content||An arrayref of the elements contents. The arrays contents is a list of nodes, in the order they were encountered in the document.|
|type||The nodes type, represented by the letter t.|
|content||A scalar piece of text.|
The parsefile function is so named because it is intended to work in a similar fashion to XML::Parser with the XML::Parser::EasyTree style. Instead of saying this:
you would say:
use XML::Tiny; my $tree = XML::Tiny::parsefile(something.xml);
If you find a document where that is not the case, please report it as a bug.
The module is intended to be fully compatible with every version of perl back to and including 5.004, and may be compatible with even older versions of perl 5.
The lack of Unicode and friends in older perls means that XML::Tiny does nothing with character sets. If you have a document with a funny character set, then you will need to open the file in an appropriate mode using a character-set-friendly perl and pass the resulting file handle to the module. BOMs are ignored.
The following parts of the XML standard are handled incorrectly or not at all - this is not an exhaustive list:
Element tags and attributes Including self-closing tags like <pie type = steak n kidney />; Comments Which are ignored; The five core entities ie &, <, >, ' and "; Numeric entities eg A and A; CDATA This is simply turned into PCDATA before parsing. Note how this may interact with the various entity-handling options;
Namespaces While documents that use namespaces will be parsed just fine, theres no special treatment of them. Their names are preserved in element and attribute names like rdf:RDF. DTDs and Schemas This is not a validating parser. <!DOCTYPE...> declarations are ignored if youve not made them fatal. Entities and references <!ENTITY...> declarations are ignored if youve not made them fatal. Unrecognised entities are ignored by default, as are naked & characters. This means that if entity parsing is enabled you wont be able to tell the difference between and . If your document might use any non-core entities then please consider using the no_entity_parsing option, and then use something like HTML::Entities. Processing instructions These are ignored. Whitespace We do not guarantee to correctly handle leading and trailing whitespace. Character sets This is not practical with older versions of perl
While feedback from real users about this module has been uniformly positive and helpful, some people seem to take issue with this module because it doesnt implement every last jot and tittle of the XML standard and merely implements a useful subset. A very useful subset, as it happens, which can cope with common light-weight XML-ish tasks such as parsing the results of queries to the Amazon Web Services. Many, perhaps most, users of XML do not in fact need a full implementation of the standard, and are understandably reluctant to install large complex pieces of software which have many dependencies. In fact, when they realise what installing and using a full implementation entails, they quite often dont *want* it. Another class of users, people distributing applications, often can not rely on users being able to install modules from the CPAN, or even having tools like make or a shell available. XML::Tiny exists for those people.
I welcome feedback about my code, including constructive criticism. Bug reports should be made using <http://rt.cpan.org/> or by email, and should include the smallest possible chunk of code, along with any necessary XML data, which demonstrates the bug. Ideally, this will be in the form of a file which I can drop in to the modules test suite. Please note that such files must work in perl 5.004.
For more capable XML parsers: XML::Parser
The requirements for a module to be Tiny <http://beta.nntp.perl.org/group/perl.datetime/2007/01/msg6584.html>
David Cantrell <email@example.com>
Thanks to David Romano for some compatibility patches for Ye Aunciente Perl;
to Matt Knecht and David Romano for prodding me to support attributes, and to Matt for providing code to implement it in a quick n dirty minimal kind of way;
to the people on <http://use.perl.org/> and elsewhere who have been kind enough to point out ways it could be improved;
to Sergio Fanchiotti for pointing out a bug in handling self-closing tags, for reporting another bug that I introduced when fixing the first one, and for providing a patch to improve error reporting;
to Corion for finding a bug with localised filehandles and providing a fix;
to Diab Jerius for spotting that element and attribute names can begin with an underscore;
to Nick Dumas for finding a bug when attribs have their quoting character in CDATA, and providing a patch;
to Mathieu Longtin for pointing out that BOMs exist.
Copyright 2007-2010 David Cantrell <firstname.lastname@example.org>
This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. Its up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.
This module is also free-as-in-mason software.
|perl v5.20.3||XML::TINY (3)||2010-12-16|