NAME

XML::Tiny - simple lightweight parser for a subset of XML

DESCRIPTION

XML::Tiny is a simple lightweight parser for a subset of XML

SYNOPSIS

    use XML::Tiny qw(parsefile);
    open($xmlfile, 'something.xml);
    my $document = parsefile($xmlfile);

This will leave $document looking something like this:

    [
        {
            type   => 'e',
            attrib => { ... },
            name   => 'rootelementname',
            content => [
                ...
                more elements and text content
                ...
           ]
        }
    ]

FUNCTIONS

The "parsefile" function is optionally exported. By default nothing is exported. There is no objecty interface.

parsefile

This takes at least one parameter, optionally more. The compulsory parameter may be:

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 we've got a string or a filename? If it begins with "_TINY_XML_STRING_" then it's 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 former case is for compatibility with older perls, but makes no attempt to properly deal with character sets. If you open a file in a character-set-friendly way and then pass in a handle / object, then the method should Do The Right Thing as it only ever works with character data.

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.
strict_entity_parsing: 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 precedence.
Obviously, if you want to maximise compliance with the XML spec, you should turn on fatal_declarations and strict_entity_parsing.

The function returns a structure describing the document. This contains one or more nodes, each being either an 'element' node or a 'text' mode. The structure is an arrayref which contains a single 'element' node which represents the document entity. The arrayref is redundant, but exists for compatibility with XML::Parser::EasyTree.

Element nodes are hashrefs with the following keys:

type: The node's type, represented by the letter 'e'.
name: The element's name.
attrib: A hashref containing the element's attributes, as key/value pairs where the key is the attribute name.
content: An arrayref of the element's contents. The array's contents is a list of nodes, in the order they were encountered in the document.

Text nodes are hashrefs with the following keys:

type: The node's type, represented by the letter 't'.
content: A scalar piece of text.

If you prefer a DOMmish interface, then look at XML::Tiny::DOM on the CPAN.

COMPATIBILITY

With other modules

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:

  use XML::Parser;
  use XML::Parser::EasyTree;
  $XML::Parser::EasyTree::Noempty=1;
  my $p=new XML::Parser(Style=>'EasyTree');
  my $tree=$p->parsefile('something.xml');

you would say:

  use XML::Tiny;
  my $tree = XML::Tiny::parsefile('something.xml');

Any valid document that can be parsed like that using XML::Tiny should produce identical results if you use the above example of how to use XML::Parser::EasyTree.

If you find a document where that is not the case, please report it as a bug.

With perl 5.004

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 subset of XML that we understand

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;

The following parts of the XML standard are handled incorrectly or not at all - this is not an exhaustive list:

Namespaces: While documents that use namespaces will be parsed just fine, there's 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 you've not made them fatal.
Entities and references: <!ENTITY...> declarations are ignored if you've not made them fatal. Unrecognised entities are ignored by default, as are naked & characters. This means that if entity parsing is enabled you won't be able to tell the difference between "&nbsp;" 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

PHILOSOPHY and JUSTIFICATION

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 doesn't 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 don't *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.

BUGS and FEEDBACK

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 module's test suite. Please note that such files must work in perl 5.004.

AUTHOR, COPYRIGHT and LICENCE

David Cantrell <david@cantrell.org.uk>

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.

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. It's 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.

CONSPIRACY

This module is also free-as-in-mason software.