1NAME
2 String::BufferStack - Nested buffers for templating systems
3
4SYNOPSIS
5 my $stack = String::BufferStack->new;
6 $stack->push( filter => sub {return uc shift} );
7 $stack->append("content");
8 $stack->flush_output;
9
10DESCRIPTION
11 "String::BufferStack" provides a framework for storing nested buffers.
12 By default, all of the buffers flow directly to the output method, but
13 individual levels of the stack can apply filters, or store their output
14 in a scalar reference.
15
16METHODS
17 new PARAMHASH
18 Creates a new buffer stack and returns it. Possible arguments include:
19
20 prealoc
21 Preallocate this many bytes in the output buffer. This can reduce
22 reallocations, and thus speed up appends.
23
24 out_method
25 The method to call when output trickles down to the bottom-most
26 buffer and is flushed via flush_output. The default "out_method"
27 prints the content to "STDOUT". This method will always be called
28 with non-undef, non-zero length content.
29
30 push PARAMHASH
31 Pushes a new frame onto the buffer stack. By default, the output from
32 this new frame connects to the input of the previous frame. There are a
33 number of possible options:
34
35 buffer
36 A string reference, into which the output from this stack frame will
37 appear. By default, this is the input buffer of the previous frame.
38
39 private
40 If a true value is passed for "private", it creates a private string
41 reference, and uses that as the buffer -- this is purely for
42 convenience. That is, the following blocks are equivilent:
43
44 my $buffer = "";
45 $stack->push( buffer => \$buffer );
46 # ...
47 $stack->pop;
48 print $buffer;
49
50 $stack->push( private => 1 );
51 # ...
52 print $stack->pop;
53
54 pre_append
55 A callback, which will be called with a reference to the
56 "String::BufferStack" object, and the arguments to append, whenever
57 this stack frame has anything appended to the input buffer, directly
58 or indirectly.
59
60 Within the context of the pre-append callback, "append",
61 "direct_append", and "set_pre_append" function on the frame the
62 pre-append is attached to, not the topmost trame. Using "append"
63 within the pre-append callback is not suggested; use "direct_append"
64 instead. "set_pre_append" can be used to alter or remove the
65 pre-append callback itself -- this is not uncommon, in the case
66 where the first append is the only one which needs be watched for,
67 for instance.
68
69 filter
70 A callback, used to process data which is appended to the stack
71 frame. By default, filters are lazy, being called only when a frame
72 is popped. They can be forced at any time by calling
73 "flush_filters", however.
74
75 depth
76 Returns the current depth of the stack. This starts at 0, when no frames
77 have been pushed, and increases by one for each frame pushed.
78
79 append STRING [, STRING, ...]
80 Appends the given strings to the input side of the topmost buffer. This
81 will call all pre-append hooks attached to it, as well. Note that if the
82 frame has a filter, the filter will not immediately run, but will be
83 delayed until the frame is "pop"'d, or "flush_filters" is called.
84
85 When called with no frames on the stack, appends the stringins directly
86 to the "output_buffer".
87
88 direct_append STRING [, STRING, ...]
89 Similar to "append", but appends the strings to the output side of the
90 frame, skipping pre-append callbacks and filters.
91
92 When called with no frames on the stack, appends the strings directly to
93 the "output_buffer".
94
95 pop
96 Removes the topmost frame on the stack, flushing the topmost filters in
97 the process. Returns the output buffer of the frame -- note that this
98 may not contain only strings appended in the current frame, but also
99 those from before, as a speed optimization. That is:
100
101 $stack->append("one");
102 $stack->push;
103 $stack->append(" two");
104 $stack->pop; # returns "one two"
105
106 This operation is a no-op if there are no frames on the stack.
107
108 set_pre_append CALLBACK
109 Alters the pre-append callback on the topmost frame. The callback will
110 be called before text is appended to the input buffer of the frame, and
111 will be passed the "String::BufferStack" and the arguments to "append".
112
113 set_filter FILTER
114 Alters the filter on the topmost frame. Doing this flushes the filters
115 on the topmost frame.
116
117 filter
118 Filters the topmost stack frame, if it has outstanding unfiltered data.
119 This will propagate content to lower frames, possibly calling their
120 pre-append hooks.
121
122 flush
123 If there are no frames on the stack, calls "flush_output". Otherwise,
124 calls "flush_filters".
125
126 flush_filters
127 Flushes all filters. This does not flush output from the output buffer;
128 see "flush_output".
129
130 buffer
131 Returns the contents of the output buffer of the topmost frame; if there
132 are no frames, returns the output buffer.
133
134 buffer_ref
135 Returns a reference to the output buffer of the topmost frame; if there
136 are no frames, returns a reference to the output buffer. Note that
137 adjusting this skips pre-append and filter hooks.
138
139 length
140 Returns the number of characters appended to the current frame; if there
141 are no frames, returns the length of the output buffer.
142
143 flush_output
144 Flushes all filters using "flush_filters", then flushes output from the
145 output buffer, using the configured "out_method".
146
147 output_buffer
148 Returns the pending output buffer, which sits below all existing frames.
149
150 output_buffer_ref
151 Returns a reference to the pending output buffer, allowing you to modify
152 it.
153
154 clear
155 Clears *all* buffers in the stack, including the output buffer.
156
157 clear_top
158 Clears the topmost buffer in the stack; if there are no frames on the
159 stack, clears the output buffer.
160
161 out_method [CALLBACK]
162 Gets or sets the output method callback, which is given content from the
163 pending output buffer, which sits below all frames.
164
165SEE ALSO
166 Many concepts were originally taken from HTML::Mason's internal buffer
167 stack.
168
169AUTHORS
170 Alex Vandiver "alexmv@bestpractical.com"
171
172LICENSE
173 Copyright 2008-2009, Best Practical Solutions.
174
175 This package is distributed under the same terms as Perl itself.
176
177