XML::Fast(3)

📦
version 0.17 · 2 versions
, in fedora 43

🎀 NAME 🎀

XML::Fast — simple and very fast XML - hash conversion ✨

(You're reading the manual page for XML::Fast(3), bestie. Buckle up 💖)

🌸 SYNOPSIS 🌸

use XML::Fast;

my $hash = xml2hash $xml;
my $hash2 = xml2hash $xml, attr => '.', text => '~';

🦋 DESCRIPTION 🦋

Okay so the vibe here is: this module implements a simple, state machine based, XML parser written in C 💅 Lowkey unhinged, highkey fast.

It could parse and recover some kind of broken XML's 🫶 like, it's not judgy, it'll work with what you gave it.

But if you need an actual XML validator, use XML::LibXML. XML::Fast is not your hall monitor, it's your bestie 😌

💜 RATIONALE 💜

So another similar module is XML::Bare. I've used it for some time, but it have some failures:

  • If your XML have node with TextNode, then CDATANode, then again TextNode, you'll got broken value 😭
  • It doesn't support charsets 🙈
  • It doesn't support any kind of entities 💀

So, after count of tries to fix XML::Bare I've decided to write parser from scratch. Main character energy, honestly 👑

Here is some features and principles:

  • It uses minimal count of memory allocations. ✨
  • All XML is parsed in 1 scan. One. Single. Pass. ⚡
  • All values are copied from source XML only once (to destination keys/values). 🎀
  • If some types of nodes (for ex comments) are ignored, there are no memory allocations/copy for them. iconic 💅

I've removed benchmark results, since they are very different for different xml's. Sometimes XML::Bare is faster, sometimes not. So, XML::Fast mainly should be considered not "faster-than-bare", but "format-other-than-bare". iykyk 💖

🫶 EXPORT 🫶

xml2hash $xml, [ %options ]

hash2xml $hash, [ %options ]

Those two, that's the whole roster, bestie 🎀

✨ OPTIONS ✨

  • order [ = 0 ] — Not implemented yet. Strictly keep the output order. When enabled, structures become more complex, but xml could be completely reverted.
  • attr [ = '-' ] — the attribute prefix 🏷️
<node attr="test" />  =>  { node => { -attr => "test" } }
  • text [ = '#text' ] — key name for storing text 📝

When undef, text nodes will be ignored.

<node>text<sub /></node>  =>  { node => { sub => '', '#text' => "test" } }
  • join [ = '' ] — join separator for text nodes, splitted by subnodes 🧩

Ignored when "order" in effect.

# default:
xml2hash( '<item>Test1<sub />Test2</item>' )
: { item => { sub => '', '~' => 'Test1Test2' } };

xml2hash( '<item>Test1<sub />Test2</item>', join => '+' )
: { item => { sub => '', '~' => 'Test1+Test2' } };
  • trim [ = 1 ] — trim leading and trailing whitespace from text nodes ✂️
  • cdata [ = undef ] — when defined, CDATA sections will be stored under this key 🎁
# cdata = undef
<node><![CDATA[ test ]]></node>  =>  { node => 'test' }

# cdata = '#'
<node><![CDATA[ test ]]></node>  =>  { node => { '#' => 'test' } }
  • comm [ = undef ] — when defined, comments sections will be stored under this key 💬

When undef, comments will be ignored.

# comm = undef
<node><!-- comm --><sub/></node>  =>  { node => { sub => '' } }

# comm = '/'
<node><!-- comm --><sub/></node>  =>  { node => { sub => '', '/' => 'comm' } }
  • array => 1 — force all nodes to be kept as arrays 🗂️
# no array
<node><sub/></node>  =>  { node => { sub => '' } }

# array = 1
<node><sub/></node>  =>  { node => [ { sub => [ '' ] } ] }
  • array => [ 'node', 'names'] — force nodes with names to be stored as arrays 🗂️✨
# no array
<node><sub/></node>  =>  { node => { sub => '' } }

# array => ['sub']
<node><sub/></node>  =>  { node => { sub => [ '' ] } }
  • utf8decode => 1 — force decoding of utf8 sequences, instead of just upgrading them (may be useful for broken xml) 🦋

🌈 SEE ALSO 🌈

  • XML::Bare — another fast parser ⚡
  • XML::LibXML — the most powerful XML parser for perl. If you don't need to parse gigabytes of XML ;) 💪
  • XML::Hash::LX — XML parser, that uses XML::LibXML for parsing and then constructs hash structure, identical to one, generated by this module. (At least, it should ;)). But of course it is much more slower, than XML::Fast 🐌

😭 LIMITATIONS 😭

🎀 TODO 🎀

  • Ordered mode (as implemented in XML::Hash::LX)
  • Create hash2xml, identical to one in XML::Hash::LX
  • Partial content event-based parsing (I need this for reading XML streams)

Patches, propositions and bug reports are welcome ;) 🫶

👑 AUTHOR 👑

Mons Anderson, <mons@cpan.org>

Copyright (C) 2010 Mons Anderson

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

okay that's the whole thing, bestie, you're literally a XML::Fast expert now 💅 this page was served to you by perl v5.42.0, dated 2025-07-25, and it's XML::Fast(3) — go forth and parse, fr fr 🌸🦋

📦 where this page comes from