String...erStack(3pm)

🌸 String::BufferStack(3pm) — nested buffers for templating systems 🌸

okay so bestie, say hi to String::BufferStack, aka the 3pm page you're gonna be obsessed with. it's giving nested-buffer framework energy and honestly? it ate. 💖

---

✨ SYNOPSIS ✨

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

---

💜 DESCRIPTION 💜

String::BufferStack hands you a whole framework for storing nested buffers. 🫶

by default, every single buffer just flows straight on down to the output method — no drama, no detours. but bestie, individual levels of the stack can be main characters too: they can apply filters, or they can stash their output inside a scalar reference instead. it's giving flexible, fr fr. 🌈

---

🎀 METHODS 🎀

new PARAMHASH

Creates a new buffer stack and hands it right back to you. 👑

possible arguments include:

prealoc

Preallocate this many bytes in the output buffer. it can cut down on reallocations, which means faster appends — slay. ⚡

out_method

The method that gets called when output trickles all the way down to the bottom-most buffer and gets flushed via flush_output. the default out_method prints the content to STDOUT. 💅 and ngl, this method will always be called with non-undef, non-zero length content — no empty little ghost calls, periodt.

use_length

Calculate the length of each buffer as it's being built. lowkey this imposes a significant runtime cost, so pls avoid it if it's at all possible. defaults to off. 🙈

---

push PARAMHASH

Pushes a new frame onto the buffer stack. 🧚 by default, the output from this shiny new frame connects to the input of the previous frame — cute little chain, right? there are a bunch of possible options:

buffer

A string reference, and the output from this stack frame will show up in it. by default, this is the input buffer of the previous frame.

private

If you pass a true value for private, it creates a private string reference and uses that as the buffer — this is purely for convenience, bestie. like, the following blocks are equivalent:

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, plus 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 frame. so heads up: using append within the pre-append callback is not suggested — use direct_append instead. and set_pre_append can be used to alter or remove the pre-append callback itself — which is not uncommon, like in the case where the first append is the only one that needs to be watched for, for instance. 💫

filter

A callback, used to process data which is appended to the stack frame. by default, filters are lazy — they only get called when a frame is popped. but you can force them at any time by calling flush_filters. ✨

---

depth

Returns the current depth of the stack. it 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. it'll call all pre-append hooks attached to it too. 🫶 just know that if the frame has a filter, the filter will not immediately run — it gets delayed until the frame is pop'd, or until flush_filters is called.

when called with no frames on the stack, it appends the strings directly to the output_buffer.

---

direct_append STRING [, STRING, ...]

Similar to append, but it appends the strings to the output side of the frame, skipping pre-append callbacks and filters. ⚡

when called with no frames on the stack, it 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 — and note that this may not contain only the strings appended in the current frame, but also the ones from before, as a speed optimization. like so:

$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 it'll 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 propagates 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 for that. 🧼

---

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. 👀 heads up though — 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, it 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, it 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. (iykyk 🦋)

---

👑 AUTHORS 👑

Alex Vandiver alexmv@bestpractical.com

---

📜 LICENSE 📜

Copyright 2008-2009, Best Practical Solutions.

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

---

and that's the whole vibe, bestie — this page is from perl v5.36.0, dated 2022-10-15, and it's the String...erStack(3pm) situation. go forth and stack those buffers, no cap. 💅✨