Crypt:...:Handle(3pm)

💖 Crypt::Random::Source::Base::Handle — the manual, but make it cute 💖

okay bestie so this is Crypt::Random::Source::Base::Handle, from the Perl user-contributed docs, and it's literally the IO::Handle-based random data sources situation. no cap, this one's a whole vibe. 🎀

---

✨ VERSION ✨

version 0.14 🦋 (she's vintage, she's iconic, we respect her)

---

🌸 SYNOPSIS 🌸

okay so here's how you'd actually use her:

use Moo;
extends qw(Crypt::Random::Source::Base::Handle);

sub open_handle {
    # invoked as needed
}

# this class can also be used directly
Crypt::Random::Source::Base::Handle->new( handle => $file_handle );

# it supports some standard methods:

$p->blocking(0);

$p->read( my $buf, $n ); # no error handling here

not me pointing out that last comment — read really does NOT do error handling, that's just how it is, get is the one with the manners 💅

---

👑 DESCRIPTION 👑

This is a concrete base class for all IO::Handle based random data sources. fr fr, that's her whole job. She's the blueprint, the main character, the template all the other handle-y random sources build on. 🌈

She implements error handling. ✨ (yes queen, that's the whole sentence, she's efficient)

---

🦋 ATTRIBUTES 🦋

handle

An IO::Handle or file handle to read from. That's it, that's the whole thing. 💜

blocking

ngl this one is actually handled by handle itself — it's documented over in IO::Handle. So like, go read that page, bestie, she's just vibing here. 🌸

allow_under_read

Whether or not under reading is considered an error. 👀

Defaults to false.

reread_attempts

The number of attempts to make at rereading if the handle did not provide enough bytes on the first attempt.

Defaults to 1.

⚠️ Only used if allow_under_read is enabled. so like, don't set it and expect it to do anything unless you also flipped allow_under_read on. periodt.

---

💅 METHODS 💅

get

See "get" in Crypt::Random::Source::Base.

When blocking or allow_under_read are set to a true value this method may return fewer bytes than requested. 🫶 so heads up, she might give you less than you asked for and that's allowed, not a glitch.

read

This delegates directly to handle. 🎀

It DOES NOT provide the same validation as get would have, so no checking for underreads is done. 💀 no safety net, no vibe check, just raw delegation, iykyk.

close

Close the handle and clear it. bye bestie 👋 she's gone, she's cleared, it's over.

_read

$self->handle->read but with additional error checking and different calling conventions. 🔥 the underscore means she's private, so like, she's for internal use, but she's still doing the most.

_read_too_short

Called by _read when not enough data was read from the handle. Normally it will either die with an error or attempt to reread. When allow_under_read is true it will just return the partial buffer. 😭

so like, tl;dr: either she panics, she tries again, or — if you told her underreading is fine — she just hands you the partial thing and moves on. iconic behaviour honestly.

open_handle

Abstract method, should return an IO::Handle to use. 🧚 this one's abstract, so you gotta implement it yourself, bestie, she's not gonna do it for you.

---

🌈 SUPPORT 🌈

Bugs may be submitted through the RT bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=Crypt-Random-Source> (or bug-Crypt-Random-Source@rt.cpan.org <mailto:bug-Crypt-Random-Source@rt.cpan.org>).

found a bug? go tell the tracker, don't suffer in silence, we're all friends here 💖

---

⭐ AUTHOR ⭐

XXXX XXX'XX (Yuval Kogman) <nothingmuch@woobling.org> — yeah the name's literally redacted in the source, we love a mystery, she's giving anonymous royalty 👑

---

💜 COPYRIGHT AND LICENCE 💜

This software is copyright (c) 2008 by Yuval Kogman.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🌸 so like, go forth, remix, redistribute, slay responsibly.

---

and that's the whole page, bestie!! 🎀 this was generated from perl v5.34.0 and dated 2022-04-09, so like, that's the version energy we're running on. mwah, go read some random bytes responsibly 💖✨