.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "XML::Filter::Sort::BufferMgr 3pm" .TH XML::Filter::Sort::BufferMgr 3pm "2002-06-14" "perl v5.12.4" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" XML::Filter::Sort::BufferMgr \- Implementation class used by XML::Filter::Sort .SH "DESCRIPTION" .IX Header "DESCRIPTION" The documentation is targetted at developers wishing to extend or replace this class. For user documentation, see XML::Filter::Sort. .PP Two classes are used to implement buffering records and spooling them back out in sorted order as \s-1SAX\s0 events. One instance of the \&\fBXML::Filter::Sort::Buffer\fR class is used to buffer each record and one or more instances of the \fBXML::Filter::Sort::BufferMgr\fR class are used to manage the buffers. .SH "API METHODS" .IX Header "API METHODS" The \s-1API\s0 of this module as used by \fBXML::Filter::Sort::Buffer\fR consists of the following sequence of method calls: .IP "1." 4 When the first 'record' in a sequence is encountered, \fBXML::Filter::Sort\fR creates a \fBXML::Filter::Sort::BufferMgr\fR object using the \f(CW\*(C`new()\*(C'\fR method. .IP "2." 4 \&\fBXML::Filter::Sort\fR calls the buffer manager's \f(CW\*(C`new_buffer()\*(C'\fR method to get a \&\fBXML::Filter::Sort::Buffer\fR object and all \s-1SAX\s0 events are directed to this object until the end of the record is encountered. The following events are supported by the current buffer implementation: .Sp .Vb 5 \& start_element() \& characters() \& comment() \& processing_instruction() \& end_element() .Ve .IP "3." 4 When the end of the record is detected, \fBXML::Filter::Sort\fR calls the buffer manager's \f(CW\*(C`close_buffer()\*(C'\fR method, which in turn calls the buffer's \f(CW\*(C`close()\*(C'\fR method. The \f(CW\*(C`close()\*(C'\fR method returns a list of values for the sort keys and the buffer manager uses these to store the buffer for later recall. Subsequent records are handled as per step 2. .IP "4." 4 When the last record has been buffered, \fBXML::Filter::Sort\fR calls the buffer manager's \f(CW\*(C`to_sax()\*(C'\fR method. The buffer manager retrieves each of the buffers in sorted order and calls the buffer's \f(CW\*(C`to_sax()\*(C'\fR method. .PP Each buffer attempts to match the sort key paths as \s-1SAX\s0 events are received. Once a value has been found for a given key, that same path match is not attempted against subsequent events. For efficiency, the code to match each key is compiled into a closure. For even more efficiency, this compilation is done once when the \fBXML::Filter::Sort\fR object is created. The \&\f(CW\*(C`compile_matches()\*(C'\fR method in the buffer manager class calls the \&\f(CW\*(C`compile_matches()\*(C'\fR method in the buffer class to achieve this. .SH "DATA STRUCTURES" .IX Header "DATA STRUCTURES" In the current implementation, the \fBXML::Filter::Sort::BufferMgr\fR class simply uses a hash to store the buffer objects. If only one sort key was defined, only a single hash is required. The values in the hash are arrayrefs containing the list of buffers for records with identical keys. .PP If two or more sort keys are defined, the hash values will be \&\fBXML::Filter::Sort::BufferMgr\fR objects which in turn will contain the buffers. The following illustration may clarify the relationship (BM=buffer manager, B=buffer): .PP .Vb 10 \& BM \& +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ \& | | \& BM BM \& +\-\-\-\-\-+\-\-\-\-\-\-\-\-+ +\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+ \& | | | | \& BM BM BM BM \& +\-\-\-\-\-+\-\-\-\-+ +\-\-\-\-+\-\-\-\-\-\-+ +\-\-\-\-+\-\-\-\-+ +\-\-\-\-\-\-+\-\-\-\-\-\-+ \& | | | | | | | | | | | | \& [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B] [B,B] [B] [B,B] [B,B,B] [B,B] .Ve .PP This layered storage structure is transparent to the \fBXML::Filter::Sort\fR object which instantiates and interacts with only one buffer manager (the one at the top of the tree). .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2002 Grant McLean .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.