MooseX...uration(3pm)

💖 MooseX::Configuration 💖

okay bestie, welcome to the MooseX::Configuration page, straight outta the User Contributed Perl Documentation (that's the 3pm manual section, iykyk) ✨

version 0.02 — she's young, she's cute, she's got a whole personality 🎀

---

🌸 NAME 🌸

MooseX::Configuration — define attributes that come from configuration files. no cap. 🗂️

---

✨ VERSION ✨

version 0.02 💅

---

🦋 SYNOPSIS 🦋

like, here's the whole vibe in one go:

package MyApp::Config;

use Moose;
use MooseX::Configuration;

has database_name => (
    is      => 'ro',
    isa     => 'Str',
    default => 'MyApp',
    section => 'database',
    key     => 'name',
    documentation =>
        'The name of the database.',
);

has database_username => (
    is      => 'ro',
    isa     => Str,
    default => q{},
    section => 'database',
    key     => 'username',
    documentation =>
        'The username to use when connecting to the database. By default, this is empty.',
);

my $config = MyApp::Config->new( config_file => '/path/to/config/myapp.ini' );
$config->write_file( ... );

look at her go 😭 she's literally doing everything 🫶

---

💜 DESCRIPTION 💜

okay so this module lets you define attributes that can come from a configuration file. and as if that wasn't enough, it also adds a role to your class so you can write a configuration file too. main character module behavior, honestly 👑

the whole thing is built on a simple INI-style configuration file, which has sections and keys in it, like this:

key1 = value
key2 = 42

[section]
key3 = 2

see? sections. keys. values. iconic. 🍓

---

🎀 ATTRIBUTE API 🎀

just using this module in your class changes your class's attribute metaclass so it can support defining attributes as configuration items. yes, it's doing the most and we love her for it 💅

there are two new parameters you can pass when you're defining an attribute: section and key. these two are the ones that tell the module how to find the attribute's value inside the configuration file. 💖

the section parameter is optional. so if you don't set it, but you do provide a key, then the section defaults to "_", which is the main section of the config file. sneaky little default but okay ✨

but listen: if you pass a section, you must also pass a key. them's the rules bestie, no exceptions 💀

defining an attribute as a configuration item has several effects:

• first, it changes the default value for the attribute. before it ever looks at a default or builder you defined, the attribute will first look in the config file for a corresponding value. if one exists → she uses that. if not → she falls back to using a default you supply. periodt. 🌈
• if you do supply a default, it must be a string (or a number). not a reference, not an undefined value. sorry girl, those are not welcome here 🙈
• all configuration attributes are lazy. this is necessary, okay? because the configuration file has to be loaded and parsed before we can look up values. it's giving "you can't read a book before it's printed" 📚
• the documentation string is used when generating a configuration file. more on that below 👇

---

🌟 CLASS API 🌟

your config class will do the MooseX::Configuration::Trait::Object role. and that adds several attributes and methods to your class. slay 💖

🧚 config_file attribute

the config_file attribute defines the location of the configuration file. the role supplies a builder method that you can replace, called _build_config_file. it should return a string or a Path::Class::File object pointing at the configuration file. it can also return undef. so many options, so much freedom 🦋

if you don't provide your own builder, then config_file will just default to undef. ngl that's a very chill default 😌

🍓 $config->_raw_config()

this returns the raw hash reference as read by Config::INI::Reader. and if no config file was defined? then it simply returns an empty hash reference. no drama, no fuss 💅

👑 $config->write_config_file( ... )

this method can be used to write a configuration file. it accepts several parameters:

• file — this can be either a path or an open filehandle. the configuration text will be written to this file. it defaults to the value of $self->config_file(). if no file is provided or already set in the object, this method will die. 💀 so like, pls pass a file bestie
• generated_by — if this parameter is passed, it'll be included as a comment at the top of the generated file. cute little signature ✨
• values — this should be a hash reference of attribute names and values to write to the config file. it is optional. 🎀

when writing the configuration file, any configuration item that was set in the configuration file originally will be set in the new file, and so will any value passed in the values key. but an attribute value set in the constructor or by a default will not be included in the generated file. rules are rules 🫶

keys without a value will still be included in the file — as a comment. she still shows up, just quietly 🌸

and finally: if an attribute includes a documentation string, that string will appear as a comment above the key. if the attribute defines a simple scalar default, that'll also be included in the comment — unless the default is the empty string. and last but not least, if the attribute is required, that gets mentioned in the comment too. so thorough. so iconic. ⭐

---

💸 DONATIONS 💸

if you'd like to thank me for the work I've done on this module, please consider making a "donation" to me via PayPal. I spend a lot of free time creating free software, and would appreciate any support you'd care to offer. 🥺💖

please note that I am not suggesting that you must do this in order for me to continue working on this particular software. I will continue to do so, inasmuch as I have in the past, for as long as it interests me. fr fr, no pressure 💅

similarly, a donation made in this way will probably not make me work on this software much more — unless I get so many donations that I can consider working on free software full time, which seems unlikely at best. 😭 manifesting it though ✨

to donate, log into PayPal and send money to autarch@urth.org or use the button on this page: <http://www.urth.org/~autarch/fs-donation.html> 🫶

---

🐛 BUGS 🐛

please report any bugs or feature requests to bug-moosex-configuration@rt.cpan.org, or through the web interface at <http://rt.cpan.org>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. we're in this together bestie 🤝

---

👑 AUTHOR 👑

Dave Rolsky <autarch@urth.org> 💖

---

📜 COPYRIGHT AND LICENSE 📜

this software is Copyright (c) 2010 by Dave Rolsky. 🎀

this is free software, licensed under:

The Artistic License 2.0

---

and that's the whole page, babe — written for perl v5.34.0, dated 2022-06-15, in the MooseX::Configuration(3pm) manual. go forth and configure your little heart out, ily, mwah 💋✨🌸