.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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" ''
.    ds C`
.    ds C'
'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 >0, 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.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "XML::Filter::Sort::Buffer 3pm"
.TH XML::Filter::Sort::Buffer 3pm "2018-03-30" "perl v5.26.1" "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::Buffer \- 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
For an overview of the classes and methods used for buffering, see
XML::Filter::Sort::BufferMgr.
.SH "BUFFER LIFE CYCLE"
.IX Header "BUFFER LIFE CYCLE"
A \fBXML::Filter::Sort::Buffer\fR object is created by a
\&\fBXML::Filter::Sort::BufferMgr\fR object using the \f(CW\*(C`new()\*(C'\fR method.
.PP
The \fBXML::Filter::Sort\fR object will then propagate any \s-1SAX\s0 events it receives,
to the buffer object until the end of the record is reached.  As each element
is added to the buffer, its contents are compared to the sort key paths and the
sort key values are extracted.
.PP
When the end of the record is reached, the \f(CW\*(C`close()\*(C'\fR method is called.  The
return value from this method is the list of sort keys.
.PP
The buffer manager will store the buffer until the end of the record sequence
is reached.  Then it will retrieve each buffer in order of the sort key values
and call the buffer's \f(CW\*(C`to_sax()\*(C'\fR method to send all buffered events to the
downstream handler.
.PP
Following the call to \f(CW\*(C`to_sax()\*(C'\fR, the buffer is discarded.  No destructor
method is used \- everything is handled by Perl's garbage collector.
.SH "DATA STRUCTURES"
.IX Header "DATA STRUCTURES"
The buffer contains a 'tree' of \s-1SAX\s0 events.  The tree is simply an array
of 'nodes'.  Text nodes are represented as scalars.  Other nodes are
represented as arrayrefs.  The first element of a node array is a single
character identifying the node type:
.PP
.Vb 3
\&  e \- element
\&  c \- comment
\&  p \- processing instruction
.Ve
.PP
The second element is the node data (the hash from the original \s-1SAX\s0 event).
The child nodes of an element node are represented by the third element as
an arrayref.
.PP
For example, this \s-1XML:\s0
.PP
.Vb 3
\&  <person age="27">
\&    <lastname>smith</lastname>
\&  </person>
.Ve
.PP
Would be buffered as this data structure:
.PP
.Vb 10
\&  [
\&    [
\&      \*(Aqe\*(Aq,
\&      {
\&        \*(AqName\*(Aq => \*(Aqperson\*(Aq
\&        \*(AqPrefix\*(Aq => \*(Aq\*(Aq,
\&        \*(AqLocalName\*(Aq => \*(Aqperson\*(Aq,
\&        \*(AqNamespaceURI\*(Aq => \*(Aq\*(Aq,
\&        \*(AqAttributes\*(Aq => {
\&          \*(Aq{}age\*(Aq => {
\&            \*(AqLocalName\*(Aq => \*(Aqage\*(Aq,
\&            \*(AqNamespaceURI\*(Aq => \*(Aq\*(Aq,
\&            \*(AqValue\*(Aq => \*(Aq27\*(Aq,
\&            \*(AqPrefix\*(Aq => \*(Aq\*(Aq,
\&            \*(AqName\*(Aq => \*(Aqage\*(Aq
\&          }
\&        },
\&      },
\&      [
\&        "\en  ",
\&        [
\&          \*(Aqe\*(Aq,
\&          {
\&            \*(AqName\*(Aq => \*(Aqlastname\*(Aq
\&            \*(AqPrefix\*(Aq => \*(Aq\*(Aq,
\&            \*(AqLocalName\*(Aq => \*(Aqlastname\*(Aq,
\&            \*(AqNamespaceURI\*(Aq => \*(Aq\*(Aq,
\&            \*(AqAttributes\*(Aq => {},
\&          },
\&          [
\&            \*(Aqsmith\*(Aq
\&          ]
\&        ],
\&        "\en  ",
\&      ]
\&    ]
\&  ]
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2002 Grant McLean <grantm@cpan.org>
.PP
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.