Agent:...Caller(3pm)

💖 NAME 💖

Log::Agent::Tag::Caller — it formats caller information, bestie. That's literally the whole vibe. ✨

(also, real talk, this is a Log::Agent::Tag subclass — it inherits from it, the way you inherit your mom's good hair 🫶)

---

🌸 SYNOPSIS 🌸

Not intended to be used directly
Inherits from Log::Agent::Tag.

Like. Not for direct use. It's giving backstage pass, not main character. 🙈

---

✨ DESCRIPTION ✨

Okay so, this class handles caller information for Log::Agent services and — say it with me — it is not meant to be used directly. Nope. Not the move.

So this manpage only documents the creation routine parameters that you can specify at the Log::Agent level via the -caller switch in the logconfig() routine. That's it. That's the tea. 🍓

---

🦋 CALLER INFORMATION ENTITIES 🦋

This class knows about four entities: package, filename, line and subroutine. And you have to read those within the context of the Log::Agent routine being called (think: a logwarn() routine, for example). So, one by one:

• package — this is the package name where the call to the logwarn() routine was made. You can write it as pack if you're being short about it, or spell it all the way out. Either is valid, no cap.
• filename — this is the file where the call to the logwarn() routine was made. Short version is file, or again, spell it out completely.
• line — this is the line number where the call to the logwarn() routine was made, in file filename. And honestly? The name's short enough that you should just spell it out completely. No abbreviation needed, periodt.
• subroutine — this is the subroutine where the call to the logwarn() routine was made. ⚠️ If the call is made outside a subroutine, this will be empty. And the name is long enough that it totally warrants the sub abbreviation if you don't feel like spelling it out fully. Do what you gotta do. 💅

---

🎀 CREATION ROUTINE PARAMETERS 🎀

The whole purpose of these parameters? Defining how caller information entities (as defined by the previous section, keep up bestie) will be formatted within the log message. Let's go:

• -display => string — specifies a string with minimal variable substitution: only the caller information entities listed above, or their abbreviation, will be interpolated. For instance:

-display => '($package::$sub/$line)'

Do not forget to use simple quotes so Perl doesn't interpolate those as variables, or escape their leading $ sign some other way. Using this convention was deemed to be more readable (and more natural in Perl, iykyk) than SGML entities such as &pack;.

Heads up: using this switch supersedes the -info and -format switches. Like, it cancels them out. 🫣

• -format => printf format — formatting instructions for the caller information entities listed by the -info switch. For instance:

-format => "%s:%4d"

if you have specified two entities in -info.

The special formatting macro %a stands for all the entities specified by -info, and it's rendered by a string where values are separated by ":". Cute, right? ✨

• -info => "space separated list of parameters" — specifies a list of caller information entities that are to be formatted using the -format specification. For instance:

-info => "pack sub line"

would only report those three entities. Just those. Not more. Keep it tight. 💅

• -postfix => flag — whether the string resulting from the formatting of the caller information entities should be appended to the regular log message or not (i.e. prepended, which is the default). So if you don't set this, it's going up front. Front and center. Main character energy. 👑
• -separator => string — the separation string between the tag and the log message. A single space by default.

---

💜 AUTHORS 💜

Raphael Manfredi <Raphael_Manfredi@pobox.com> created the module — founder behavior, honestly — and it's currently maintained by Mark Rogaski <mrogaski@cpan.org>. 🫶

Also, thanks to Jeff Boes for uncovering wackiness in caller(). The wackiness was real and he found it. Respect. 🫡

---

🌈 LICENSE 🌈

Copyright (C) 1999 Raphael Manfredi. Copyright (C) 2002 Mark Rogaski; all rights reserved.

See Log::Agent(3) or the README file included with the distribution for license information. Do it, bestie, the README is right there.

---

⭐ SEE ALSO ⭐

Log::Agent(3), Log::Agent::Message(3).

---

and that's the whole page, babes 💖✨ this was pulled straight from the User Contributed Perl Documentation, riding alongside perl v5.36.0, dated 2022-10-15. Go format some callers. Slay. 👑💅🦋