NAME
Ryu::Buffer - accumulate data
DESCRIPTION
Provides a simple way to push bytes or characters into a buffer, and get them back out again.
Typically of use for delimiter-based or fixed-size protocols.
See also Future::Buffer, if you're dealing exclusively with Future instances and don't need the Ryu::Source functionality then that's likely to be a better option.
METHODS
new
Instantiates a new, empty Ryu::Buffer.
METHODS - Reading data
These methods provide ways of accessing the buffer either destructively (read*) or non-destructively (peek*).
read_exactly
Reads exactly the given number of bytes or characters.
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.
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.
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.
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.
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.
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.
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.
data
Accessor for the internal buffer. Not recommended to use this, but if you break it you get to keep all the pieces.
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.
INHERITED METHODS
AUTHOR
Tom Molesworth <TEAM@cpan.org>
LICENSE
Copyright Tom Molesworth 2011-2023. Licensed under the same terms as Perl itself.