local-lib5/man/man3/XML::SAX.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "SAX 3"
 127 .TH SAX 3 "2008-08-05" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::SAX \- Simple API for XML
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use XML::SAX;
 138 \&
 139 \&  # get a list of known parsers
 140 \&  my $parsers = XML::SAX\->parsers();
 141 \&
 142 \&  # add/update a parser
 143 \&  XML::SAX\->add_parser(q(XML::SAX::PurePerl));
 144 \&
 145 \&  # remove parser
 146 \&  XML::SAX\->remove_parser(q(XML::SAX::Foodelberry));
 147 \&
 148 \&  # save parsers
 149 \&  XML::SAX\->save_parsers();
 150 .Ve
 151 .SH "DESCRIPTION"
 152 .IX Header "DESCRIPTION"
 153 \&\s-1XML::SAX\s0 is a \s-1SAX\s0 parser access \s-1API\s0 for Perl. It includes classes
 154 and APIs required for implementing \s-1SAX\s0 drivers, along with a factory
 155 class for returning any \s-1SAX\s0 parser installed on the user's system.
 156 .SH "USING A SAX2 PARSER"
 157 .IX Header "USING A SAX2 PARSER"
 158 The factory class is XML::SAX::ParserFactory. Please see the
 159 documentation of that module for how to instantiate a \s-1SAX\s0 parser:
 160 XML::SAX::ParserFactory. However if you don't want to load up
 161 another manual page, here's a short synopsis:
 162 .PP
 163 .Vb 6
 164 \&  use XML::SAX::ParserFactory;
 165 \&  use XML::SAX::XYZHandler;
 166 \&  my $handler = XML::SAX::XYZHandler\->new();
 167 \&  my $p = XML::SAX::ParserFactory\->parser(Handler => $handler);
 168 \&  $p\->parse_uri("foo.xml");
 169 \&  # or $p\->parse_string("<foo/>") or $p\->parse_file($fh);
 170 .Ve
 171 .PP
 172 This will automatically load a \s-1SAX2\s0 parser (defaulting to
 173 XML::SAX::PurePerl if no others are found) and return it to you.
 174 .PP
 175 In order to learn how to use \s-1SAX\s0 to parse \s-1XML\s0, you will need to read
 176 XML::SAX::Intro and for reference, XML::SAX::Specification.
 177 .SH "WRITING A SAX2 PARSER"
 178 .IX Header "WRITING A SAX2 PARSER"
 179 The first thing to remember in writing a \s-1SAX2\s0 parser is to subclass
 180 XML::SAX::Base. This will make your life infinitely easier, by providing
 181 a number of methods automagically for you. See XML::SAX::Base for more
 182 details.
 183 .PP
 184 When writing a \s-1SAX2\s0 parser that is compatible with \s-1XML::SAX\s0, you need
 185 to inform \s-1XML::SAX\s0 of the presence of that driver when you install it.
 186 In order to do that, \s-1XML::SAX\s0 contains methods for saving the fact that
 187 the parser exists on your system to a \*(L"\s-1INI\s0\*(R" file, which is then loaded
 188 to determine which parsers are installed.
 189 .PP
 190 The best way to do this is to follow these rules:
 191 .IP "\(bu" 4
 192 Add \s-1XML::SAX\s0 as a prerequisite in Makefile.PL:
 193 .Sp
 194 .Vb 5
 195 \&  WriteMakefile(
 196 \&      ...
 197 \&      PREREQ_PM => { \*(AqXML::SAX\*(Aq => 0 },
 198 \&      ...
 199 \&  );
 200 .Ve
 201 .Sp
 202 Alternatively you may wish to check for it in other ways that will
 203 cause more than just a warning.
 204 .IP "\(bu" 4
 205 Add the following code snippet to your Makefile.PL:
 206 .Sp
 207 .Vb 8
 208 \&  sub MY::install {
 209 \&    package MY;
 210 \&    my $script = shift\->SUPER::install(@_);
 211 \&    if (ExtUtils::MakeMaker::prompt(
 212 \&      "Do you want to modify ParserDetails.ini?", \*(AqY\*(Aq)
 213 \&      =~ /^y/i) {
 214 \&      $script =~ s/install :: (.*)$/install :: $1 install_sax_driver/m;
 215 \&      $script .= <<"INSTALL";
 216 \&
 217 \&  install_sax_driver :
 218 \&  \et\e@\e$(PERL) \-MXML::SAX \-e "XML::SAX\->add_parser(q(\e$(NAME)))\->save_parsers()"
 219 \&
 220 \&  INSTALL
 221 \&    }
 222 \&    return $script;
 223 \&  }
 224 .Ve
 225 .Sp
 226 Note that you should check the output of this \- \e$(\s-1NAME\s0) will use the name of
 227 your distribution, which may not be exactly what you want. For example XML::LibXML
 228 has a driver called XML::LibXML::SAX::Generator, which is used in place of
 229 \&\e$(\s-1NAME\s0) in the above.
 230 .IP "\(bu" 4
 231 Add an \s-1XML::SAX\s0 test:
 232 .Sp
 233 A test file should be added to your t/ directory containing something like the
 234 following:
 235 .Sp
 236 .Vb 10
 237 \&  use Test;
 238 \&  BEGIN { plan tests => 3 }
 239 \&  use XML::SAX;
 240 \&  use XML::SAX::PurePerl::DebugHandler;
 241 \&  XML::SAX\->add_parser(q(XML::SAX::MyDriver));
 242 \&  local $XML::SAX::ParserPackage = \*(AqXML::SAX::MyDriver\*(Aq;
 243 \&  eval {
 244 \&    my $handler = XML::SAX::PurePerl::DebugHandler\->new();
 245 \&    ok($handler);
 246 \&    my $parser = XML::SAX::ParserFactory\->parser(Handler => $handler);
 247 \&    ok($parser);
 248 \&    ok($parser\->isa(\*(AqXML::SAX::MyDriver\*(Aq);
 249 \&    $parser\->parse_string("<tag/>");
 250 \&    ok($handler\->{seen}{start_element});
 251 \&  };
 252 .Ve
 253 .SH "EXPORTS"
 254 .IX Header "EXPORTS"
 255 By default, \s-1XML::SAX\s0 exports nothing into the caller's namespace. However you
 256 can request the symbols \f(CW\*(C`Namespaces\*(C'\fR and \f(CW\*(C`Validation\*(C'\fR which are the
 257 URIs for those features, allowing an easier way to request those features
 258 via ParserFactory:
 259 .PP
 260 .Vb 5
 261 \&  use XML::SAX qw(Namespaces Validation);
 262 \&  my $factory = XML::SAX::ParserFactory\->new();
 263 \&  $factory\->require_feature(Namespaces);
 264 \&  $factory\->require_feature(Validation);
 265 \&  my $parser = $factory\->parser();
 266 .Ve
 267 .SH "AUTHOR"
 268 .IX Header "AUTHOR"
 269 Current maintainer: Grant McLean, grantm@cpan.org
 270 .PP
 271 Originally written by:
 272 .PP
 273 Matt Sergeant, matt@sergeant.org
 274 .PP
 275 Kip Hampton, khampton@totalcinema.com
 276 .PP
 277 Robin Berjon, robin@knowscape.com
 278 .SH "LICENSE"
 279 .IX Header "LICENSE"
 280 This is free software, you may use it and distribute it under
 281 the same terms as Perl itself.
 282 .SH "SEE ALSO"
 283 .IX Header "SEE ALSO"
 284 XML::SAX::Base for writing \s-1SAX\s0 Filters and Parsers
 285 .PP
 286 XML::SAX::PurePerl for an \s-1XML\s0 parser written in 100%
 287 pure perl.
 288 .PP
 289 XML::SAX::Exception for details on exception handling