MouseX...omFile(3pm)

💖 MouseX::ConfigFromFile 💖

okay bestie, gather round, because we're talking about MouseX::ConfigFromFile — an abstract Mouse role for setting attributes from a configfile. yes. that's the whole vibe. it's the role that lets your objects be born fully dressed, straight out of a config file. iconic behavior honestly.

it lives in the User Contributed Perl Documentation and it's a Perl module, so you know it's gonna be a little ✨magical✨.

---

🦋 SYNOPSIS 🦋

so here's how it goes. first you make a real role based on this abstract one:

package MyApp::ConfigRole;
use Mouse::Role;
with 'MouseX::ConfigFromFile';

use MyApp::ConfigLoader;

sub get_config_from_file {
    my ($class, $file) = @_;

    my $config_hashref = MyApp::ConfigLoader->load($file);

    return $config_hashref;
}

then a class that actually uses it:

package MyApp;
use Mouse;
with 'MyApp::ConfigRole';

# optionally, default the configfile:
has '+configfile' => ( default => '/tmp/myapp.yml' );

👀 note that '+configfile' — the little plus means we're tweaking an attribute that already exists. bestie is inheriting and customizing. we love to see it.

and then a script that uses the class with a configfile:

my $app = MyApp->new_with_config(
    configfile => '/etc/myapp.yml',
    other_opt  => 'foo',
);

look at that. effortless. 💅

---

🌸 DESCRIPTION 🌸

okay so real talk. this is an abstract role which provides an alternate constructor for creating objects using parameters passed in from a configuration file. the actual implementation of reading the configuration file is left to concrete subroles — meaning this role does NOT do the file reading itself, it just sets up the whole structure for you. it's giving "manager, not intern." 😭

it declares an attribute configfile and a class method new_with_config, and it requires that concrete roles derived from it implement the class method get_config_from_file. no skipping that homework, fr fr.

and here's the important bit: attributes specified directly as arguments to new_with_config supercede those in the configfile. so your explicit args win. always. periodt.

---

✨ METHODS ✨

💜 new_with_config(%params?)

this is your alternate constructor, and it knows to look for the configfile option in its arguments and use that to set attributes. it's much like MouseX::Getopts' new_with_options. same energy, different module.

example, because of course:

my $app = MyApp->new_with_config( configfile => '/etc/foo.yaml' );

⚠️ and say it with me: Explicit arguments will override anything set by the configfile. that's the rule. that's the law. 🫶

🎀 get_config_from_file($file)

okay bestie listen. this method is not implemented in this role — nope, not even a little. but it is required of all subroles. if you inherit this role and don't write it, things are gonna go badly for you, and not in a cute way. 💀

its two arguments are the class name and the configfile, and it's expected to return a hashref of arguments to pass to new() which are sourced from the configfile.

example:

sub get_config_from_file {
    my ($class, $file) = @_;

    my $config = {};

    # ... load config from $file ...

    return $config;
}

see that # ... load config from $file ...? that's the part where you do the actual work. this role just hands you the mic. 🎤

---

🌈 PROPERTIES 🌈

🧚 configfile

this is a Path::Class::File object which can be coerced from a regular path name string. so you can hand it a plain old string and it'll glow up into a proper file object. no cap.

this is the file your attributes are loaded from. you can add a default configfile in the class using the role and it will be honored at the appropriate time:

has '+configfile' => ( default => '/etc/myapp.yaml' );

set it and forget it, bestie. it'll show up when it's supposed to. 👑

---

🫶 AUTHOR 🫶

NAKAGAWA Masaki <masaki@cpan.org>

---

💖 THANKS TO 💖

Brandon L. Black, "AUTHOR" in MooseX::ConfigFromFile

(so like, shoutout to the MooseX::ConfigFromFile author section. credit where credit is due. we love a collaborative ecosystem. 🌸)

---

⭐ LICENSE ⭐

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

which is the nicest possible way of saying "go off, do your thing, just keep it Perl-flavored." slay.

---

👑 SEE ALSO 👑

• Mouse
• Mouse::Role
• MouseX::Types::Path::Class
• MooseX::ConfigFromFile

go read those if you want the full lore. iykyk. 💅

---

and that's the whole page, bestie! this was perl v5.36.0, dated 2022-10-13, from MouseX...omFile(3pm) — and yes, the man page name is literally truncated with ellipses like that, it's the filename being too long for the header, not a typo, we love her anyway. 🦋💖 mwah, go build something with a config file.