Agent:...Handle(3pm)

💖 Log::Agent::Channel::Handle — the I/O handle logging channel for Log::Agent 💖

okay bestie so this is Log::Agent::Channel::Handle, a lil Perl module from the User Contributed Perl Documentation corner of the world, and it's literally the thing that lets Log::Agent yell into an I/O handle you already opened. let's get into it 🫶

---

✨ SYNOPSIS ✨

require Log::Agent::Channel::Handle;

my $driver = Log::Agent::Channel::Handle->make(
    -prefix     => "prefix",
    -stampfmt   => "own",
    -showpid    => 1,
    -handle     => \*FILE,
);

like. that's it. that's the whole vibe. 🌸

---

💅 DESCRIPTION 💅

okay so the handle channel does one thing and it does it iconically: it logs to an already opened I/O handle, and it handles all the necessary prefixing and stamping of the messages on the way out. no cap. 👑

the creation routine make() takes the following arguments, and yes we're going through every single one because that's the whole point:

• -handle => handle — specifies the I/O handle to use 🎀. it can be given as a GLOB reference, like \*FILE, or as an IO::Handle object. super flexible, we love that for us.

⚠️ NOTE: auto-flushing is not enabled on the handle. and even when the channel is closed, the handle is left as-is — we literally just stop sending log messages to it. that's it, that's the break-up, no further changes to your handle, periodt.

• -no_newline => flag — when you set this to true, we never append any "\n" (on Unix) or "\r\n" (on Windows) to log messages 🚫😭.

internals tea: Log::Agent relies on the channel to delimit logged lines appropriately, so this flag is not used. however, it might be useful for Log::Agent::Logger users. so like, it's here if you need it iykyk.

default is false, meaning newline markers are systematically appended. 💀

• -no_prefixing => flag — when true, the prefixing logic is disabled entirely, i.e. these options are ignored completely: -prefix, -showpid, -no_ucfirst, -stampfmt. all of them. gone. ghosted. 👻

default is false.

• -no_ucfirst => flag — when true, don't upper-case the first letter of the log message entry when there's no prefix inserted before the logged line. because when there is a prefix, a ":" character follows, and therefore the leading letter of the message should not be upper-cased anyway. grammar girlies rise 🙈

default is false, meaning uppercasing is performed.

• -prefix => prefix — the application prefix string to prepend to messages. that's it, that's the assignment. ✨
• -showpid => flag — if true, the PID of the process gets appended within square brackets after the prefix, on all messages. main character energy, every line knows whose it is 👑

default is false.

• -stampfmt => (name | CODE) — specifies the time stamp format to use 🕐. by default, the "own" format is used. see Log::Agent::Stamping for a description of the available format names.

you may also specify a CODE ref: that routine will be called every time we need to compute a time stamp. it should not expect any parameter, and should return a string. custom timestamps, slay 💅

---

🚨 CAVEAT 🚨

beware of chdir(). fr fr. 😭

if your program uses chdir(), you should always specify logfiles by using absolute paths, otherwise you run the risk of having your relative paths become invalid: there is no anchoring done at the time you specify them.

this is especially true when configured for rotation, since the logfiles are recreated as needed and you might end up with many logfiles scattered throughout all the directories you chdir()ed to. 💀 a whole trail of chaos. use absolute paths bestie i am begging 🫶

---

👑 AUTHOR 👑

Raphael Manfredi <Raphael_Manfredi@pobox.com>

---

🦋 SEE ALSO 🦋

• Log::Agent::Logger(3)
• Log::Agent::Channel(3)

---

and that's the page gorgeous ✨ it's Perl v5.36.0, dated 2022-10-15, from the User Contributed Perl Documentation — so like, if you ever forget a flag, this is your girl 💖 mwah, go log something 🌈🎀