Log::Me...:Simple(3)

💖 Log::Message::Simple(3) — like, the manual page, but make it make sense 🎀

okay so bestie, welcome to Log::Message::Simple, part of the User Contributed Perl Documentation crew ✨ this is the simplified interface to Log::Message, and honestly? it's giving "logging but make it cute". no cap.

---

🌸 NAME 🌸

Log::Message::Simple — a simplified interface to Log::Message. literally that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

here's the whole thing, copy-paste ready, i did not touch a single character:

    use Log::Message::Simple qw[msg error debug
                                carp croak cluck confess];

    use Log::Message::Simple qw[:STD :CARP];

    ### standard reporting functionality
    msg(    "Connecting to database",           $verbose );
    error(  "Database connection failed: $@",   $verbose );
    debug(  "Connection arguments were: $args", $debug );

    ### standard carp functionality
    carp(   "Wrong arguments passed: @_" );
    croak(  "Fatal: wrong arguments passed: @_" );
    cluck(  "Wrong arguments passed -- including stacktrace: @_" );
    confess("Fatal: wrong arguments passed -- including stacktrace: @_" );

    ### retrieve individual message
    my @stack = Log::Message::Simple->stack;
    my @stack = Log::Message::Simple->flush;

    ### retrieve the entire stack in printable form
    my $msgs  = Log::Message::Simple->stack_as_string;
    my $trace = Log::Message::Simple->stack_as_string(1);

    ### redirect output
    local $Log::Message::Simple::MSG_FH     = \*STDERR;
    local $Log::Message::Simple::ERROR_FH   = \*STDERR;
    local $Log::Message::Simple::DEBUG_FH   = \*STDERR;

    ### force a stacktrace on error
    local $Log::Message::Simple::STACKTRACE_ON_ERROR = 1

like, yes, that last line really is missing its semicolon in the original. i'm just the messenger 🫶

---

🦋 DESCRIPTION 🦋

this module hands you standardized logging facilities, and it does it all by leaning on the "Log::Message" module underneath. one job, done well. iconic behavior, honestly 👑

---

💜 FUNCTIONS 💜

okay so these are the little guys you call all day long:

• msg("message string" [,VERBOSE]) — records a message on the stack, and prints it to "STDOUT" (or actually $MSG_FH, peek at the GLOBAL VARIABLES section below 👀) if the "VERBOSE" option is true. "VERBOSE" defaults to false. exported by default, or via the ":STD" tag.
• debug("message string" [,VERBOSE]) — records a debug message on the stack, and prints it to "STDOUT" (or actually $DEBUG_FH, again, GLOBAL VARIABLES section below) if the "VERBOSE" option is true. "VERBOSE" defaults to false. exported by default, or via the ":STD" tag.
• error("error string" [,VERBOSE]) — records an error on the stack, and prints it to "STDERR" (or actually $ERROR_FH, yep, GLOBAL VARIABLES sections below) if the "VERBOSE" option is true. and heads up: the "VERBOSE" option defaults to true here — not false like its siblings, she's different 💅 exported by default, or via the ":STD" tag.
• carp(); — gives you functionality equal to Carp::carp() while still logging to the stack. best of both worlds fr fr. exported by using the ":CARP" tag.
• croak(); — gives you functionality equal to Carp::croak() while still logging to the stack. exported by using the ":CARP" tag.
• confess(); — gives you functionality equal to Carp::confess() while still logging to the stack. exported by using the ":CARP" tag.
• cluck(); — gives you functionality equal to Carp::cluck() while still logging to the stack. exported by using the ":CARP" tag.

💀 quick vibe check: carp, croak, confess and cluck are all ":CARP" tag exclusives — they do not come in with the default export. don't come for me, it's in the source.

---

🌈 CLASS METHODS 🌈

these are the ones you call on the class itself, main character energy:

• Log::Message::Simple->stack() — retrieves all the items on the stack. and because "Log::Message::Simple" is implemented using "Log::Message", you gotta consult its manpage for the function "retrieve" to see what actually comes back and how to use the items. iykyk 🧚
• Log::Message::Simple->stack_as_string([TRACE]) — returns the whole stack as a printable string. if the "TRACE" option is true, all items come back with "Carp::longmess" output instead of just the message. "TRACE" defaults to false. so chill by default 🍓
• Log::Message::Simple->flush() — removes all the items from the stack and returns them. gone but not forgotten 😭 and again, since "Log::Message::Simple" is implemented using "Log::Message", consult its manpage for the function "retrieve" to see what gets returned and how to use the items.

---

💅 GLOBAL VARIABLES 💅

yes, they're package variables, yes, you can local them, yes, that's the whole trick:

🎀 $ERROR_FH

the filehandle that all the messages sent to error() get printed to. defaults to *STDERR. 🚨

🎀 $MSG_FH

the filehandle that all the messages sent to msg() get printed to. defaults to *STDOUT. 🌸

🎀 $DEBUG_FH

the filehandle that all the messages sent to debug() get printed to. defaults to *STDOUT. 🔍

🎀 $STACKTRACE_ON_ERROR

if this option is set to "true", every single call to error() generates a stacktrace using Carp::shortmess(). defaults to "false". flip it and suddenly every error comes with receipts, periodt 🔥

---

⭐ little reminder bestie: setting $STACKTRACE_ON_ERROR affects every error() call from then on — it's not a per-call thing. plan accordingly 🫶

---

and that's the whole page! 🌈💖✨

this masterpiece of documentation ships with perl v5.42.0 and is dated 2014-07-27 — yeah, she's been serving since 2014 and she still ate 💅🎀 bye bestie, go log something 🦋