MooseX...omFile(3pm)

💖 MooseX::ConfigFromFile 💖

okay bestie, so this is a page from the User Contributed Perl Documentation set — MooseX::ConfigFromFile(3pm), to be exact. it's a whole abstract Moose role for setting attributes from a configfile and it is, genuinely, a little bit iconic. let's get into it 🫶

---

✨ NAME ✨

MooseX::ConfigFromFile — an abstract Moose role for setting attributes from a configfile. yes that is literally the whole name. slay.

---

🌸 VERSION 🌸

version 0.14. noted. locked in. 💅

---

🦋 SYNOPSIS 🦋

bestie, here's the whole vibe. three parts. first: a real role built on top of this abstract one:

########
## A real role based on this abstract role:
########

package MooseX::SomeSpecificConfigRole;
use Moose::Role;

with 'MooseX::ConfigFromFile';

use Some::ConfigFile::Loader ();

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

  my $options_hashref = Some::ConfigFile::Loader->load($file);

  return $options_hashref;
}

then a class that actually consumes it:

########
## A class that uses it:
########
package Foo;
use Moose;
with 'MooseX::SomeSpecificConfigRole';

# optionally, default the configfile:
sub _get_default_configfile { '/tmp/foo.yaml' }

# ... insert your stuff here ...

and finally a lil script that uses that class with a configfile:

########
## A script that uses the class with a configfile
########

my $obj = Foo->new_with_config(configfile => '/etc/foo.yaml', other_opt => 'foo');

that's the whole flow. no cap. 🌈

---

💜 DESCRIPTION 💜

so this is an abstract role. what it does is hand you an alternate constructor for making objects using parameters that got passed in from a configuration file. the actual reading of the config file? not its problem. that part is left to concrete sub-roles. delegation, queen behavior. 👑

it declares a configfile attribute and a class method new_with_config, and it requires that any concrete roles derived from it implement the class method get_config_from_file.

attributes you pass in directly as arguments to new_with_config supersede the ones sitting in the configfile. direct args win. periodt.

also: MooseX::Getopt knows about this abstract role, and if it's available it'll use it to load attributes from the file specified by the command line flag --configfile during its normal new_with_options. iykyk. ✨

---

🎀 Attributes 🎀

🍓 configfile 🍓

this one is a Path::Tiny object, and it can be coerced from a regular path string or from any object that supports stringification. it's the file your attributes get loaded from, bestie. you can add a default configfile in the consuming class and it will be honored at the appropriate time — scroll down to _get_default_configfile to see how. 💖

and if you have MooseX::Getopt installed, this attribute will also get the Getopt trait supplied, which means you can set the configfile straight from the command line too. versatile! 🔥

---

🧚 Class Methods 🧚

⭐ new_with_config ⭐

this is an alternate constructor, and it knows to look for the configfile option in its arguments and use that to set attributes. it's much like MooseX::Getopt's new_with_options. example time:

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

and remember: explicit arguments will override anything set by the configfile. you're the main character, your args come first. 👑

🌸 get_config_from_file 🌸

this class method is not implemented in this role — nope, not here. but it is required of all classes or roles that consume this role. 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. so like, that's your homework. do it. ✨

🦋 _get_default_configfile 🦋

this class method is also not implemented in this role, but it can and should be defined in a consuming class or role to return the default value of the configfile — that's the case when nothing got passed into the constructor explicitly. 🙈

---

👑 AUTHOR 👑

Brandon L. Black <blblack@gmail.com>

---

💅 CONTRIBUTORS 💅

• Karen Etheridge <ether@cpan.org>
• Tomas Doran <bobtfish@bobtfish.net>
• Chris Prather <chris@prather.org>
• Yuval Kogman <nothingmuch@woobling.org>
• Zbigniew Lukasiak <zby@cpan.org>

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2007 by Brandon L. Black.

it's free software, bestie — you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

okay so that's the whole page, and honestly? it ate. 💖 this was MooseX::ConfigFromFile(3pm) from perl v5.34.0, dated 2022-06-15, and that's the tea. go forth and configfile, queen. 🎀✨💅