HTML::Mason::Buffer - Objects for Handling Component Output
my $buffer = HTML::Mason::Buffer->new( sink => sub { print @_ } );
my $child = $buffer->new_child;
$child->receive( 'foo', 'bar' );
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.
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.
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.
flush method. This parameter defaults to true for buffers
created via the new method, and false for those created via the
new_child method.
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.
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.