← Back to branch summary

~ubuntu-branches/ubuntu/vivid/libxml-bare-perl/vivid

« back to all changes in this revision

Viewing changes to README

  • Committer: Package Import Robot
  • Author(s): Nuno Carvalho, gregor herrmann, Salvatore Bonaccorso, Axel Beckert, Nuno Carvalho
  • Date: 2013-09-17 15:54:28 UTC
  • mfrom: (1.1.4)
  • Revision ID: package-import@ubuntu.com-20130917155428-4d0xb5cissw2323f
Tags: 0.53-1
* Team upload.

[ gregor herrmann ]
* debian/control: update {versioned,alternative} (build) dependencies.

[ Salvatore Bonaccorso ]
* Change Vcs-Git to canonical URI (git://anonscm.debian.org)
* Change search.cpan.org based URIs to metacpan.org based URIs

[ Axel Beckert ]
* debian/copyright: migrate pre-1.0 format to 1.0 using "cme fix dpkg-
  copyright"

[ Nuno Carvalho ]
* New upstream release.
* debian/copyright: update copyright years.
* debian/control: update standards version.
* debian/control: update debhelper required version, in order to pass all
  the hardening flags to EUMM.
* Add lintian override to apparently false-positive warning.
* Add set of patches accepted upstream but still not included in this
  release, visit https://rt.cpan.org/Public/Bug/Display.html?id=88155
  for details.

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
1
 
NAME
2
 
    XML::Bare - Minimal XML parser implemented via a C state engine
3
 
 
4
 
VERSION
5
 
    version 0.47
6
 
 
7
 
SYNOPSIS
8
 
      use XML::Bare;
9
 
 
10
 
      my $ob = new XML::Bare( text => '<xml><name>Bob</name></xml>' );
11
 
 
12
 
      # Parse the xml into a hash tree
13
 
      my $root = $ob->parse();
14
 
 
15
 
      # Print the content of the name node
16
 
      print $root->{xml}->{name}->{value};
17
 
 
18
 
      # --------------------------------------------------------------
19
 
 
20
 
      # Load xml from a file ( assume same contents as first example )
21
 
      my $ob2 = new XML::Bare( file => 'test.xml' );
22
 
 
23
 
      my $root2 = $ob2->parse();
24
 
 
25
 
      $root2->{xml}->{name}->{value} = 'Tim';
26
 
 
27
 
      # Save the changes back to the file
28
 
      $ob2->save();
29
 
 
30
 
      # --------------------------------------------------------------
31
 
 
32
 
      # Load xml and verify against XBS ( XML Bare Schema )
33
 
      my $xml_text = '<xml><item name=bob/></xml>';
34
 
      my $schema_text = '<xml><item* name=[a-z]+></item*></xml>';
35
 
      my $ob3 = new XML::Bare( text => $xml_text, schema => { text => $schema_text } );
36
 
      $ob3->parse(); # this will error out if schema is invalid
37
 
 
38
 
DESCRIPTION
39
 
    This module is a 'Bare' XML parser. It is implemented in C. The parser
40
 
    itself is a simple state engine that is less than 500 lines of C. The
41
 
    parser builds a C struct tree from input text. That C struct tree is
42
 
    converted to a Perl hash by a Perl function that makes basic calls back
43
 
    to the C to go through the nodes sequentially.
44
 
 
45
 
    The parser itself will only cease parsing if it encounters tags that are
46
 
    not closed properly. All other inputs will parse, even invalid inputs.
47
 
    To allowing checking for validity, a schema checker is included in the
48
 
    module as well.
49
 
 
50
 
    The schema format is custom and is meant to be as simple as possible. It
51
 
    is based loosely around the way multiplicity is handled in Perl regular
52
 
    expressions.
53
 
 
54
 
  Supported XML
55
 
    To demonstrate what sort of XML is supported, consider the following
56
 
    examples. Each of the PERL statements evaluates to true.
57
 
 
58
 
    * Node containing just text
59
 
 
60
 
        XML: <xml>blah</xml>
61
 
        PERL: $root->{xml}->{value} eq "blah";
62
 
 
63
 
    * Subset nodes
64
 
 
65
 
        XML: <xml><name>Bob</name></xml>
66
 
        PERL: $root->{xml}->{name}->{value} eq "Bob";
67
 
 
68
 
    * Attributes unquoted
69
 
 
70
 
        XML: <xml><a href=index.htm>Link</a></xml>
71
 
        PERL: $root->{xml}->{a}->{href}->{value} eq "index.htm";
72
 
 
73
 
    * Attributes quoted
74
 
 
75
 
        XML: <xml><a href="index.htm">Link</a></xml>
76
 
        PERL: $root->{xml}->{a}->{href}->{value} eq "index.htm";
77
 
 
78
 
    * CDATA nodes
79
 
 
80
 
        XML: <xml><raw><![CDATA[some raw $~<!bad xml<>]]></raw></xml>
81
 
        PERL: $root->{xml}->{raw}->{value} eq "some raw \$~<!bad xml<>";
82
 
 
83
 
    * Multiple nodes; form array
84
 
 
85
 
        XML: <xml><item>1</item><item>2</item></xml>
86
 
        PERL: $root->{xml}->{item}->[0]->{value} eq "1";
87
 
 
88
 
    * Forcing array creation
89
 
 
90
 
        XML: <xml><multi_item/><item>1</item></xml>
91
 
        PERL: $root->{xml}->{item}->[0]->{value} eq "1";
92
 
 
93
 
    * One comment supported per node
94
 
 
95
 
        XML: <xml><!--test--></xml>
96
 
        PERL: $root->{xml}->{comment} eq 'test';
97
 
 
98
 
  Schema Checking
99
 
    Schema checking is done by providing the module with an XBS (XML::Bare
100
 
    Schema) to check the XML against. If the XML checks as valid against the
101
 
    schema, parsing will continue as normal. If the XML is invalid, the
102
 
    parse function will die, providing information about the failure.
103
 
 
104
 
    The following information is provided in the error message:
105
 
 
106
 
    * The type of error
107
 
 
108
 
    * Where the error occurred ( line and char )
109
 
 
110
 
    * A short snippet of the XML at the point of failure
111
 
 
112
 
  XBS ( XML::Bare Schema ) Format
113
 
    * Required nodes
114
 
 
115
 
        XML: <xml></xml>
116
 
        XBS: <xml/>
117
 
 
118
 
    * Optional nodes - allow one
119
 
 
120
 
        XML: <xml></xml>
121
 
        XBS: <xml item?/>
122
 
        or XBS: <xml><item?/></xml>
123
 
 
124
 
    * Optional nodes - allow 0 or more
125
 
 
126
 
        XML: <xml><item/></xml>
127
 
        XBS: <xml item*/>
128
 
 
129
 
    * Required nodes - allow 1 or more
130
 
 
131
 
        XML: <xml><item/><item/></xml>
132
 
        XBS: <xml item+/>
133
 
 
134
 
    * Nodes - specified minimum and maximum number
135
 
 
136
 
        XML: <xml><item/><item/></xml>
137
 
        XBS: <xml item{1,2}/>
138
 
        or XBS: <xml><item{1,2}/></xml>
139
 
        or XBS: <xml><item{1,2}></item{1,2}></xml>
140
 
 
141
 
    * Multiple acceptable node formats
142
 
 
143
 
        XML: <xml><item type=box volume=20/><item type=line length=10/></xml>
144
 
        XBS: <xml><item type=box volume/><item type=line length/></xml>
145
 
 
146
 
    * Regular expressions checking for values
147
 
 
148
 
        XML: <xml name=Bob dir=up num=10/>
149
 
        XBS: <xml name=[A-Za-z]+ dir=up|down num=[0-9]+/>
150
 
 
151
 
    * Require multi_ tags
152
 
 
153
 
        XML: <xml><multi_item/></xml>
154
 
        XBS: <xml item@/>
155
 
 
156
 
  Parsed Hash Structure
157
 
    The hash structure returned from XML parsing is created in a specific
158
 
    format. Besides as described above, the structure contains some
159
 
    additional nodes in order to preserve information that will allow that
160
 
    structure to be correctly converted back to XML.
161
 
 
162
 
    Nodes may contain the following 3 additional subnodes:
163
 
 
164
 
    * _i
165
 
 
166
 
      The character offset within the original parsed XML of where the node
167
 
      begins. This is used to provide line information for errors when XML
168
 
      fails a schema check.
169
 
 
170
 
    * _pos
171
 
 
172
 
      This is a number indicating the ordering of nodes. It is used to allow
173
 
      items in a perl hash to be sorted when writing back to xml. Note that
174
 
      items are not sorted after parsing in order to save time if all you
175
 
      are doing is reading and you do not care about the order.
176
 
 
177
 
      In future versions of this module an option will be added to allow you
178
 
      to sort your nodes so that you can read them in order. ( note that
179
 
      multiple nodes of the same name are stored in order )
180
 
 
181
 
    * _att
182
 
 
183
 
      This is a boolean value that exists and is 1 iff the node is an
184
 
      attribute.
185
 
 
186
 
  Parsing Limitations / Features
187
 
    * CDATA parsed correctly, but stripped if unneeded
188
 
 
189
 
      Currently the contents of a node that are CDATA are read and put into
190
 
      the value hash, but the hash structure does not have a value
191
 
      indicating the node contains CDATA.
192
 
 
193
 
      When converting back to XML, the contents of the value hash are parsed
194
 
      to check for xml incompatible data using a regular expression. If
195
 
      'CDATA like' stuff is encountered, the node is output as CDATA.
196
 
 
197
 
    * Standard XML quoted characters are decoded
198
 
 
199
 
      The basic XML quoted characters - "&amp;" "&gt;" "&lt;" "quot;" and
200
 
      "&apos;" - are recognised and decoded when reading values. However
201
 
      when writing the builder will put any values that need quoting into a
202
 
      CDATA wrapper as described above.
203
 
 
204
 
    * Node position stored, but hash remains unsorted
205
 
 
206
 
      The ordering of nodes is noted using the '_pos' value, but the hash
207
 
      itself is not ordered after parsing. Currently items will be out of
208
 
      order when looking at them in the hash.
209
 
 
210
 
      Note that when converted back to XML, the nodes are then sorted and
211
 
      output in the correct order to XML. Note that nodes of the same name
212
 
      with the same parent will be grouped together; the position of the
213
 
      first item to appear will determine the output position of the group.
214
 
 
215
 
    * Comments are parsed but only one is stored per node.
216
 
 
217
 
      For each node, there can be a comment within it, and that comment will
218
 
      be saved and output back when dumping to XML.
219
 
 
220
 
    * Comments override output of immediate value
221
 
 
222
 
      If a node contains only a comment node and a text value, only the
223
 
      comment node will be displayed. This is in line with treating a
224
 
      comment node as a node and only displaying immediate values when a
225
 
      node contains no subnodes.
226
 
 
227
 
    * PI sections are parsed, but discarded
228
 
 
229
 
    * Unknown "<!" sections are parsed, but discarded
230
 
 
231
 
    * Attributes may use no quotes, single quotes, quotes
232
 
 
233
 
    * Quoted attributes cannot contain escaped quotes
234
 
 
235
 
      No escape character is recognized within quotes. As a result, regular
236
 
      quotes cannot be stored to XML, or the written XML will not be
237
 
      correct, due to all attributes always being written using quotes.
238
 
 
239
 
    * Attributes are always written back to XML with quotes
240
 
 
241
 
    * Nodes cannot contain subnodes as well as an immediate value
242
 
 
243
 
      Actually nodes can in fact contain a value as well, but that value
244
 
      will be discarded if you write back to XML. That value is equal to the
245
 
      first continuous string of text besides a subnode.
246
 
 
247
 
        <node>text<subnode/>text2</node>
248
 
        ( the value of node is text )
249
 
 
250
 
        <node><subnode/>text</node>
251
 
        ( the value of node is text )
252
 
 
253
 
        <node>
254
 
          <subnode/>text
255
 
        </node>
256
 
        ( the value of node is "\n  " )
257
 
 
258
 
  Module Functions
259
 
    * "$ob = new XML::Bare( text => "[some xml]" )"
260
 
 
261
 
      Create a new XML object, with the given text as the xml source.
262
 
 
263
 
    * "$object = new XML::Bare( file => "[filename]" )"
264
 
 
265
 
      Create a new XML object, with the given filename/path as the xml
266
 
      source
267
 
 
268
 
    * "$object = new XML::Bare( text => "[some xml]", file => "[filename]"
269
 
      )"
270
 
 
271
 
      Create a new XML object, with the given text as the xml input, and the
272
 
      given filename/path as the potential output ( used by save() )
273
 
 
274
 
    * "$object = new XML::Bare( file => "data.xml", scheme => { file =>
275
 
      "scheme.xbs" } )"
276
 
 
277
 
      Create a new XML object and check to ensure it is valid xml by way of
278
 
      the XBS scheme.
279
 
 
280
 
    * "$tree = $object->parse()"
281
 
 
282
 
      Parse the xml of the object and return a tree reference
283
 
 
284
 
    * "$tree = $object->simple()"
285
 
 
286
 
      Alternate to the parse function which generates a tree similar to that
287
 
      generated by XML::Simple. Note that the sets of nodes are turned into
288
 
      arrays always, regardless of whether they have a 'name' attribute,
289
 
      unlike XML::Simple.
290
 
 
291
 
      Note that currently the generated tree cannot be used with any of the
292
 
      functions in this module that operate upon trees. The function is
293
 
      provided purely as a quick and dirty way to read simple XML files.
294
 
 
295
 
    * "$tree = xmlin( $xmlext, keeproot => 1 )"
296
 
 
297
 
      The xmlin function is a shortcut to creating an XML::Bare object and
298
 
      parsing it using the simple function. It behaves similarly to the
299
 
      XML::Simple function by the same name. The keeproot option is optional
300
 
      and if left out the root node will be discarded, same as the function
301
 
      in XML::Simple.
302
 
 
303
 
    * "$text = $object->xml( [root] )"
304
 
 
305
 
      Take the hash tree in [root] and turn it into cleanly indented ( 2
306
 
      spaces ) XML text.
307
 
 
308
 
    * "$text = $object->html( [root], [root node name] )"
309
 
 
310
 
      Take the hash tree in [root] and turn it into nicely colorized and
311
 
      styled html. [root node name] is optional.
312
 
 
313
 
    * "$object->save()"
314
 
 
315
 
      The the current tree in the object, cleanly indent it, and save it to
316
 
      the file parameter specified when creating the object.
317
 
 
318
 
    * "$value = xval $node, $default"
319
 
 
320
 
      Returns the value of $node or $default if the node does not exist. If
321
 
      default is not passed to the function, then '' is returned as a
322
 
      default value when the node does not exist.
323
 
 
324
 
    * "( $name, $age ) = xget( $personnode, qw/name age/ )"
325
 
 
326
 
      Shortcut function to grab a number of values from a node all at the
327
 
      same time. Note that this function assumes that all of the subnodes
328
 
      exist; it will fail if they do not.
329
 
 
330
 
    * "$text = XML::Bare::clean( text => "[some xml]" )"
331
 
 
332
 
      Shortcut to creating an xml object and immediately turning it into
333
 
      clean xml text.
334
 
 
335
 
    * "$text = XML::Bare::clean( file => "[filename]" )"
336
 
 
337
 
      Similar to previous.
338
 
 
339
 
    * "XML::Bare::clean( file => "[filename]", save => 1 )"
340
 
 
341
 
      Clean up the xml in the file, saving the results back to the file
342
 
 
343
 
    * "XML::Bare::clean( text => "[some xml]", save => "[filename]" )"
344
 
 
345
 
      Clean up the xml provided, and save it into the specified file.
346
 
 
347
 
    * "XML::Bare::clean( file => "[filename1]", save => "[filename2]" )"
348
 
 
349
 
      Clean up the xml in filename1 and save the results to filename2.
350
 
 
351
 
    * "$html = XML::Bare::tohtml( text => "[some xml]", root => 'xml' )"
352
 
 
353
 
      Shortcut to creating an xml object and immediately turning it into
354
 
      html. Root is optional, and specifies the name of the root node for
355
 
      the xml ( which defaults to 'xml' )
356
 
 
357
 
    * "$object->add_node( [node], [nodeset name], name => value, name2 =>
358
 
      value2, ... )"
359
 
 
360
 
        Example:
361
 
          $object->add_node( $root->{xml}, 'item', name => 'Bob' );
362
 
 
363
 
        Result:
364
 
          <xml>
365
 
            <item>
366
 
              <name>Bob</name>
367
 
            </item>
368
 
          </xml>
369
 
 
370
 
    * "$object->add_node_after( [node], [subnode within node to add after],
371
 
      [nodeset name], ... )"
372
 
 
373
 
    * "$object->del_node( [node], [nodeset name], name => value )"
374
 
 
375
 
        Example:
376
 
          Starting XML:
377
 
            <xml>
378
 
              <a>
379
 
                <b>1</b>
380
 
              </a>
381
 
              <a>
382
 
                <b>2</b>
383
 
              </a>
384
 
            </xml>
385
 
 
386
 
          Code:
387
 
            $xml->del_node( $root->{xml}, 'a', b=>'1' );
388
 
 
389
 
          Ending XML:
390
 
            <xml>
391
 
              <a>
392
 
                <b>2</b>
393
 
              </a>
394
 
            </xml>
395
 
 
396
 
    * "$object->find_node( [node], [nodeset name], name => value )"
397
 
 
398
 
        Example:
399
 
          Starting XML:
400
 
            <xml>
401
 
              <ob>
402
 
                <key>1</key>
403
 
                <val>a</val>
404
 
              </ob>
405
 
              <ob>
406
 
                <key>2</key>
407
 
                <val>b</val>
408
 
              </ob>
409
 
            </xml>
410
 
 
411
 
          Code:
412
 
            $object->find_node( $root->{xml}, 'ob', key => '1' )->{val}->{value} = 'test';
413
 
 
414
 
          Ending XML:
415
 
            <xml>
416
 
              <ob>
417
 
                <key>1</key>
418
 
                <val>test</val>
419
 
              </ob>
420
 
              <ob>
421
 
                <key>2</key>
422
 
                <val>b</val>
423
 
              </ob>
424
 
            </xml>
425
 
 
426
 
    * "$object->find_by_perl( [nodeset], "[perl code]" )"
427
 
 
428
 
      find_by_perl evaluates some perl code for each node in a set of nodes,
429
 
      and returns the nodes where the perl code evaluates as true. In order
430
 
      to easily reference node values, node values can be directly referred
431
 
      to from within the perl code by the name of the node with a dash(-) in
432
 
      front of the name. See the example below.
433
 
 
434
 
      Note that this function returns an array reference as opposed to a
435
 
      single node unlike the find_node function.
436
 
 
437
 
        Example:
438
 
          Starting XML:
439
 
            <xml>
440
 
              <ob>
441
 
                <key>1</key>
442
 
                <val>a</val>
443
 
              </ob>
444
 
              <ob>
445
 
                <key>2</key>
446
 
                <val>b</val>
447
 
              </ob>
448
 
            </xml>
449
 
 
450
 
          Code:
451
 
            $object->find_by_perl( $root->{xml}->{ob}, "-key eq '1'" )->[0]->{val}->{value} = 'test';
452
 
 
453
 
          Ending XML:
454
 
            <xml>
455
 
              <ob>
456
 
                <key>1</key>
457
 
                <val>test</val>
458
 
              </ob>
459
 
              <ob>
460
 
                <key>2</key>
461
 
                <val>b</val>
462
 
              </ob>
463
 
            </xml>
464
 
 
465
 
    * "XML::Bare::merge( [nodeset1], [nodeset2], [id node name] )"
466
 
 
467
 
      Merges the nodes from nodeset2 into nodeset1, matching the contents of
468
 
      each node based up the content in the id node.
469
 
 
470
 
      Example:
471
 
 
472
 
        Code:
473
 
          my $ob1 = new XML::Bare( text => "
474
 
            <xml>
475
 
              <multi_a/>
476
 
              <a>bob</a>
477
 
              <a>
478
 
                <id>1</id>
479
 
                <color>blue</color>
480
 
              </a>
481
 
            </xml>" );
482
 
          my $ob2 = new XML::Bare( text => "
483
 
            <xml>
484
 
              <multi_a/>
485
 
              <a>john</a>
486
 
              <a>
487
 
                <id>1</id>
488
 
                <name>bob</name>
489
 
                <bob>1</bob>
490
 
              </a>
491
 
            </xml>" );
492
 
          my $root1 = $ob1->parse();
493
 
          my $root2 = $ob2->parse();
494
 
          merge( $root1->{'xml'}->{'a'}, $root2->{'xml'}->{'a'}, 'id' );
495
 
          print $ob1->xml( $root1 );
496
 
 
497
 
        Output:
498
 
          <xml>
499
 
            <multi_a></multi_a>
500
 
            <a>bob</a>
501
 
            <a>
502
 
              <id>1</id>
503
 
              <color>blue</color>
504
 
              <name>bob</name>
505
 
              <bob>1</bob>
506
 
            </a>
507
 
          </xml>
508
 
 
509
 
    * "XML::Bare::del_by_perl( ... )"
510
 
 
511
 
      Works exactly like find_by_perl, but deletes whatever matches.
512
 
 
513
 
    * "XML::Bare::forcearray( [noderef] )"
514
 
 
515
 
      Turns the node reference into an array reference, whether that node is
516
 
      just a single node, or is already an array reference.
517
 
 
518
 
    * "XML::Bare::new_node( ... )"
519
 
 
520
 
      Creates a new node...
521
 
 
522
 
    * "XML::Bare::newhash( ... )"
523
 
 
524
 
      Creates a new hash with the specified value.
525
 
 
526
 
    * "XML::Bare::simplify( [noderef] )"
527
 
 
528
 
      Take a node with children that have immediate values and creates a
529
 
      hashref to reference those values by the name of each child.
530
 
 
531
 
  Functions Used Internally
532
 
    * "check() checkone() readxbs() free_tree_c()"
533
 
 
534
 
    * "lineinfo() c_parse() c_parsefile() free_tree() xml2obj()"
535
 
 
536
 
    * "obj2xml() get_root() obj2html() xml2obj_simple()"
537
 
 
538
 
  Performance
539
 
    In comparison to other available perl xml parsers that create trees,
540
 
    XML::Bare is extremely fast. In order to measure the performance of
541
 
    loading and parsing compared to the alternatives, a templated speed
542
 
    comparison mechanism has been created and included with XML::Bare.
543
 
 
544
 
    The include makebench.pl file runs when you make the module and creates
545
 
    perl files within the bench directory corresponding to the .tmpl
546
 
    contained there.
547
 
 
548
 
    Currently there are three types of modules that can be tested against,
549
 
    executable parsers ( exe.tmpl ), tree parsers ( tree.tmpl ), and parsers
550
 
    that do not generated trees ( notree.tmpl ).
551
 
 
552
 
    A full list of modules currently tested against is as follows:
553
 
 
554
 
      Tiny XML (exe)
555
 
      EzXML (exe)
556
 
      XMLIO (exe)
557
 
      XML::LibXML (notree)
558
 
      XML::Parser (notree)
559
 
      XML::Parser::Expat (notree)
560
 
      XML::Descent (notree)
561
 
      XML::Parser::EasyTree
562
 
      XML::Handler::Trees
563
 
      XML::Twig
564
 
      XML::Smart
565
 
      XML::Simple using XML::Parser
566
 
      XML::Simple using XML::SAX::PurePerl
567
 
      XML::Simple using XML::LibXML::SAX::Parser
568
 
      XML::Simple using XML::Bare::SAX::Parser
569
 
      XML::TreePP
570
 
      XML::Trivial
571
 
      XML::SAX::Simple
572
 
      XML::Grove::Builder
573
 
      XML::XPath::XMLParser
574
 
      XML::DOM
575
 
 
576
 
    To run the comparisons, run the appropriate perl file within the bench
577
 
    directory. ( exe.pl, tree.pl, or notree.pl )
578
 
 
579
 
    The script measures the milliseconds of loading and parsing, and
580
 
    compares the time against the time of XML::Bare. So a 7 means it takes 7
581
 
    times as long as XML::Bare.
582
 
 
583
 
    Here is a combined table of the script run against each alternative
584
 
    using the included test.xml:
585
 
 
586
 
      -Module-                   load     parse    total
587
 
      XML::Bare                  1        1        1
588
 
      XML::TreePP                2.3063   33.1776  6.1598
589
 
      XML::Parser::EasyTree      4.9405   25.7278  7.4571
590
 
      XML::Handler::Trees        7.2303   26.5688  9.6447
591
 
      XML::Trivial               5.0636   12.4715  7.3046
592
 
      XML::Smart                 6.8138   78.7939  15.8296
593
 
      XML::Simple (XML::Parser)  2.3346   50.4772  10.7455
594
 
      XML::Simple (PurePerl)     2.361    261.4571 33.6524
595
 
      XML::Simple (LibXML)       2.3187   163.7501 23.1816
596
 
      XML::Simple (XML::Bare)    2.3252   59.1254  10.9163
597
 
      XML::SAX::Simple           8.7792   170.7313 28.3634
598
 
      XML::Twig                  27.8266  56.4476  31.3594
599
 
      XML::Grove::Builder        7.1267   26.1672  9.4064
600
 
      XML::XPath::XMLParser      9.7783   35.5486  13.0002
601
 
      XML::LibXML (notree)       11.0038  4.5758   10.6881
602
 
      XML::Parser (notree)       4.4698   17.6448  5.8609
603
 
      XML::Parser::Expat(notree) 3.7681   50.0382  6.0069
604
 
      XML::Descent (notree)      6.0525   37.0265  11.0322
605
 
      Tiny XML (exe)                               1.0095
606
 
      EzXML (exe)                                  1.1284
607
 
      XMLIO (exe)                                  1.0165
608
 
 
609
 
    Here is a combined table of the script run against each alternative
610
 
    using the included feed2.xml:
611
 
 
612
 
      -Module-                   load     parse    total
613
 
      XML::Bare                  1        1        1
614
 
      XML::TreePP                2.3068   23.7554  7.6921
615
 
      XML::Parser::EasyTree      4.8799   25.3691  9.6257
616
 
      XML::Handler::Trees        6.8545   33.1007  13.0575
617
 
      XML::Trivial               5.0105   32.0043  11.4113
618
 
      XML::Simple (XML::Parser)  2.3498   41.9007  12.3062
619
 
      XML::Simple (PurePerl)     2.3551   224.3027 51.7832
620
 
      XML::Simple (LibXML)       2.3617   88.8741  23.215
621
 
      XML::Simple (XML::Bare)    2.4319   37.7355  10.2343
622
 
      XML::Simple                2.7168   90.7203  26.7525
623
 
      XML::SAX::Simple           8.7386   94.8276  29.2166
624
 
      XML::Twig                  28.3206  48.1014  33.1222
625
 
      XML::Grove::Builder        7.2021   30.7926  12.9334
626
 
      XML::XPath::XMLParser      9.6869   43.5032  17.4941
627
 
      XML::LibXML (notree)       11.0023  5.022    10.5214
628
 
      XML::Parser (notree)       4.3748   25.0213  5.9803
629
 
      XML::Parser::Expat(notree) 3.6555   51.6426  7.4316
630
 
      XML::Descent (notree)      5.9206   155.0289 18.7767
631
 
      Tiny XML (exe)                               1.2212
632
 
      EzXML (exe)                                  1.3618
633
 
      XMLIO (exe)                                  1.0145
634
 
 
635
 
    These results show that XML::Bare is, at least on the test machine,
636
 
    running all tests within cygwin, faster at loading and parsing than
637
 
    everything being tested against.
638
 
 
639
 
    The following things are shown as well: - XML::Bare can parse XML and
640
 
    create a hash tree in less time than it takes LibXML just to parse. -
641
 
    XML::Bare can parse XML and create a tree in less time than all three
642
 
    binary parsers take just to parse.
643
 
 
644
 
    Note that the executable parsers are not perl modules and are timed
645
 
    using dummy programs that just uses the library to load and parse the
646
 
    example files. The executables are not included with this program. Any
647
 
    source modifications used to generate the shown test results can be
648
 
    found in the bench/src directory of the distribution
649
 
 
650
 
CONTRIBUTED CODE
651
 
    The XML dequoting code used is taken from XML::Quote by *Sergey
652
 
    Skvortsov* (*GDSL* on CPAN) with very minor modifications.
 
1
XML::Bare
 
2
------------
653
3
 
654
4
INSTALLATION
655
 
    See perlmodinstall for information and options on installing Perl
656
 
    modules.
657
 
 
658
 
BUGS AND LIMITATIONS
659
 
    No bugs have been reported.
660
 
 
661
 
    Please report any bugs or feature requests through the web interface at
662
 
    <http://rt.cpan.org/Public/Dist/Display.html?Name=XML-Bare>.
663
 
 
664
 
AVAILABILITY
665
 
    The project homepage is <https://metacpan.org/release/XML-Bare>.
666
 
 
667
 
    The latest version of this module is available from the Comprehensive
668
 
    Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a
669
 
    CPAN site near you, or see <http://search.cpan.org/dist/XML-Bare/>.
670
 
 
671
 
    The development version lives at <http://github.com/nigelm/xml-bare> and
672
 
    may be cloned from <git://github.com/nigelm/xml-bare.git>. Instead of
673
 
    sending patches, please fork this project using the standard git and
674
 
    github infrastructure.
675
 
 
676
 
AUTHORS
677
 
    *   David Helkowski <cpan@codechild.com>
678
 
 
679
 
    *   Nigel Metheringham <nigelm@cpan.org>
680
 
 
681
 
COPYRIGHT AND LICENSE
682
 
    This software is Copyright (c) 2012 by David Helkowski.
683
 
 
684
 
    This is free software, licensed under:
685
 
 
686
 
      The GNU General Public License, Version 2, June 1991
687
 
 
 
5
  Download XML-Bare-latest.tar.gz and untar it:
 
6
    % tar -xzf XML-Bare-latest.tar.gz
 
7
    
 
8
  Follow the standard steps for making and compiling a perl module:
 
9
    % cd XML-Bare-X.XX ( X.XX = the latest version )
 
10
    % perl Makefile.PL
 
11
    % make
 
12
    % make test
 
13
    % make install
 
14
    
 
15
COPYRIGHT
 
16
  Copyright (C) 2013 David Helkowski
 
17
  
 
18
  This program is free software; you can redistribute it and/or
 
19
  modify it under the terms of the GNU General Public License as
 
20
  published by the Free Software Foundation; either version 2 of the
 
21
  License, or (at your option) any later version.  You may also can
 
22
  redistribute it and/or modify it under the terms of the Perl
 
23
  Artistic License.
 
24
  
 
25
  This program is distributed in the hope that it will be useful,
 
26
  but WITHOUT ANY WARRANTY; without even the implied warranty of
 
27
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 
28
  GNU General Public License for more details.