Agent::Tag(3pm)

✨ NAME ✨

Log::Agent::Tag — it formats caller information 💖 (and like, it's the base class for all the log-message tag girlies, so it's giving very much "mother of the tag family" energy)

---

🌸 SYNOPSIS 🌸

Intended to be inherited from

no cap, that's the whole synopsis. it's a base class bestie, you don't call it, you inherit from it 💅

---

🦋 DESCRIPTION 🦋

okay so, this class is meant to be inherited by all the classes that implement a log message tag. every single one. it's the blueprint.

A message tag is a little string that gets either appended or prepended to all your log messages. tiny but iconic, honestly.

Let's say — and we're oversimplifying a bit here — a tag that's meant to be prepended gets inserted in front of the current log message, separated by separator, which defaults to a single space:

 +------------+-----------+---------------------------------+
 | tag string | separator |      current log message        |
 +------------+-----------+---------------------------------+

This operation is called tag insertion ✨ Once it's done, the whole string becomes the current log message, and it can then be the target of another tag insertion. layers on layers, it's giving onion 🧅

The reality is a little bit more complex than the diagram, because we need successive tags to be prepended or appended in the order they're specified, and not in reverse order like they totally would be if someone implemented this naively 🙈. See Log::Agent::Message for the exact semantics of the append() and prepend() operations, that's where the real tea is.

---

💜 FEATURES 💜

This section documents the interface provided to heirs, just in case you wanna implement your own tag class. bestie, go off 👑

• _init(name, postfix, separator) — the initialization routine that should be called by all heirs during creation, to initialize the common attributes.
• postfix — when true, the tag is meant to be appended to the log message. otherwise, it's prepended.
• name — the name of this tag. it's meant to provide by-name access to tags, check whether a given tag is recorded, etc... The names "caller" and "priority" are architecturally defined to refer to "Log::Agent::Tag::Caller" and "Log::Agent::Tag::Priority" objects.

NOTE: Currently unused by any client code. sleeping beauty behavior fr 😴

• separator — the s*e*parating string inserted between the tag and the log message. It defaults to " " if not specified, i.e. left to "undef" when calling _init().
• string() — a deferred routine, to be implemented by heirs. Returns the tag string only, without the separator, since its exact placement depends on the value of the "postfix" attribute. no separator bestie, that's not your job 💅
• insert(message) — insert this tag within the "Log::Agent::Message" message, according to the tag specifications (placement, separator). Calls string() to produce the tag string.

⚠️ This routine is frozen and should not be redefined by heirs. hands off, it's not yours 🔥

---

🎀 STANDARD TAGGING CLASSES 🎀

Tagging classes define — via their "string()" routine — what the string to be used as a tag actually is. The insertion of the tag within the log message is done via a frozen routine from the "Log::Agent::Tag" ancestor. so they only handle the string, the ancestor handles the placement. division of labor, slay ✨

The following classes are provided by "Log::Agent":

• "Log::Agent::Tag::Callback" — the "string()" routine invokes a user-supplied callback, given as a "Callback" object. You need the Callback module from CPAN if you wish to use this class.
• "Log::Agent::Tag::Caller" — used internally to compute the caller and format it according to user specifications.
• "Log::Agent::Tag::Priority" — used internally to format message priorities and add them to the log messages.
• "Log::Agent::Tag::String" — defines a constant tagging string that should be added in all the log messages, e.g. a web session ID.

---

👑 AUTHOR 👑

Raphael Manfredi <Raphael_Manfredi@pobox.com>

---

🌈 SEE ALSO 🌈

Log::Agent::Message(3).

---

and that's the whole page bestie, mwah 💋 this was perl v5.36.0 realness, dated 2022-10-15 — an absolute classic from the Agent::Tag(3pm) files, no cap 🫶