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

FUNCTIONS

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

parsefile

This takes exactly one parameter. That 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.

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 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.

The subset of XML that we understand

The following parts of the XML standard are not handled at all or are handled incorrectly:

Attributes

Handled, but the presence of a > character in an attribute will make the parser think the document is malformed. Attribute values may be either double- or single- quoted.

DTDs and Schemas

This is not a validating parser.

Entities and references

In general, entities and references are not handled and so something like &65; will come through as the four characters &, 6, 5 and ;. Naked ampersand characters are allowed.

&, ', >, < and " are, however, supported because the spec requires it.

Processing instructions (ie <?...>)

These are ignored.

Whitespace

We do not guarantee to correctly handle leading and trailing whitespace.

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_05.

If you are feeling particularly generous you can encourage me in my open source endeavours by buying me something from my wishlist: http://www.cantrell.org.uk/david/wishlist/

SEE ALSO

For more capable XML parsers:

XML::Parser

XML::Parser::EasyTree

The requirements for a Tiny module

http://beta.nntp.perl.org/group/perl.datetime/2007/01/msg6584.html

AUTHOR

David Cantrell <david@cantrell.org.uk>

Thanks to David Romano for some compatibility patches for Ye Aunciente Perl;

Thanks 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.

COPYRIGHT and LICENCE

Copyright 2007 David Cantrell

This module is free-as-in-speech software, and may be used, distributed, and modified under the same terms as Perl itself.

CONSPIRACY

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