Log::D...r::Any(3pm)

💖 Log::Dispatch::Configurator::Any 💖

okay bestie so this is Log::Dispatch::Configurator::Any, a lil piece of the User Contributed Perl Documentation collection, and honestly? it's giving "small module, huge main character energy." let's get into it 🫶

---

✨ VERSION ✨

version 1.122640 — yeah it's been around a minute, it's vintage, it's iconic 💅

---

🎯 PURPOSE 🎯

use this module with Log::Dispatch::Config when you want to load your config files in so many different formats — like, whatever format, it does not care — because it hands all of that off to Config::Any. that's the whole job. that's the vibe. 💖

---

🌸 SYNOPSIS 🌸

the classic way, the traditional Log::Dispatch::Config way:

use Log::Dispatch::Config; # loads Log::Dispatch
use Log::Dispatch::Configurator::Any;

my $config = Log::Dispatch::Configurator::Any->new('log.yml');
Log::Dispatch::Config->configure($config);

# nearby piece of code
my $log = Log::Dispatch::Config->instance;
$log->alert('Hello, world!');

or, if you're feeling spicy and you literally do not have a config file on disk, you can just vibe with a hash instead:

use Log::Dispatch::Config; # loads Log::Dispatch
use Log::Dispatch::Configurator::Any;

my $confhash = {
    dispatchers => ['screen]',
    screen = {
        class => 'Log::Dispatch::Screen',
        min_level => 'debug',
    },
};

my $config = Log::Dispatch::Configurator::Any->new($confhash);
Log::Dispatch::Config->configure($config);

# nearby piece of code
my $log = Log::Dispatch::Config->instance;
$log->alert('Hello, world!');

(and yes, copy that code block character for character, bestie. it is what it is. 🙈)

---

📖 DESCRIPTION 📖

so Log::Dispatch::Config is a wrapper around Log::Dispatch, and it lets you set up your Log::Dispatch objects using config files. it's kinda like a lite version of log4j and Log::Log4perl — it lets you have multiple log destinations, which is a whole slay. the standard config file format for Log::Dispatch::Config is AppConfig.

but here's where this module comes in: it plugs into Log::Dispatch::Config and unlocks other file formats — literally any format that Config::Any supports. and as a lil bonus? you can also just pass in a configuration data structure instead of a filename. no file required. ✨

---

🛠️ USAGE 🛠️

just follow the examples up in the SYNOPSIS, bestie. but heads up: if you're using an external configuration file, you are required to use a filename extension (like .yml for YAML). no extension = no vibe check passed. 😭

below are a couple of tips and tricks you might find useful 👑

🍓 Fall-back default config

being able to pass a configuration data structure instead of a file on disk is so handy when you want to ship application defaults that the user can then replace with their own settings. like, for example, you could have this:

my $defaults = {
    dispatchers => ['screen'],
    screen => {
        class     => 'Log::Dispatch::Screen',
        min_level => 'debug',
    },
};

my $config_file = '/etc/myapp_logging.conf';
my $config = $ENV{MYAPP_LOGGING_CONFIG} || $ARGV[0] ||
    ( -e $config_file ? $config_file : $defaults);

Log::Dispatch::Config->configure_and_watch(
    Log::Dispatch::Configurator::Any->new($config) );
my $dispatcher = Log::Dispatch::Config->instance;

with that code, your app checks for a filename in an environment variable, then a filename as a command line argument, then it checks for a file on disk, and finally it falls back to its built-in defaults. the pipeline is pipeline-ing. 💅

🦋 Dealing with a "dispatchers" list

Log::Dispatch::Config requires that the global setting dispatchers has a list value (i.e. your list of dispatchers, obvi). but a few config file formats do not support list values at all, or they don't support list values at the global level — two examples being Config::Tiny and Config::General. annoying, right?

so this module gives you a lil grace when you've only got one dispatcher in use. write the config file like normal, and the single-item dispatchers value gets automatically promoted to a list. in other words:

# myapp.ini
dispatchers = screen

# this becomes a config of:
$config = { dispatchers => 'screen', ... };

# so this module promotes it to:
$config = { dispatchers => ['screen'], ... };

but if you want more than one dispatcher, you're gonna need a config file format that supports these lists natively, i'm afraid 😭 a good suggestion might be YAML. (it's always YAML.)

---

💜 THANKS 💜

big thanks to "miyagawa" for writing Log::Dispatch::Config — i also stole some tests from there, no shame, it's a compliment fr fr. and also thanks to Florian Merges for his YAML Configurator, which was a super useful example and saved me soooo much time. 🫶✨

---

👑 AUTHOR 👑

Oliver Gorwits <oliver@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2012 by University of Oxford.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 💖 (yes, that means go wild, but read the terms, bestie.)

---

and that's the whole page!! 🎀 this one was perl v5.34.0 flavored, dated 2022-06-15, and honestly it ate. no cap. byeeee 🌈💅✨