[31809] | 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 | $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 = 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 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<[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
|
---|