HTML::Mason::Buffer(3)

NAME
HTML::Mason::Buffer - Objects for Handling Component Output

SYNOPSIS
  my $buffer = HTML::Mason::Buffer->new( sink => sub { print @_ } );

  my $child = $buffer->new_child;

  $child->receive( 'foo', 'bar' );

DESCRIPTION
Mason's buffer objects handle all output generated by components. They are used to implement "<%filter>" blocks, the "$m->scomp" method, the "store" component call modifier, and content-filtering component feature.

Buffers can either store output in a scalar, internally, or they can be given a callback to call immediately when output is generated.

Most users will never have to deal with buffer objects directly, but will instead use Request object methods such as "print" or "clear_buffer".

CONSTRUCTOR
Buffer objects can be constructed in two different ways. Like any other Mason object, they can be created via their "new" method.

This method takes several parameters, all of them optional.

sink
    This should be either a subroutine reference or a scalar reference.

    If this is a subroutine reference, then any output received by the buffer will be passed to this subroutine reference as a list of one or more items.

    If this is a scalar reference, then data will be concatenated onto this scalar as it is received.

    If no parameter is given, then output will be buffered internally, to be retrieved by the "output" method.

ignore_flush
    If this parameter is true, then the created buffer will ignore calls to its "flush" method. This parameter defaults to true for buffers created via the "new" method, and false for those created via the "new_child" method.

filter
    This parameter should be a subroutine reference which should expect to receive a single argument, the output to be filtered. It should return the output after transforming it in any way it desires.

New buffers can also be created via the "new_child" method, which takes the same parameters as the "new" method. The "new_child" method is an object method, not a class method.

It creates a new buffer object which will eventually pass its output to the buffer object that created it.

This allows you to create a stack of buffers.

METHODS

receive
    This method takes a list of items to be sent to the buffer's sink.

flush
    This method tells the buffer to pass any output it may currently have stored internally to its parent, if it has one. It then clears the buffer.

    This method does nothing if the buffer does not have any stored output, which is the case for buffers that were given a subroutine reference as their "sink" argument.

clear
    For buffers which store output internally, this clears any pending output.

output
    For buffers which store output internally, this returns any pending output, possibly passing it through a buffer's filter, if it has one. This does not clear the buffer.