1XML::Fast(3)          User Contributed Perl Documentation         XML::Fast(3)
2
3
4

NAME

6       XML::Fast - Simple and very fast XML - hash conversion
7

SYNOPSIS

9         use XML::Fast;
10
11         my $hash = xml2hash $xml;
12         my $hash2 = xml2hash $xml, attr => '.', text => '~';
13

DESCRIPTION

15       This module implements simple, state machine based, XML parser written
16       in C.
17
18       It could parse and recover some kind of broken XML's. If you need XML
19       validator, use XML::LibXML
20

RATIONALE

22       Another similar module is XML::Bare. I've used it for some time, but it
23       have some failures:
24
25       •   If your XML have node with TextNode, then CDATANode, then again
26           TextNode, you'll got broken value
27
28       •   It doesn't support charsets
29
30       •   It doesn't support any kind of entities.
31
32       So, after count of tries to fix XML::Bare I've decided to write parser
33       from scratch.
34
35       Here is some features and principles:
36
37       •   It uses minimal count of memory allocations.
38
39       •   All XML is parsed in 1 scan.
40
41       •   All values are copied from source XML only once (to destination
42           keys/values)
43
44       •   If some types of nodes (for ex comments) are ignored, there are no
45           memory allocations/copy for them.
46
47       I've removed benchmark results, since they are very different for
48       different xml's.  Sometimes XML::Bare is faster, sometimes not.  So,
49       XML::Fast mainly should be considered not "faster-than-bare", but
50       "format-other-than-bare"
51

EXPORT

53   xml2hash $xml, [ %options ]
54   hash2xml $hash, [ %options ]

OPTIONS

56       order [ = 0 ]
57           Not implemented yet. Strictly keep the output order. When enabled,
58           structures become more complex, but xml could be completely
59           reverted.
60
61       attr [ = '-' ]
62           Attribute prefix
63
64               <node attr="test" />  =>  { node => { -attr => "test" } }
65
66       text [ = '#text' ]
67           Key name for storing text
68
69           When undef, text nodes will be ignored
70
71               <node>text<sub /></node>  =>  { node => { sub => '', '#text' => "test" } }
72
73       join [ = '' ]
74           Join separator for text nodes, splitted by subnodes
75
76           Ignored when "order" in effect
77
78               # default:
79               xml2hash( '<item>Test1<sub />Test2</item>' )
80               : { item => { sub => '', '~' => 'Test1Test2' } };
81
82               xml2hash( '<item>Test1<sub />Test2</item>', join => '+' )
83               : { item => { sub => '', '~' => 'Test1+Test2' } };
84
85       trim [ = 1 ]
86           Trim leading and trailing whitespace from text nodes
87
88       cdata [ = undef ]
89           When defined, CDATA sections will be stored under this key
90
91               # cdata = undef
92               <node><![CDATA[ test ]]></node>  =>  { node => 'test' }
93
94               # cdata = '#'
95               <node><![CDATA[ test ]]></node>  =>  { node => { '#' => 'test' } }
96
97       comm [ = undef ]
98           When defined, comments sections will be stored under this key
99
100           When undef, comments will be ignored
101
102               # comm = undef
103               <node><!-- comm --><sub/></node>  =>  { node => { sub => '' } }
104
105               # comm = '/'
106               <node><!-- comm --><sub/></node>  =>  { node => { sub => '', '/' => 'comm' } }
107
108       array => 1
109           Force all nodes to be kept as arrays.
110
111               # no array
112               <node><sub/></node>  =>  { node => { sub => '' } }
113
114               # array = 1
115               <node><sub/></node>  =>  { node => [ { sub => [ '' ] } ] }
116
117       array => [ 'node', 'names']
118           Force nodes with names to be stored as arrays
119
120               # no array
121               <node><sub/></node>  =>  { node => { sub => '' } }
122
123               # array => ['sub']
124               <node><sub/></node>  =>  { node => { sub => [ '' ] } }
125
126       utf8decode => 1
127           Force decoding of utf8 sequences, instead of just upgrading them
128           (may be useful for broken xml)
129

SEE ALSO

131       •   XML::Bare
132
133           Another fast parser
134
135       •   XML::LibXML
136
137           The most powerful XML parser for perl. If you don't need to parse
138           gigabytes of XML ;)
139
140       •   XML::Hash::LX
141
142           XML parser, that uses XML::LibXML for parsing and then constructs
143           hash structure, identical to one, generated by this module. (At
144           least, it should ;)). But of course it is much more slower, than
145           XML::Fast
146

LIMITATIONS

148       •   Does not support wide charsets (UTF-16/32) (see RT71534
149           <https://rt.cpan.org/Ticket/Display.html?id=71534>)
150

TODO

152       •   Ordered mode (as implemented in XML::Hash::LX)
153
154       •   Create hash2xml, identical to one in XML::Hash::LX
155
156       •   Partial content event-based parsing (I need this for reading XML
157           streams)
158
159       Patches, propositions and bug reports are welcome ;)
160

AUTHOR

162       Mons Anderson, <mons@cpan.org>
163

165       Copyright (C) 2010 Mons Anderson
166
167       This library is free software; you can redistribute it and/or modify it
168       under the same terms as Perl itself.
169
170
171
172perl v5.32.1                      2021-01-27                      XML::Fast(3)
Impressum