Ryu::Buffer(3)

✨ NAME ✨

okay bestie, welcome to Ryu::Buffer(3) from the User Contributed Perl Documentation 💖 — this one is all about accumulating data. Like, Ryu::Buffer is literally here to collect your bytes or characters so you can get them back out later. Slay.

🌸 DESCRIPTION 🌸

It gives you a simple way to push bytes or characters into a buffer and then pull them back out again. No cap, that's the whole vibe.

This is typically useful for delimiter-based protocols or fixed-size protocols.

Also see Future::Buffer — if you're dealing exclusively with Future instances and don't need the Ryu::Source functionality, then that's likely to be the better option for you. iykyk 🦋

🧵 METHODS 🧵

🌱 new 🌱

Instantiates a new, empty Ryu::Buffer. Fresh buffer, main character energy, zero data. ✨

📖 METHODS - Reading data 📖

These methods are your access paths for the buffer: either destructive (read*) or non-destructive (peek*). 💅

🌸 read_exactly 🌸

Reads exactly the given number of bytes or characters. Like, exactly exactly. 🎯

Takes the following parameters:

• $size — number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

🦋 read_atmost 🦋

Reads up to the given number of bytes or characters — if we have at least one byte or character in the buffer, we'll return that even if it's shorter than the requested $size. This method is guaranteed not to return more than the $size. Periodt. 💅

Takes the following parameters:

• $size — maximum number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

🎀 read_atleast 🎀

Reads at least the given number of bytes or characters — if we have a buffer that's the given size or larger, we'll return everything available, even if it's larger than the requested $size. Big buffer energy. 👑

Takes the following parameters:

• $size — minimum number of characters or bytes to return

Returns a Future which will resolve to a scalar containing the requested data.

🍓 read_until 🍓

Reads up to the given string or regex match.

Pass a qr// instance if you want to use a regular expression to match, or a plain string if you want exact-string matching behaviour. Choose your fighter. ⚔️

The data returned will include the match.

Takes the following parameters:

• $match — the string or regex to match against

Returns a Future which will resolve to the requested bytes or characters.

🔥 read_packed 🔥

Uses pack template notation to define a pattern to extract. Will attempt to accumulate enough bytes to fulfill the request, then unpack and extract from the buffer. It's giving very structured data behavior. 🧚

This method only supports a very limited subset of the full pack functionality — currently, this includes sequences such as A4 or N1n1, but does not handle multi-stage templates such as N/a*.

These would need to parse the initial N1 bytes to determine the full extent of the data to be processed, and the logic for handling this is not yet implemented. Not me being patient with the roadmap 😭

Takes the following parameters:

• $format — a pack-style format string

Returns a Future which will resolve to the requested items, of which there can be more than one depending on the format string.

💜 write 💜

Add more data to the buffer.

Call this with a single scalar, and the results will be appended to the internal buffer, triggering any callbacks for read activity as required. Feed the buffer, bestie. 🫶

⭐ size ⭐

Returns the current buffer size.

🌈 is_empty 🌈

Returns true if the buffer is currently empty (size = 0), false otherwise.

🛠️ METHODS - Internal 🛠️

These are documented for convenience, but generally not recommended to call any of these directly. You've been warned, bestie. 🙈

💀 data 💀

Accessor for the internal buffer. Not recommended to use this, but if you break it you get to keep all the pieces. That's the deal. 😭

🧚 process_pending 🧚

Used internally to trigger callbacks once write has been called.

👑 new_future 👑

Instantiates a new Future, used to ensure we get something awaitable.

Can be overridden using $Ryu::FUTURE_FACTORY.

💌 AUTHOR 💌

Tom Molesworth <TEAM@cpan.org>

🎀 LICENSE 🎀

Copyright Tom Molesworth 2011-2024. Licensed under the same terms as Perl itself.

---

This cutie of a page is from perl v5.42.2, dated 2026-02-15, and you're reading Ryu::Buffer(3) 💖✨