local-lib5/man/man3/XML::LibXML::InputCallback.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 "XML::LibXML::InputCallback 3"
 127 .TH XML::LibXML::InputCallback 3 "2009-10-07" "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::LibXML::InputCallback \- XML::LibXML Class for Input Callbacks
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use XML::LibXML;
 138 .Ve
 139 .SH "DESCRIPTION"
 140 .IX Header "DESCRIPTION"
 141 You may get unexpected results if you are trying to load external documents
 142 during libxml2 parsing if the location of the resource is not a \s-1HTTP\s0, \s-1FTP\s0 or
 143 relative location but a absolute path for example. To get around this
 144 limitation, you may add your own input handler to open, read and close
 145 particular types of locations or \s-1URI\s0 classes. Using this input callback
 146 handlers, you can handle your own custom \s-1URI\s0 schemes for example.
 147 .PP
 148 The input callbacks are used whenever LibXML has to get something other than
 149 externally parsed entities from somewhere. They are implemented using a
 150 callback stack on the Perl layer in analogy to libxml2's native callback stack.
 151 .PP
 152 The XML::LibXML::InputCallback class transparently registers the input
 153 callbacks for the libxml2's parser processes.
 154 .SS "How does XML::LibXML::InputCallback work?"
 155 .IX Subsection "How does XML::LibXML::InputCallback work?"
 156 The libxml2 library offers a callback implementation as global functions only.
 157 To work-around the troubles resulting in having only global callbacks \- for
 158 example, if the same global callback stack is manipulated by different
 159 applications running together in a single Apache Web-server environment \-,
 160 XML::LibXML::InputCallback comes with a object-oriented and a function-oriented
 161 part.
 162 .PP
 163 Using the function-oriented part the global callback stack of libxml2 can be
 164 manipulated. Those functions can be used as interface to the callbacks on the
 165 C\- and \s-1XS\s0 Layer. At the object-oriented part, operations for working with the
 166 \&\*(L"pseudo-localized\*(R" callback stack are implemented. Currently, you can register
 167 and de-register callbacks on the Perl layer and initialize them on a per parser
 168 basis.
 169 .PP
 170 \fICallback Groups\fR
 171 .IX Subsection "Callback Groups"
 172 .PP
 173 The libxml2 input callbacks come in groups. One group contains a \s-1URI\s0 matcher (\fImatch\fR), a data stream constructor (\fIopen\fR), a data stream reader (\fIread\fR), and a data stream destructor (\fIclose\fR). The callbacks can be manipulated on a per group basis only.
 174 .PP
 175 \fIThe Parser Process\fR
 176 .IX Subsection "The Parser Process"
 177 .PP
 178 The parser process work on a \s-1XML\s0 data stream, along which, links to other
 179 resources can be embedded. This can be links to external DTDs or XIncludes for
 180 example. Those resources are identified by URIs. The callback implementation of
 181 libxml2 assumes that one callback group can handle a certain amount of URIs and
 182 a certain \s-1URI\s0 scheme. Per default, callback handlers for \fIfile://*\fR, \fIfile:://*.gz\fR, \fIhttp://*\fR and \fIftp://*\fR are registered.
 183 .PP
 184 Callback groups in the callback stack are processed from top to bottom, meaning
 185 that callback groups registered later will be processed before the earlier
 186 registered ones.
 187 .PP
 188 While parsing the data stream, the libxml2 parser checks if a registered
 189 callback group will handle a \s-1URI\s0 \- if they will not, the \s-1URI\s0 will be
 190 interpreted as \fIfile://URI\fR. To handle a \s-1URI\s0, the \fImatch\fR callback will have to return '1'. If that happens, the handling of the \s-1URI\s0 will
 191 be passed to that callback group. Next, the \s-1URI\s0 will be passed to the \fIopen\fR callback, which should return a \fIreference\fR to the data stream if it successfully opened the file, '0' otherwise. If
 192 opening the stream was successful, the \fIread\fR callback will be called repeatedly until it returns an empty string. After the
 193 read callback, the \fIclose\fR callback will be called to close the stream.
 194 .PP
 195 \fIOrganisation of callback groups in XML::LibXML::InputCallback\fR
 196 .IX Subsection "Organisation of callback groups in XML::LibXML::InputCallback"
 197 .PP
 198 Callback groups are implemented as a stack (Array), each entry holds a
 199 reference to an array of the callbacks. For the libxml2 library, the
 200 XML::LibXML::InputCallback callback implementation appears as one single
 201 callback group. The Perl implementation however allows to manage different
 202 callback stacks on a per libxml2\-parser basis.
 203 .SS "Using XML::LibXML::InputCallback"
 204 .IX Subsection "Using XML::LibXML::InputCallback"
 205 After object instantiation using the parameter-less constructor, you can
 206 register callback groups.
 207 .PP
 208 .Vb 7
 209 \&  my $input_callbacks = XML::LibXML::InputCallback\->new();
 210 \&  $input_callbacks\->register_callbacks([ $match_cb1, $open_cb1,
 211 \&                                         $read_cb1, $close_cb1 ] );
 212 \&  $input_callbacks\->register_callbacks([ $match_cb2, $open_cb2,
 213 \&                                         $read_cb2, $close_cb2 ] );
 214 \&  $input_callbacks\->register_callbacks( [ $match_cb3, $open_cb3,
 215 \&                                          $read_cb3, $close_cb3 ] );
 216 \&
 217 \&  $parser\->input_callbacks( $input_callbacks );
 218 \&  $parser\->parse_file( $some_xml_file );
 219 .Ve
 220 .SS "What about the old callback system prior to XML::LibXML::InputCallback?"
 221 .IX Subsection "What about the old callback system prior to XML::LibXML::InputCallback?"
 222 In XML::LibXML versions prior to 1.59 \- i.e. without the
 223 XML::LibXML::InputCallback module \- you could define your callbacks either
 224 using globally or locally. You still can do that using
 225 XML::LibXML::InputCallback, and in addition to that you can define the
 226 callbacks on a per parser basis!
 227 .PP
 228 If you use the old callback interface through global callbacks,
 229 XML::LibXML::InputCallback will treat them with a lower priority as the ones
 230 registered using the new interface. The global callbacks will not override the
 231 callback groups registered using the new interface. Local callbacks are
 232 attached to a specific parser instance, therefore they are treated with highest
 233 priority. If the \fImatch\fR callback of the callback group registered as local variable is identical to one
 234 of the callback groups registered using the new interface, that callback group
 235 will be replaced.
 236 .PP
 237 Users of the old callback implementation whose \fIopen\fR callback returned a plain string, will have to adapt their code to return a
 238 reference to that string after upgrading to version >= 1.59. The new callback
 239 system can only deal with the \fIopen\fR callback returning a reference!
 240 .SH "INTERFACE DESCRIPTION"
 241 .IX Header "INTERFACE DESCRIPTION"
 242 .SS "Global Variables"
 243 .IX Subsection "Global Variables"
 244 .ie n .IP "$_CUR_CB" 4
 245 .el .IP "\f(CW$_CUR_CB\fR" 4
 246 .IX Item "$_CUR_CB"
 247 Stores the current callback and can be used as shortcut to access the callback
 248 stack.
 249 .ie n .IP "@_GLOBAL_CALLBACKS" 4
 250 .el .IP "\f(CW@_GLOBAL_CALLBACKS\fR" 4
 251 .IX Item "@_GLOBAL_CALLBACKS"
 252 Stores all callback groups for the current parser process.
 253 .ie n .IP "@_CB_STACK" 4
 254 .el .IP "\f(CW@_CB_STACK\fR" 4
 255 .IX Item "@_CB_STACK"
 256 Stores the currently used callback group. Used to prevent parser errors when
 257 dealing with nested \s-1XML\s0 data.
 258 .SS "Global Callbacks"
 259 .IX Subsection "Global Callbacks"
 260 .IP "_callback_match" 4
 261 .IX Item "_callback_match"
 262 Implements the interface for the \fImatch\fR callback at C\-level and for the selection of the callback group from the
 263 callbacks defined at the Perl-level.
 264 .IP "_callback_open" 4
 265 .IX Item "_callback_open"
 266 Forwards the \fIopen\fR callback from libxml2 to the corresponding callback function at the Perl-level.
 267 .IP "_callback_read" 4
 268 .IX Item "_callback_read"
 269 Forwards the read request to the corresponding callback function at the
 270 Perl-level and returns the result to libxml2.
 271 .IP "_callback_close" 4
 272 .IX Item "_callback_close"
 273 Forwards the \fIclose\fR callback from libxml2 to the corresponding callback function at the
 274 Perl-level..
 275 .SS "Class methods"
 276 .IX Subsection "Class methods"
 277 .IP "\fInew()\fR" 4
 278 .IX Item "new()"
 279 A simple constructor.
 280 .ie n .IP "register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])" 4
 281 .el .IP "register_callbacks( [ \f(CW$match_cb\fR, \f(CW$open_cb\fR, \f(CW$read_cb\fR, \f(CW$close_cb\fR ])" 4
 282 .IX Item "register_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])"
 283 The four callbacks \fIhave\fR to be given as array reference in the above order \fImatch\fR, \fIopen\fR, \fIread\fR, \fIclose\fR!
 284 .ie n .IP "unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])" 4
 285 .el .IP "unregister_callbacks( [ \f(CW$match_cb\fR, \f(CW$open_cb\fR, \f(CW$read_cb\fR, \f(CW$close_cb\fR ])" 4
 286 .IX Item "unregister_callbacks( [ $match_cb, $open_cb, $read_cb, $close_cb ])"
 287 With no arguments given, \f(CW\*(C`unregister_callbacks()\*(C'\fR will delete the last registered callback group from the stack. If four
 288 callbacks are passed as array reference, the callback group to unregister will
 289 be identified by the \fImatch\fR callback and deleted from the callback stack. Note that if several identical \fImatch\fR callbacks are defined in different callback groups, \s-1ALL\s0 of them will be deleted
 290 from the stack.
 291 .IP "\fIinit_callbacks()\fR" 4
 292 .IX Item "init_callbacks()"
 293 Initializes the callback system before a parsing process.
 294 .IP "\fIcleanup_callbacks()\fR" 4
 295 .IX Item "cleanup_callbacks()"
 296 Resets global variables and the libxml2 callback stack.
 297 .IP "\fIlib_init_callbacks()\fR" 4
 298 .IX Item "lib_init_callbacks()"
 299 Used internally for callback registration at C\-level.
 300 .IP "\fIlib_cleanup_callbacks()\fR" 4
 301 .IX Item "lib_cleanup_callbacks()"
 302 Used internally for callback resetting at the C\-level.
 303 .SH "EXAMPLE CALLBACKS"
 304 .IX Header "EXAMPLE CALLBACKS"
 305 The following example is a purely fictitious example that uses a
 306 MyScheme::Handler object that responds to methods similar to an IO::Handle.
 307 .PP
 308 .Vb 5
 309 \&  # Define the four callback functions
 310 \&  sub match_uri {
 311 \&      my $uri = shift;
 312 \&      return $uri =~ /^myscheme:/; # trigger our callback group at a \*(Aqmyscheme\*(Aq URIs
 313 \&  }
 314 \&
 315 \&  sub open_uri {
 316 \&      my $uri = shift;
 317 \&      my $handler = MyScheme::Handler\->new($uri);
 318 \&      return $handler;
 319 \&  }
 320 \&
 321 \&  # The returned $buffer will be parsed by the libxml2 parser
 322 \&  sub read_uri {
 323 \&      my $handler = shift;
 324 \&      my $length = shift;
 325 \&      my $buffer;
 326 \&      read($handler, $buffer, $length);
 327 \&      return $buffer; # $buffer will be an empty string \*(Aq\*(Aq if read() is done
 328 \&  }
 329 \&
 330 \&  # Close the handle associated with the resource.
 331 \&  sub close_uri {
 332 \&      my $handler = shift;
 333 \&      close($handler);
 334 \&  }
 335 \&
 336 \&  # Register them with a instance of XML::LibXML::InputCallback
 337 \&  my $input_callbacks = XML::LibXML::InputCallback\->new();
 338 \&  $input_callbacks\->register_callbacks([ \e&match_uri, \e&open_uri,
 339 \&                                         \e&read_uri, \e&close_uri ] );
 340 \&
 341 \&  # Register the callback group at a parser instance
 342 \&  $parser\->input_callbacks( $input_callbacks );
 343 \&
 344 \&  # $some_xml_file will be parsed using our callbacks
 345 \&  $parser\->parse_file( $some_xml_file );
 346 .Ve
 347 .SH "AUTHORS"
 348 .IX Header "AUTHORS"
 349 Matt Sergeant,
 350 Christian Glahn,
 351 Petr Pajas
 352 .SH "VERSION"
 353 .IX Header "VERSION"
 354 1.70
 355 .SH "COPYRIGHT"
 356 .IX Header "COPYRIGHT"
 357 2001\-2007, AxKit.com Ltd.
 358 .PP
 359 2002\-2006, Christian Glahn.
 360 .PP
 361 2006\-2009, Petr Pajas.