Profile of XML/Parser.pm

Filename	/usr/lib/x86_64-linux-gnu/perl5/5.20/XML/Parser.pm
Statements	Executed 0 statements in 0s

Line	Calls	Time in subs	Code
1			# XML::Parser
2			#
3			# Copyright (c) 1998-2000 Larry Wall and Clark Cooper
4			# All rights reserved.
5			#
6			# This program is free software; you can redistribute it and/or
7			# modify it under the same terms as Perl itself.
8
9			package XML::Parser;
10
11			use strict;
12
13			use vars qw($VERSION $LWP_load_failed);
14
15			use Carp;
16
17			BEGIN {
18			require XML::Parser::Expat;
19			$VERSION = '2.41';
20			die "Parser.pm and Expat.pm versions don't match"
21			unless $VERSION eq $XML::Parser::Expat::VERSION;
22			}
23
24			$LWP_load_failed = 0;
25
26			sub new {
27			my ($class, %args) = @_;
28			my $style = $args{Style};
29
30			my $nonexopt = $args{Non_Expat_Options} \|\|= {};
31
32			$nonexopt->{Style} = 1;
33			$nonexopt->{Non_Expat_Options} = 1;
34			$nonexopt->{Handlers} = 1;
35			$nonexopt->{_HNDL_TYPES} = 1;
36			$nonexopt->{NoLWP} = 1;
37
38			$args{_HNDL_TYPES} = {%XML::Parser::Expat::Handler_Setters};
39			$args{_HNDL_TYPES}->{Init} = 1;
40			$args{_HNDL_TYPES}->{Final} = 1;
41
42			$args{Handlers} \|\|= {};
43			my $handlers = $args{Handlers};
44
45			if (defined($style)) {
46			my $stylepkg = $style;
47
48			if ($stylepkg !~ /::/) {
49			$stylepkg = "\u$style";
50
51			eval {
52			my $fullpkg = 'XML::Parser::Style::' . $stylepkg;
53			my $stylefile = $fullpkg;
54			$stylefile =~ s/::/\//g;
55			require "$stylefile.pm";
56			$stylepkg = $fullpkg;
57			};
58			if ($@) {
59			# fallback to old behaviour
60			$stylepkg = 'XML::Parser::' . $stylepkg;
61			}
62			}
63
64			my $htype;
65			foreach $htype (keys %{$args{_HNDL_TYPES}}) {
66			# Handlers explicity given override
67			# handlers from the Style package
68			unless (defined($handlers->{$htype})) {
69
70			# A handler in the style package must either have
71			# exactly the right case as the type name or a
72			# completely lower case version of it.
73
74			my $hname = "${stylepkg}::$htype";
75			if (defined(&$hname)) {
76			$handlers->{$htype} = \&$hname;
77			next;
78			}
79
80			$hname = "${stylepkg}::\L$htype";
81			if (defined(&$hname)) {
82			$handlers->{$htype} = \&$hname;
83			next;
84			}
85			}
86			}
87			}
88
89			unless (defined($handlers->{ExternEnt})
90			or defined ($handlers->{ExternEntFin})) {
91
92			if ($args{NoLWP} or $LWP_load_failed) {
93			$handlers->{ExternEnt} = \&file_ext_ent_handler;
94			$handlers->{ExternEntFin} = \&file_ext_ent_cleanup;
95			}
96			else {
97			# The following just bootstraps the real LWP external entity
98			# handler
99
100			$handlers->{ExternEnt} = \&initial_ext_ent_handler;
101
102			# No cleanup function available until LWPExternEnt.pl loaded
103			}
104			}
105
106			$args{Pkg} \|\|= caller;
107			bless \%args, $class;
108			} # End of new
109
110			sub setHandlers {
111			my ($self, @handler_pairs) = @_;
112
113			croak("Uneven number of arguments to setHandlers method")
114			if (int(@handler_pairs) & 1);
115
116			my @ret;
117			while (@handler_pairs) {
118			my $type = shift @handler_pairs;
119			my $handler = shift @handler_pairs;
120			unless (defined($self->{_HNDL_TYPES}->{$type})) {
121			my @types = sort keys %{$self->{_HNDL_TYPES}};
122
123			croak("Unknown Parser handler type: $type\n Valid types: @types");
124			}
125			push(@ret, $type, $self->{Handlers}->{$type});
126			$self->{Handlers}->{$type} = $handler;
127			}
128
129			return @ret;
130			}
131
132			sub parse_start {
133			my $self = shift;
134			my @expat_options = ();
135
136			my ($key, $val);
137			while (($key, $val) = each %{$self}) {
138			push (@expat_options, $key, $val)
139			unless exists $self->{Non_Expat_Options}->{$key};
140			}
141
142			my %handlers = %{$self->{Handlers}};
143			my $init = delete $handlers{Init};
144			my $final = delete $handlers{Final};
145
146			my $expatnb = XML::Parser::ExpatNB->new(@expat_options, @_);
147			$expatnb->setHandlers(%handlers);
148
149			&$init($expatnb)
150			if defined($init);
151
152			$expatnb->{_State_} = 1;
153
154			$expatnb->{FinalHandler} = $final
155			if defined($final);
156
157			return $expatnb;
158			}
159
160			sub parse {
161			my $self = shift;
162			my $arg = shift;
163			my @expat_options = ();
164			my ($key, $val);
165			while (($key, $val) = each %{$self}) {
166			push(@expat_options, $key, $val)
167			unless exists $self->{Non_Expat_Options}->{$key};
168			}
169
170			my $expat = XML::Parser::Expat->new(@expat_options, @_);
171			my %handlers = %{$self->{Handlers}};
172			my $init = delete $handlers{Init};
173			my $final = delete $handlers{Final};
174
175			$expat->setHandlers(%handlers);
176
177			if ($self->{Base}) {
178			$expat->base($self->{Base});
179			}
180
181			&$init($expat)
182			if defined($init);
183
184			my @result = ();
185			my $result;
186			eval {
187			$result = $expat->parse($arg);
188			};
189			my $err = $@;
190			if ($err) {
191			$expat->release;
192			die $err;
193			}
194
195			if ($result and defined($final)) {
196			if (wantarray) {
197			@result = &$final($expat);
198			}
199			else {
200			$result = &$final($expat);
201			}
202			}
203
204			$expat->release;
205
206			return unless defined wantarray;
207			return wantarray ? @result : $result;
208			}
209
210			sub parsestring {
211			my $self = shift;
212			$self->parse(@_);
213			}
214
215			sub parsefile {
216			my $self = shift;
217			my $file = shift;
218			local(*FILE);
219			open(FILE, $file) or croak "Couldn't open $file:\n$!";
220			binmode(FILE);
221			my @ret;
222			my $ret;
223
224			$self->{Base} = $file;
225
226			if (wantarray) {
227			eval {
228			@ret = $self->parse(*FILE, @_);
229			};
230			}
231			else {
232			eval {
233	1	31µs	$ret = $self->parse(*FILE, @_); # spent 31µs making 1 call to XML::Parser::Expat::DESTROY
234			};
235			}
236			my $err = $@;
237			close(FILE);
238			die $err if $err;
239
240			return unless defined wantarray;
241			return wantarray ? @ret : $ret;
242			}
243
244			sub initial_ext_ent_handler {
245			# This just bootstraps in the real lwp_ext_ent_handler which
246			# also loads the URI and LWP modules.
247
248			unless ($LWP_load_failed) {
249			local($^W) = 0;
250
251			my $stat =
252			eval {
253			require('XML/Parser/LWPExternEnt.pl');
254			};
255
256			if ($stat) {
257			$_[0]->setHandlers(ExternEnt => \&lwp_ext_ent_handler,
258			ExternEntFin => \&lwp_ext_ent_cleanup);
259
260			goto &lwp_ext_ent_handler;
261			}
262
263			# Failed to load lwp handler, act as if NoLWP
264
265			$LWP_load_failed = 1;
266
267			my $cmsg = "Couldn't load LWP based external entity handler\n";
268			$cmsg .= "Switching to file-based external entity handler\n";
269			$cmsg .= " (To avoid this message, use NoLWP option to XML::Parser)\n";
270			warn($cmsg);
271			}
272
273			$_[0]->setHandlers(ExternEnt => \&file_ext_ent_handler,
274			ExternEntFin => \&file_ext_ent_cleanup);
275			goto &file_ext_ent_handler;
276
277			}
278
279			sub file_ext_ent_handler {
280			my ($xp, $base, $path) = @_;
281
282			# Prepend base only for relative paths
283
284			if (defined($base)
285			and not ($path =~ m!^(?:[\\/]\|\w+:)!))
286			{
287			my $newpath = $base;
288			$newpath =~ s![^\\/:]*$!$path!;
289			$path = $newpath;
290			}
291
292			if ($path =~ /^\s*[\|>+]/
293			or $path =~ /\\|\s*$/) {
294			$xp->{ErrorMessage}
295			.= "System ID ($path) contains Perl IO control characters";
296			return undef;
297			}
298
299			require IO::File;
300			my $fh = IO::File->new($path);
301			unless (defined $fh) {
302			$xp->{ErrorMessage}
303			.= "Failed to open $path:\n$!";
304			return undef;
305			}
306
307			$xp->{_BaseStack} \|\|= [];
308			$xp->{_FhStack} \|\|= [];
309
310			push(@{$xp->{_BaseStack}}, $base);
311			push(@{$xp->{_FhStack}}, $fh);
312
313			$xp->base($path);
314
315			return $fh;
316			}
317
318			sub file_ext_ent_cleanup {
319			my ($xp) = @_;
320
321			my $fh = pop(@{$xp->{_FhStack}});
322			$fh->close;
323
324			my $base = pop(@{$xp->{_BaseStack}});
325			$xp->base($base);
326			}
327
328			1;
329
330			__END__
331
332			=head1 NAME
333
334			XML::Parser - A perl module for parsing XML documents
335
336			=head1 SYNOPSIS
337
338			use XML::Parser;
339
340			$p1 = XML::Parser->new(Style => 'Debug');
341			$p1->parsefile('REC-xml-19980210.xml');
342			$p1->parse('<foo id="me">Hello World</foo>');
343
344			# Alternative
345			$p2 = XML::Parser->new(Handlers => {Start => \&handle_start,
346			End => \&handle_end,
347			Char => \&handle_char});
348			$p2->parse($socket);
349
350			# Another alternative
351			$p3 = XML::Parser->new(ErrorContext => 2);
352
353			$p3->setHandlers(Char => \&text,
354			Default => \&other);
355
356			open(FOO, 'xmlgenerator \|');
357			$p3->parse(*FOO, ProtocolEncoding => 'ISO-8859-1');
358			close(FOO);
359
360			$p3->parsefile('junk.xml', ErrorContext => 3);
361
362			=begin man
363			.ds PI
364
365			=end man
366
367			=head1 DESCRIPTION
368
369			This module provides ways to parse XML documents. It is built on top of
370			L<XML::Parser::Expat>, which is a lower level interface to James Clark's
371			expat library. Each call to one of the parsing methods creates a new
372			instance of XML::Parser::Expat which is then used to parse the document.
373			Expat options may be provided when the XML::Parser object is created.
374			These options are then passed on to the Expat object on each parse call.
375			They can also be given as extra arguments to the parse methods, in which
376			case they override options given at XML::Parser creation time.
377
378			The behavior of the parser is controlled either by C<L</STYLES>> and/or
379			C<L</HANDLERS>> options, or by L</setHandlers> method. These all provide
380			mechanisms for XML::Parser to set the handlers needed by XML::Parser::Expat.
381			If neither C<Style> nor C<Handlers> are specified, then parsing just
382			checks the document for being well-formed.
383
384			When underlying handlers get called, they receive as their first parameter
385			the I<Expat> object, not the Parser object.
386
387			=head1 METHODS
388
389			=over 4
390
391			=item new
392
393			This is a class method, the constructor for XML::Parser. Options are passed
394			as keyword value pairs. Recognized options are:
395
396			=over 4
397
398			=item * Style
399
400			This option provides an easy way to create a given style of parser. The
401			built in styles are: L<"Debug">, L<"Subs">, L<"Tree">, L<"Objects">,
402			and L<"Stream">. These are all defined in separate packages under
403			C<XML::Parser::Style::*>, and you can find further documentation for
404			each style both below, and in those packages.
405
406			Custom styles can be provided by giving a full package name containing
407			at least one '::'. This package should then have subs defined for each
408			handler it wishes to have installed. See L<"STYLES"> below
409			for a discussion of each built in style.
410
411			=item * Handlers
412
413			When provided, this option should be an anonymous hash containing as
414			keys the type of handler and as values a sub reference to handle that
415			type of event. All the handlers get passed as their 1st parameter the
416			instance of expat that is parsing the document. Further details on
417			handlers can be found in L<"HANDLERS">. Any handler set here
418			overrides the corresponding handler set with the Style option.
419
420			=item * Pkg
421
422			Some styles will refer to subs defined in this package. If not provided,
423			it defaults to the package which called the constructor.
424
425			=item * ErrorContext
426
427			This is an Expat option. When this option is defined, errors are reported
428			in context. The value should be the number of lines to show on either side
429			of the line in which the error occurred.
430
431			=item * ProtocolEncoding
432
433			This is an Expat option. This sets the protocol encoding name. It defaults
434			to none. The built-in encodings are: C<UTF-8>, C<ISO-8859-1>, C<UTF-16>, and
435			C<US-ASCII>. Other encodings may be used if they have encoding maps in one
436			of the directories in the @Encoding_Path list. Check L<"ENCODINGS"> for
437			more information on encoding maps. Setting the protocol encoding overrides
438			any encoding in the XML declaration.
439
440			=item * Namespaces
441
442			This is an Expat option. If this is set to a true value, then namespace
443			processing is done during the parse. See L<XML::Parser::Expat/"Namespaces">
444			for further discussion of namespace processing.
445
446			=item * NoExpand
447
448			This is an Expat option. Normally, the parser will try to expand references
449			to entities defined in the internal subset. If this option is set to a true
450			value, and a default handler is also set, then the default handler will be
451			called when an entity reference is seen in text. This has no effect if a
452			default handler has not been registered, and it has no effect on the expansion
453			of entity references inside attribute values.
454
455			=item * Stream_Delimiter
456
457			This is an Expat option. It takes a string value. When this string is found
458			alone on a line while parsing from a stream, then the parse is ended as if it
459			saw an end of file. The intended use is with a stream of xml documents in a
460			MIME multipart format. The string should not contain a trailing newline.
461
462			=item * ParseParamEnt
463
464			This is an Expat option. Unless standalone is set to "yes" in the XML
465			declaration, setting this to a true value allows the external DTD to be read,
466			and parameter entities to be parsed and expanded.
467
468			=item * NoLWP
469
470			This option has no effect if the ExternEnt or ExternEntFin handlers are
471			directly set. Otherwise, if true, it forces the use of a file based external
472			entity handler.
473
474			=item * Non-Expat-Options
475
476			If provided, this should be an anonymous hash whose keys are options that
477			shouldn't be passed to Expat. This should only be of concern to those
478			subclassing XML::Parser.
479
480			=back
481
482			=item setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])
483
484			This method registers handlers for various parser events. It overrides any
485			previous handlers registered through the Style or Handler options or through
486			earlier calls to setHandlers. By providing a false or undefined value as
487			the handler, the existing handler can be unset.
488
489			This method returns a list of type, handler pairs corresponding to the
490			input. The handlers returned are the ones that were in effect prior to
491			the call.
492
493			See a description of the handler types in L<"HANDLERS">.
494
495			=item parse(SOURCE [, OPT => OPT_VALUE [...]])
496
497			The SOURCE parameter should either be a string containing the whole XML
498			document, or it should be an open IO::Handle. Constructor options to
499			XML::Parser::Expat given as keyword-value pairs may follow the SOURCE
500			parameter. These override, for this call, any options or attributes passed
501			through from the XML::Parser instance.
502
503			A die call is thrown if a parse error occurs. Otherwise it will return 1
504			or whatever is returned from the B<Final> handler, if one is installed.
505			In other words, what parse may return depends on the style.
506
507			=item parsestring
508
509			This is just an alias for parse for backwards compatibility.
510
511			=item parsefile(FILE [, OPT => OPT_VALUE [...]])
512
513			Open FILE for reading, then call parse with the open handle. The file
514			is closed no matter how parse returns. Returns what parse returns.
515
516			=item parse_start([ OPT => OPT_VALUE [...]])
517
518			Create and return a new instance of XML::Parser::ExpatNB. Constructor
519			options may be provided. If an init handler has been provided, it is
520			called before returning the ExpatNB object. Documents are parsed by
521			making incremental calls to the parse_more method of this object, which
522			takes a string. A single call to the parse_done method of this object,
523			which takes no arguments, indicates that the document is finished.
524
525			If there is a final handler installed, it is executed by the parse_done
526			method before returning and the parse_done method returns whatever is
527			returned by the final handler.
528
529			=back
530
531			=head1 HANDLERS
532
533			Expat is an event based parser. As the parser recognizes parts of the
534			document (say the start or end tag for an XML element), then any handlers
535			registered for that type of an event are called with suitable parameters.
536			All handlers receive an instance of XML::Parser::Expat as their first
537			argument. See L<XML::Parser::Expat/"METHODS"> for a discussion of the
538			methods that can be called on this object.
539
540			=head2 Init (Expat)
541
542			This is called just before the parsing of the document starts.
543
544			=head2 Final (Expat)
545
546			This is called just after parsing has finished, but only if no errors
547			occurred during the parse. Parse returns what this returns.
548
549			=head2 Start (Expat, Element [, Attr, Val [,...]])
550
551			This event is generated when an XML start tag is recognized. Element is the
552			name of the XML element type that is opened with the start tag. The Attr &
553			Val pairs are generated for each attribute in the start tag.
554
555			=head2 End (Expat, Element)
556
557			This event is generated when an XML end tag is recognized. Note that
558			an XML empty tag (<foo/>) generates both a start and an end event.
559
560			=head2 Char (Expat, String)
561
562			This event is generated when non-markup is recognized. The non-markup
563			sequence of characters is in String. A single non-markup sequence of
564			characters may generate multiple calls to this handler. Whatever the
565			encoding of the string in the original document, this is given to the
566			handler in UTF-8.
567
568			=head2 Proc (Expat, Target, Data)
569
570			This event is generated when a processing instruction is recognized.
571
572			=head2 Comment (Expat, Data)
573
574			This event is generated when a comment is recognized.
575
576			=head2 CdataStart (Expat)
577
578			This is called at the start of a CDATA section.
579
580			=head2 CdataEnd (Expat)
581
582			This is called at the end of a CDATA section.
583
584			=head2 Default (Expat, String)
585
586			This is called for any characters that don't have a registered handler.
587			This includes both characters that are part of markup for which no
588			events are generated (markup declarations) and characters that
589			could generate events, but for which no handler has been registered.
590
591			Whatever the encoding in the original document, the string is returned to
592			the handler in UTF-8.
593
594			=head2 Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)
595
596			This is called for a declaration of an unparsed entity. Entity is the name
597			of the entity. Base is the base to be used for resolving a relative URI.
598			Sysid is the system id. Pubid is the public id. Notation is the notation
599			name. Base and Pubid may be undefined.
600
601			=head2 Notation (Expat, Notation, Base, Sysid, Pubid)
602
603			This is called for a declaration of notation. Notation is the notation name.
604			Base is the base to be used for resolving a relative URI. Sysid is the system
605			id. Pubid is the public id. Base, Sysid, and Pubid may all be undefined.
606
607			=head2 ExternEnt (Expat, Base, Sysid, Pubid)
608
609			This is called when an external entity is referenced. Base is the base to be
610			used for resolving a relative URI. Sysid is the system id. Pubid is the public
611			id. Base, and Pubid may be undefined.
612
613			This handler should either return a string, which represents the contents of
614			the external entity, or return an open filehandle that can be read to obtain
615			the contents of the external entity, or return undef, which indicates the
616			external entity couldn't be found and will generate a parse error.
617
618			If an open filehandle is returned, it must be returned as either a glob
619			(*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).
620
621			A default handler is installed for this event. The default handler is
622			XML::Parser::lwp_ext_ent_handler unless the NoLWP option was provided with
623			a true value, otherwise XML::Parser::file_ext_ent_handler is the default
624			handler for external entities. Even without the NoLWP option, if the
625			URI or LWP modules are missing, the file based handler ends up being used
626			after giving a warning on the first external entity reference.
627
628			The LWP external entity handler will use proxies defined in the environment
629			(http_proxy, ftp_proxy, etc.).
630
631			Please note that the LWP external entity handler reads the entire
632			entity into a string and returns it, where as the file handler opens a
633			filehandle.
634
635			Also note that the file external entity handler will likely choke on
636			absolute URIs or file names that don't fit the conventions of the local
637			operating system.
638
639			The expat base method can be used to set a basename for
640			relative pathnames. If no basename is given, or if the basename is itself
641			a relative name, then it is relative to the current working directory.
642
643			=head2 ExternEntFin (Expat)
644
645			This is called after parsing an external entity. It's not called unless
646			an ExternEnt handler is also set. There is a default handler installed
647			that pairs with the default ExternEnt handler.
648
649			If you're going to install your own ExternEnt handler, then you should
650			set (or unset) this handler too.
651
652			=head2 Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)
653
654			This is called when an entity is declared. For internal entities, the Val
655			parameter will contain the value and the remaining three parameters will be
656			undefined. For external entities, the Val parameter will be undefined, the
657			Sysid parameter will have the system id, the Pubid parameter will have the
658			public id if it was provided (it will be undefined otherwise), the Ndata
659			parameter will contain the notation for unparsed entities. If this is a
660			parameter entity declaration, then the IsParam parameter is true.
661
662			Note that this handler and the Unparsed handler above overlap. If both are
663			set, then this handler will not be called for unparsed entities.
664
665			=head2 Element (Expat, Name, Model)
666
667			The element handler is called when an element declaration is found. Name
668			is the element name, and Model is the content model as an XML::Parser::Content
669			object. See L<XML::Parser::Expat/"XML::Parser::ContentModel Methods">
670			for methods available for this class.
671
672			=head2 Attlist (Expat, Elname, Attname, Type, Default, Fixed)
673
674			This handler is called for each attribute in an ATTLIST declaration.
675			So an ATTLIST declaration that has multiple attributes will generate multiple
676			calls to this handler. The Elname parameter is the name of the element with
677			which the attribute is being associated. The Attname parameter is the name
678			of the attribute. Type is the attribute type, given as a string. Default is
679			the default value, which will either be "#REQUIRED", "#IMPLIED" or a quoted
680			string (i.e. the returned string will begin and end with a quote character).
681			If Fixed is true, then this is a fixed attribute.
682
683			=head2 Doctype (Expat, Name, Sysid, Pubid, Internal)
684
685			This handler is called for DOCTYPE declarations. Name is the document type
686			name. Sysid is the system id of the document type, if it was provided,
687			otherwise it's undefined. Pubid is the public id of the document type,
688			which will be undefined if no public id was given. Internal is the internal
689			subset, given as a string. If there was no internal subset, it will be
690			undefined. Internal will contain all whitespace, comments, processing
691			instructions, and declarations seen in the internal subset. The declarations
692			will be there whether or not they have been processed by another handler
693			(except for unparsed entities processed by the Unparsed handler). However,
694			comments and processing instructions will not appear if they've been processed
695			by their respective handlers.
696
697			=head2 * DoctypeFin (Parser)
698
699			This handler is called after parsing of the DOCTYPE declaration has finished,
700			including any internal or external DTD declarations.
701
702			=head2 XMLDecl (Expat, Version, Encoding, Standalone)
703
704			This handler is called for xml declarations. Version is a string containg
705			the version. Encoding is either undefined or contains an encoding string.
706			Standalone will be either true, false, or undefined if the standalone attribute
707			is yes, no, or not made respectively.
708
709			=head1 STYLES
710
711			=head2 Debug
712
713			This just prints out the document in outline form. Nothing special is
714			returned by parse.
715
716			=head2 Subs
717
718			Each time an element starts, a sub by that name in the package specified
719			by the Pkg option is called with the same parameters that the Start
720			handler gets called with.
721
722			Each time an element ends, a sub with that name appended with an underscore
723			("_"), is called with the same parameters that the End handler gets called
724			with.
725
726			Nothing special is returned by parse.
727
728			=head2 Tree
729
730			Parse will return a parse tree for the document. Each node in the tree
731			takes the form of a tag, content pair. Text nodes are represented with
732			a pseudo-tag of "0" and the string that is their content. For elements,
733			the content is an array reference. The first item in the array is a
734			(possibly empty) hash reference containing attributes. The remainder of
735			the array is a sequence of tag-content pairs representing the content
736			of the element.
737
738			So for example the result of parsing:
739
740			<foo><head id="a">Hello <em>there</em></head><bar>Howdy<ref/></bar>do</foo>
741
742			would be:
743
744			Tag Content
745			==================================================================
746			[foo, [{}, head, [{id => "a"}, 0, "Hello ", em, [{}, 0, "there"]],
747			bar, [ {}, 0, "Howdy", ref, [{}]],
748			0, "do"
749			]
750			]
751
752			The root document "foo", has 3 children: a "head" element, a "bar"
753			element and the text "do". After the empty attribute hash, these are
754			represented in it's contents by 3 tag-content pairs.
755
756			=head2 Objects
757
758			This is similar to the Tree style, except that a hash object is created for
759			each element. The corresponding object will be in the class whose name
760			is created by appending "::" and the element name to the package set with
761			the Pkg option. Non-markup text will be in the ::Characters class. The
762			contents of the corresponding object will be in an anonymous array that
763			is the value of the Kids property for that object.
764
765			=head2 Stream
766
767			This style also uses the Pkg package. If none of the subs that this
768			style looks for is there, then the effect of parsing with this style is
769			to print a canonical copy of the document without comments or declarations.
770			All the subs receive as their 1st parameter the Expat instance for the
771			document they're parsing.
772
773			It looks for the following routines:
774
775			=over 4
776
777			=item * StartDocument
778
779			Called at the start of the parse .
780
781			=item * StartTag
782
783			Called for every start tag with a second parameter of the element type. The $_
784			variable will contain a copy of the tag and the %_ variable will contain
785			attribute values supplied for that element.
786
787			=item * EndTag
788
789			Called for every end tag with a second parameter of the element type. The $_
790			variable will contain a copy of the end tag.
791
792			=item * Text
793
794			Called just before start or end tags with accumulated non-markup text in
795			the $_ variable.
796
797			=item * PI
798
799			Called for processing instructions. The $_ variable will contain a copy of
800			the PI and the target and data are sent as 2nd and 3rd parameters
801			respectively.
802
803			=item * EndDocument
804
805			Called at conclusion of the parse.
806
807			=back
808
809			=head1 ENCODINGS
810
811			XML documents may be encoded in character sets other than Unicode as
812			long as they may be mapped into the Unicode character set. Expat has
813			further restrictions on encodings. Read the xmlparse.h header file in
814			the expat distribution to see details on these restrictions.
815
816			Expat has built-in encodings for: C<UTF-8>, C<ISO-8859-1>, C<UTF-16>, and
817			C<US-ASCII>. Encodings are set either through the XML declaration
818			encoding attribute or through the ProtocolEncoding option to XML::Parser
819			or XML::Parser::Expat.
820
821			For encodings other than the built-ins, expat calls the function
822			load_encoding in the Expat package with the encoding name. This function
823			looks for a file in the path list @XML::Parser::Expat::Encoding_Path, that
824			matches the lower-cased name with a '.enc' extension. The first one it
825			finds, it loads.
826
827			If you wish to build your own encoding maps, check out the XML::Encoding
828			module from CPAN.
829
830			=head1 AUTHORS
831
832			Larry Wall <F<larry@wall.org>> wrote version 1.0.
833
834			Clark Cooper <F<coopercc@netheaven.com>> picked up support, changed the API
835			for this version (2.x), provided documentation,
836			and added some standard package features.
837
838			Matt Sergeant <F<matt@sergeant.org>> is now maintaining XML::Parser
839
840			=cut