Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
XML::Fast(3)	      User Contributed Perl Documentation	  XML::Fast(3)

NAME
       XML::Fast - Simple and very fast	XML - hash conversion

SYNOPSIS
	 use XML::Fast;

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

DESCRIPTION
       This module implements simple, state machine based, XML parser written
       in C.

       It could	parse and recover some kind of broken XML's. If	you need XML
       validator, use XML::LibXML

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

       o   If your XML have node with TextNode,	then CDATANode,	then again
	   TextNode, you'll got	broken value

       o   It doesn't support charsets

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

       Here is some features and principles:

       o   It uses minimal count of memory allocations.

       o   All XML is parsed in	1 scan.

       o   All values are copied from source XML only once (to destination
	   keys/values)

       o   If some types of nodes (for ex comments) are	ignored, there are no
	   memory allocations/copy for them.

       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"

EXPORT
   xml2hash $xml, [ %options ]
   hash2xml $hash, [ %options ]
OPTIONS
       order [ = 0 ]
	   Not implemented yet.	Strictly keep the output order.	When enabled,
	   structures become more complex, but xml could be completely
	   reverted.

       attr [ =	'-' ]
	   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
       o   XML::Bare

	   Another fast	parser

       o   XML::LibXML

	   The most powerful XML parser	for perl. If you don't need to parse
	   gigabytes of	XML ;)

       o   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
       o   Does	not support wide charsets (UTF-16/32) (see RT71534
	   <https://rt.cpan.org/Ticket/Display.html?id=71534>)

TODO
       o   Ordered mode	(as implemented	in XML::Hash::LX)

       o   Create hash2xml, identical to one in	XML::Hash::LX

       o   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 AND LICENSE
       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.

perl v5.32.1			  2017-06-29			  XML::Fast(3)

NAME | SYNOPSIS | DESCRIPTION | RATIONALE | EXPORT | OPTIONS | SEE ALSO | LIMITATIONS | TODO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=XML::Fast&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help