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 Carp;
|
---|
12 |
|
---|
13 | BEGIN {
|
---|
14 | require XML::Parser::Expat;
|
---|
15 | $VERSION = '2.34';
|
---|
16 | die "Parser.pm and Expat.pm versions don't match"
|
---|
17 | unless $VERSION eq $XML::Parser::Expat::VERSION;
|
---|
18 | }
|
---|
19 |
|
---|
20 | use strict;
|
---|
21 |
|
---|
22 | use vars qw($VERSION $LWP_load_failed);
|
---|
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 = new XML::Parser::ExpatNB(@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 = new XML::Parser::Expat(@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 | $ret = $self->parse(*FILE, @_);
|
---|
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 = new IO::File($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 = new XML::Parser(Style => 'Debug');
|
---|
341 | $p1->parsefile('REC-xml-19980210.xml');
|
---|
342 | $p1->parse('<foo id="me">Hello World</foo>');
|
---|
343 |
|
---|
344 | # Alternative
|
---|
345 | $p2 = new XML::Parser(Handlers => {Start => \&handle_start,
|
---|
346 | End => \&handle_end,
|
---|
347 | Char => \&handle_char});
|
---|
348 | $p2->parse($socket);
|
---|
349 |
|
---|
350 | # Another alternative
|
---|
351 | $p3 = new XML::Parser(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 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</Style>> 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<[email protected]>> wrote version 1.0.
|
---|
833 |
|
---|
834 | Clark Cooper <F<[email protected]>> 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<[email protected]>> is now maintaining XML::Parser
|
---|
839 |
|
---|
840 | =cut
|
---|