MooseX...ispatch(3pm)

💖 MooseX::LogDispatch — the manual page, but make it cute 💖

okay bestie, gather round, because this is the Perl documentation for MooseX...ispatch(3pm) — aka MooseX::LogDispatch, a logging role for Moose, and it is genuinely one of the most useful little guys in the ecosystem. ✨

---

🌸 VERSION 🌸

This doc is describing MooseX::LogDispatch version 1.1000. That's the number, bestie, don't @ me. 💅

---

✨ SYNOPSIS ✨

okay so here's the whole vibe in code form, and I am not touching a single character of it:

package MyApp;
use Moose;
with 'MooseX::LogDispatch';
# or
# with 'MooseX::LogDispatch::Levels'

# This is optional. Will log to screen if not provided
has log_dispatch_conf => (
  is => 'ro',
  lazy => 1,
  default => sub {
    my $self = shift;
    My::Configurator->new( # <- you write this class!
        file => $self->log_file,
        debug => $self->debug,
    );

  }
);

# This is the same as the old FileBased config parameter to the role. If you
# prefer you could name the attribute 'config_filename' instead.
has log_dispatch_conf => (
  is => 'ro',
  lazy => 1,
  default => "/path/to/my/logger.conf"
);

# Here's another variant, using a Log::Dispatch::Configurator-style
#  hashref to configure things without an explicit subclass
has log_dispatch_conf => (
  is => 'ro',
  isa => 'HashRef',
  lazy => 1,
  required => 1,
  default => sub {
    my $self = shift;
    return $self->debug ?
       {
         class     => 'Log::Dispatch::Screen',
         min_level => 'debug',
         stderr    => 1,
         format    => '[%p] %m at %F line %L%n',
       }
       : {
           class     => 'Log::Dispatch::Syslog',
           min_level => 'info',
           facility  => 'daemon',
           ident     => $self->daemon_name,
           format    => '[%p] %m',
       };
   },
);

sub foo {
  my ($self) = @_;
  $self->logger->debug("started foo");
  ....
  $self->logger->debug('ending foo');
}

like… look at her. three whole ways to configure, zero drama. 🫶

---

🦋 DESCRIPTION 🦋

It's a Log::Dispatch role, and you slap it onto your Moose classes. That's the whole thing. That's the tweet. 💜

---

👑 ACCESSORS 👑

🎀 logger

This is the main Log::Dispatch::Config object that does all the work. She's the main character here, fr fr. She's got a method for every single log level — stuff like "debug" or "error" — so you just call it and go on with your day. 💅

🍓 log_dispatch_conf

This is an optional attribute you can hand to your class, and depending on what shape you give it, it does different things:

• if you define it as a hashref value, it gets interpreted in the style of the configuration hashrefs documented in the Log::Dispatch::Config docs — specifically the ones where they show examples of using a PLUGGABLE CONFIGURATOR for pluggable configuration. iconic, honestly.
• you can also level up and get way more flexibility by defining your own complete Log::Dispatch::Configurator subclass, and having your "log_dispatch_config" attribute be an instance of that class. yes bestie, your own class. go off. 🌈
• if this attribute holds a string, that string is taken to be the path to a config file for Log::Dispatch::Configurator::AppConfig.

By lazy-loading this attribute (that's the lazy => 1 situation), you get to have the configuration figured out at runtime. Which is so nice if you want to change your log format and/or destination at runtime based on things like MooseX::Getopt / MooseX::Daemonize parameters. 🧚

And if you just… don't provide this attribute at all? No worries. It'll default to sending everything to the screen in a reasonable debugging format. the fallback is a vibe, not a punishment. 💖

⭐ use_logger_singleton

If this attribute has a true value, and Log::Dispatch::Config has a configured log instance, then that gets used in preference to anything set via "log_dispatch_config". she wins. periodt.

The main use for this attribute is when you want to use this module inside another library module — like, when the consumer of this role isn't the end user. Setting this attribute to true makes it so much easier for the end user to configure logging themselves. 🫶

Note: if you're using a class that consumes this one as a role, and you're planning on reinstantiating that class, it's probably a good idea to set this to 1 to avoid errors. lowkey important. don't skip it. 😭

---

🌈 SEE ALSO 🌈

Go read these too, bestie, they're the whole extended universe:

• MooseX::LogDispatch::Levels
• Log::Dispatch::Configurator
• Log::Dispatch::Config
• Log::Dispatch

---

💀 DEPRECATION NOTICE 💀

okay so, bad news for the old heads: the old "with Logger(...)" style is deprecated, in favour of just using one of the two roles and making the config much more flexible. And as of version 1.2000 of this module, if you try to use the old style, it will make your code die. not a drill. not a metaphor. your code literally dies. 💀

---

🙈 BUGS AND LIMITATIONS 🙈

Found a bug? Want a feature? Please report it, we genuinely want to know:

• email "bug-moosex-logdispatch@rt.cpan.org", or
• use the web interface at <http://rt.cpan.org>.

Or honestly? Just come bother us in "#moose" on "irc.perl.org". we're there. we're always there. 🦋

---

💜 AUTHOR 💜

Ash Berlin "<ash@cpan.org>" — with v1.2000 fixes by Mike Whitaker "<penfold@cpan.org>"

Based on work by Chris Prather "<perigrin@cpan.org>"

Thanks to Brandon Black "<blblack@gmail.com>" for showing me a much nicer way to configure things. 🫶

---

🎀 LICENCE AND COPYRIGHT 🎀

Some development sponsored by Takkle Inc.

Copyright (c) 2007, Ash Berlin "<ash@cpan.org>". Some rights reserved.

Copyright (c) 2007, Chris Prather "<perigrin@cpan.org>". Some rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

---

okay that's the whole page, you made it to the end, I'm so proud of you 🥹💖

this was perl v5.36.0, dated 2023-02-18, and yeah the header's a little cursed (MooseX...ispatch(3pm), we've all seen it, we don't talk about it) — but the docs? the docs ate. slay. go log something. 💅✨