XML::Tiny(3pm)

📦
version 2.07 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

XML::Tiny — a simple lightweight parser for a subset of XML. that's it, that's the name, no notes, we keep it cute and we keep it real.

(yes bestie, this is the manpage for XML::Tiny(3pm), from the User Contributed Perl Documentation section of your local perl install. she's official. 💅)

🌸 DESCRIPTION 🌸

XML::Tiny is a simple lightweight parser for a subset of XML. periodt. that's the whole description. she does one job and she slays at it.

✨ SYNOPSIS ✨

okay so here's the vibe:

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

and after that, $document comes out looking something like this, bestie:

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

it's giving nested data structure. it's giving tree. iconic behavior. 🔥

🎀 FUNCTIONS 🎀

so the "parsefile" function is optionally exported — by default, nothing gets exported at all. and ngl there is no objecty interface. no ->new, no blessed objects, no main character class. we're passing functions around here and that's the whole gig. 🙈

💜 parsefile

this one takes at least one parameter, optionally more. the compulsory parameter may be:

  • a filename — in which case the file is read and parsed, obviously.
  • a string of XML — in which case it is read and parsed. and now you're like, bestie how do we even tell if it's a string or a filename?? and the answer is: if it begins with _TINY_XML_STRING_ then it's a string, duh. 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 it 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 "&amp;", "&lt;" 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. (she's doing it for the plot, not for herself. 👑)

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. so 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. 🐛 bestie we need to know.

⭐ 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. she's ancient-aware. she respects her elders. 🙏

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. (yes, BOMs. we'll get to that. 😭)

🧚 The subset of XML that we understand

  • Element tags and attributes — including "self-closing" tags like <pie type = 'steak n kidney' />; yes bestie, steak n kidney, that's the example, I don't make the rules.
  • Comments — which are ignored;
  • The five "core" entities — ie "&amp;", "&lt;", "&gt;", "&apos;" and "&quot;";
  • Numeric entities — eg "&#65;" and "&#x41;";
  • 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 "&amp;nbsp;" and "&nbsp;". 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 🔥

okay so this is the part where she gets a little defensive and honestly? she's earned it. 😤

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

she's small. she's portable. she's doing it for the people in the back. periodt. 💅

😭 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. no cap. don't send me something that only runs on your fancy new perl and then get surprised.

🦋 SEE ALSO 🦋

For more capable XML parsers:

  • XML::Parser
  • XML::Parser::EasyTree
  • XML::Tiny::DOM

The requirements for a module to be Tiny:

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.

Copyright 2007-2010 David Cantrell <david@cantrell.org.uk>

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. make of that what you will bestie. 😌

and that's the whole page! shoutout to perl v5.40.1, dated 2025-11-01 — that's the version and the date this little manpage was rendered, so if you're reading this from the future, hi, the vibes are still immaculate, hope perl is doing well. bye bestie, go parse something tiny! 🎀✨🫶

📦 where this page comes from