NAME¶
Log::Agent::Tag - formats caller information
SYNOPSIS¶
Intended to be inherited from
DESCRIPTION¶
This class is meant to be inherited by all the classes implementing a log
message tag.
A message tag is a little string that is either appended or prepended to all log
messages.
For instance, and oversimplifying a bit, a tag meant to be prepended will be
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. The whole string then becomes the
current log message, and can be the target of another tag insertion.
The reality is a little bit more complex, to allow successive tags to be
prepended or appended in the order they are specified, and not in reverse
order as they would be if naively implemented. See Log::Agent::Message for the
exact semantics of
append() and
prepend() operations.
FEATURES¶
This section documents the interface provided to heirs, in case you wish to
implement your own tag class.
- _init(name, postfix, separator)
- 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 is prepended.
- name
- The name of this tag. It is 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.
- separator
- The sperating 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.
- insert(message)
- Insert this tag withing 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.
STANDARD TAGGING CLASSES¶
Tagging classes define via their "string()" routine what is the string
to be used as a tag. The insertion of the tag within the log message is done
via a frozen routine from the "Log::Agent::Tag" ancestor.
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).