Provided by: libstring-bufferstack-perl_1.16-3_all bug

NAME

       String::BufferStack - Nested buffers for templating systems

SYNOPSIS

         my $stack = String::BufferStack->new;
         $stack->push( filter => sub {return uc shift} );
         $stack->append("content");
         $stack->flush_output;

DESCRIPTION

       "String::BufferStack" provides a framework for storing nested buffers.  By default, all of
       the buffers flow directly to the output method, but individual levels of the stack can
       apply filters, or store their output in a scalar reference.

METHODS

   new PARAMHASH
       Creates a new buffer stack and returns it.  Possible arguments include:

       prealoc
           Preallocate this many bytes in the output buffer.  This can reduce reallocations, and
           thus speed up appends.

       out_method
           The method to call when output trickles down to the bottom-most buffer and is flushed
           via flush_output.  The default "out_method" prints the content to "STDOUT".  This
           method will always be called with non-undef, non-zero length content.

       use_length
           Calculate length of each buffer as it is built.  This imposes a significant runtime
           cost, so should be avoided if at all possible.  Defaults to off.

   push PARAMHASH
       Pushes a new frame onto the buffer stack.  By default, the output from this new frame
       connects to the input of the previous frame.  There are a number of possible options:

       buffer
           A string reference, into which the output from this stack frame will appear.  By
           default, this is the input buffer of the previous frame.

       private
           If a true value is passed for "private", it creates a private string reference, and
           uses that as the buffer -- this is purely for convenience.  That is, the following
           blocks are equivilent:

             my $buffer = "";
             $stack->push( buffer => \$buffer );
             # ...
             $stack->pop;
             print $buffer;

             $stack->push( private => 1 );
             # ...
             print $stack->pop;

       pre_append
           A callback, which will be called with a reference to the "String::BufferStack" object,
           and the arguments to append, whenever this stack frame has anything appended to the
           input buffer, directly or indirectly.

           Within the context of the pre-append callback, "append", "direct_append", and
           "set_pre_append" function on the frame the pre-append is attached to, not the topmost
           trame.  Using "append" within the pre-append callback is not suggested; use
           "direct_append" instead.  "set_pre_append" can be used to alter or remove the pre-
           append callback itself -- this is not uncommon, in the case where the first append is
           the only one which needs be watched for, for instance.

       filter
           A callback, used to process data which is appended to the stack frame.  By default,
           filters are lazy, being called only when a frame is popped.  They can be forced at any
           time by calling "flush_filters", however.

   depth
       Returns the current depth of the stack.  This starts at 0, when no frames have been
       pushed, and increases by one for each frame pushed.

   append STRING [, STRING, ...]
       Appends the given strings to the input side of the topmost buffer.  This will call all
       pre-append hooks attached to it, as well.  Note that if the frame has a filter, the filter
       will not immediately run, but will be delayed until the frame is "pop"'d, or
       "flush_filters" is called.

       When called with no frames on the stack, appends the stringins directly to the
       "output_buffer".

   direct_append STRING [, STRING, ...]
       Similar to "append", but appends the strings to the output side of the frame, skipping
       pre-append callbacks and filters.

       When called with no frames on the stack, appends the strings directly to the
       "output_buffer".

   pop
       Removes the topmost frame on the stack, flushing the topmost filters in the process.
       Returns the output buffer of the frame -- note that this may not contain only strings
       appended in the current frame, but also those from before, as a speed optimization.  That
       is:

          $stack->append("one");
          $stack->push;
          $stack->append(" two");
          $stack->pop;   # returns "one two"

       This operation is a no-op if there are no frames on the stack.

   set_pre_append CALLBACK
       Alters the pre-append callback on the topmost frame.  The callback will be called before
       text is appended to the input buffer of the frame, and will be passed the
       "String::BufferStack" and the arguments to "append".

   set_filter FILTER
       Alters the filter on the topmost frame.  Doing this flushes the filters on the topmost
       frame.

   filter
       Filters the topmost stack frame, if it has outstanding unfiltered data.  This will
       propagate content to lower frames, possibly calling their pre-append hooks.

   flush
       If there are no frames on the stack, calls "flush_output".  Otherwise, calls
       "flush_filters".

   flush_filters
       Flushes all filters.  This does not flush output from the output buffer; see
       "flush_output".

   buffer
       Returns the contents of the output buffer of the topmost frame; if there are no frames,
       returns the output buffer.

   buffer_ref
       Returns a reference to the output buffer of the topmost frame; if there are no frames,
       returns a reference to the output buffer.  Note that adjusting this skips pre-append and
       filter hooks.

   length
       If "use_length" was enabled in the buffer stack's constructor, returns the number of
       characters appended to the current frame; if there are no frames, returns the length of
       the output buffer.

       If "use_length" was not enabled, warns and returns 0.

   flush_output
       Flushes all filters using "flush_filters", then flushes output from the output buffer,
       using the configured "out_method".

   output_buffer
       Returns the pending output buffer, which sits below all existing frames.

   output_buffer_ref
       Returns a reference to the pending output buffer, allowing you to modify it.

   clear
       Clears all buffers in the stack, including the output buffer.

   clear_top
       Clears the topmost buffer in the stack; if there are no frames on the stack, clears the
       output buffer.

   out_method [CALLBACK]
       Gets or sets the output method callback, which is given content from the pending output
       buffer, which sits below all frames.

SEE ALSO

       Many concepts were originally taken from HTML::Mason's internal buffer stack.

AUTHORS

       Alex Vandiver "alexmv@bestpractical.com"

LICENSE

       Copyright 2008-2009, Best Practical Solutions.

       This package is distributed under the same terms as Perl itself.