TraceMessages(3pm)

💖 TraceMessages — bestie's guide to debug tracing 💖

okay so listen. this is the Log::TraceMessages page from the User Contributed Perl Documentation section of the manual, and honestly? it's giving "why did nobody tell me about this sooner". it's a Perl extension for trace messages used in debugging, and it's about to be your new fave. 🫶

---

✨ NAME ✨

Log::TraceMessages — a Perl extension for trace messages, aka the lil glow-up your debugging statements deserve. 🌸

---

🎀 SYNOPSIS 🎀

here's the whole vibe, verbatim, no notes:

  use Log::TraceMessages qw(t d);
  $Log::TraceMessages::On = 1;
  t 'got to here';
  t 'value of $a is ' . d($a);
  {
      local $Log::TraceMessages::On = 0;
      t 'this message will not be printed';
  }

  $Log::TraceMessages::Logfile = 'log.out';
  t 'this message will go to the file log.out';
  $Log::TraceMessages::Logfile = undef;
  t 'and this message is on stderr as usual';

  # For a CGI program producing HTML
  $Log::TraceMessages::CGI = 1;

  # Or to turn on trace if there's a command-line argument '--trace'
  Log::TraceMessages::check_argv();

like, look at that local. the way that block just... contains the vibe. not me getting emotional over scoping. 😭

---

💅 DESCRIPTION 💅

so here's the tea, bestie. this module is a slightly better way to put trace statements into your code than just calling print(). it gives you an easy way to turn trace on and off for particular sections of code, without having to go comment out bits of your source like some kind of feral gremlin. 🔥

---

🌈 USAGE 🌈

$Log::TraceMessages::On

the flag that controls whether tracing is on or off. set it however you want — and of course it can be local-ized (iconic behaviour, we love to see it). the default is off.

$Log::TraceMessages::Logfile

the name of the file that trace should be appended to. if this is undefined (which, btw, is the default), then trace gets written to stderr — or to stdout if $CGI is set.

$Log::TraceMessages::CGI

flag controlling whether the program printing trace messages is a CGI program (default is no). what this means is that trace messages get printed as HTML. and unless $Logfile is also set, messages get printed to stdout so they show up in the output page. 🦋

t(messages)

print the given strings — but only if tracing is enabled. unless $CGI is true or $Logfile is set, each message gets printed to stderr with a newline appended. 💖

trace(messages)

a synonym for t(messages). same energy, different name.

d(scalar)

returns a string representation of a scalar's value, suitable for use in a trace statement. this is just a wrapper for Data::Dumper. 🌸

heads up bestie: d() will exit with '' if trace is not turned on. this is to stop your program from being slowed down by generating lots of strings for trace statements that are never gonna get printed. efficiency queen behaviour, honestly.

dmp(scalar)

a synonym for d(scalar). 💅

check_argv()

looks at the global @ARGV of command-line parameters to find one called '--trace'. if it finds it, that arg gets removed from @ARGV and tracing gets turned on. since tracing is off by default, calling check_argv() is your way to make your program print trace only when you ask for it from the command line. main character energy fr fr. 👑

---

👑 AUTHOR 👑

Ed Avis, ed@membled.com

---

🔍 SEE ALSO 🔍

perl(1), Data::Dumper(3).

---

💀 POD ERRORS 💀

hey! 😭 the above document had some coding errors, which are explained below:

• Around line 218:
  • You forgot a '=back' before '=head1'

like, the manpage is a little messy but she's still slaying. we don't judge. 🎀

---

and that's the whole thing, bestie — written up under perl v5.34.0, dated 2022-06-15. go forth and trace responsibly. periodt. 💖✨