local-lib5/man/man3/XML::SAX::ParserFactory.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::ParserFactory 3"
 127 .TH SAX::ParserFactory 3 "2008-08-04" "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::ParserFactory \- Obtain a SAX parser
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 6
 137 \&  use XML::SAX::ParserFactory;
 138 \&  use XML::SAX::XYZHandler;
 139 \&  my $handler = XML::SAX::XYZHandler\->new();
 140 \&  my $p = XML::SAX::ParserFactory\->parser(Handler => $handler);
 141 \&  $p\->parse_uri("foo.xml");
 142 \&  # or $p\->parse_string("<foo/>") or $p\->parse_file($fh);
 143 .Ve
 144 .SH "DESCRIPTION"
 145 .IX Header "DESCRIPTION"
 146 XML::SAX::ParserFactory is a factory class for providing an application
 147 with a Perl \s-1SAX2\s0 \s-1XML\s0 parser. It is akin to \s-1DBI\s0 \- a front end for other
 148 parser classes. Each new \s-1SAX2\s0 parser installed will register itself
 149 with \s-1XML::SAX\s0, and then it will become available to all applications
 150 that use XML::SAX::ParserFactory to obtain a \s-1SAX\s0 parser.
 151 .PP
 152 Unlike \s-1DBI\s0 however, \s-1XML/SAX\s0 parsers almost all work alike (especially
 153 if they subclass XML::SAX::Base, as they should), so rather than
 154 specifying the parser you want in the call to \f(CW\*(C`parser()\*(C'\fR, \s-1XML::SAX\s0
 155 has several ways to automatically choose which parser to use:
 156 .IP "\(bu" 4
 157 \&\f(CW$XML::SAX::ParserPackage\fR
 158 .Sp
 159 If this package variable is set, then this package is \f(CW\*(C`require()\*(C'\fRd
 160 and an instance of this package is returned by calling the \f(CW\*(C`new()\*(C'\fR
 161 class method in that package. If it cannot be loaded or there is
 162 an error, an exception will be thrown. The variable can also contain
 163 a version number:
 164 .Sp
 165 .Vb 1
 166 \&  $XML::SAX::ParserPackage = "XML::SAX::Expat (0.72)";
 167 .Ve
 168 .Sp
 169 And the number will be treated as a minimum version number.
 170 .IP "\(bu" 4
 171 Required features
 172 .Sp
 173 It is possible to require features from the parsers. For example, you
 174 may wish for a parser that supports validation via a \s-1DTD\s0. To do that,
 175 use the following code:
 176 .Sp
 177 .Vb 4
 178 \&  use XML::SAX::ParserFactory;
 179 \&  my $factory = XML::SAX::ParserFactory\->new();
 180 \&  $factory\->require_feature(\*(Aqhttp://xml.org/sax/features/validation\*(Aq);
 181 \&  my $parser = $factory\->parser(...);
 182 .Ve
 183 .Sp
 184 Alternatively, specify the required features in the call to the
 185 ParserFactory constructor:
 186 .Sp
 187 .Vb 5
 188 \&  my $factory = XML::SAX::ParserFactory\->new(
 189 \&          RequiredFeatures => {
 190 \&               \*(Aqhttp://xml.org/sax/features/validation\*(Aq => 1,
 191 \&               }
 192 \&          );
 193 .Ve
 194 .Sp
 195 If the features you have asked for are unavailable (for example the
 196 user might not have a validating parser installed), then an
 197 exception will be thrown.
 198 .Sp
 199 The list of known parsers is searched in reverse order, so it will
 200 always return the last installed parser that supports all of your
 201 requested features (Note: this is subject to change if someone
 202 comes up with a better way of making this work).
 203 .IP "\(bu" 4
 204 \&\s-1SAX\s0.ini
 205 .Sp
 206 ParserFactory will search \f(CW@INC\fR for a file called \s-1SAX\s0.ini, which
 207 is in a simple format:
 208 .Sp
 209 .Vb 3
 210 \&  # a comment looks like this,
 211 \&  ; or like this, and are stripped anywhere in the file
 212 \&  key = value # SAX.in contains key/value pairs.
 213 .Ve
 214 .Sp
 215 All whitespace is non-significant.
 216 .Sp
 217 This file can contain either a line:
 218 .Sp
 219 .Vb 1
 220 \&  ParserPackage = MyParserModule (1.02)
 221 .Ve
 222 .Sp
 223 Where MyParserModule is the module to load and use for the parser,
 224 and the number in brackets is a minimum version to load.
 225 .Sp
 226 Or you can list required features:
 227 .Sp
 228 .Vb 1
 229 \&  http://xml.org/sax/features/validation = 1
 230 .Ve
 231 .Sp
 232 And each feature with a true value will be required.
 233 .IP "\(bu" 4
 234 Fallback
 235 .Sp
 236 If none of the above works, the last parser installed on the user's
 237 system will be used. The \s-1XML::SAX\s0 package ships with a pure perl
 238 \&\s-1XML\s0 parser, XML::SAX::PurePerl, so that there will always be a
 239 fallback parser.
 240 .SH "AUTHOR"
 241 .IX Header "AUTHOR"
 242 Matt Sergeant, matt@sergeant.org
 243 .SH "LICENSE"
 244 .IX Header "LICENSE"
 245 This is free software, you may use it and distribute it under the same
 246 terms as Perl itself.