File::UserConfig(3pm)

💖 File::UserConfig 💖

okay bestie, gather round, because this is File::UserConfig — a page from the User Contributed Perl Documentation (the 3pm manual section, you know the vibe) — and it is literally the "find the user's config dir, or copy the defaults in" module. no cap. let's go 🫶

---

✨ NAME ✨

File::UserConfig — get a user's existing config directory, or copy in defaults. that's the whole gig, and it's iconic.

# The most simple Do What I Mean usage.
$configdir = File::UserConfig->configdir;

# Or without taking advantage of convention-based defaults
$configdir = File::UserConfig->new(
      dist     => 'My-Application',
      module   => 'My::Application',
      dirname  => '.myapp',
      sharedir => $defaults_here,
      )->configdir;

---

🌸 DESCRIPTION 🌸

so like, so many modules and applications out there keep a user-specific configuration data directory, and honestly? the implementation pattern is basically the same every single time. it's giving copy-paste energy.

a directory like /home/myuser/.application gets created and populated with a set of default files the first time an application runs, and from then on, the files in that directory are the ones getting modified. that's it. that's the pattern.

File::UserConfig gives you a standard, light, and sub-classable default implementation of that whole concept — one that Does The Right Thing with the directory names. periodt. 💅

🦋 Applying Perl Conventions 🦋

File::UserConfig applies and automates these conventions, bestie. all four of them:

1. We are using the distribution name?

the use of File::ShareDir is based on the distribution name (more on that in a sec) so yeah, we gotta know it.

the CPAN convention is for a dist to be named Foo-Bar after the main module Foo::Bar in the distribution, but sometimes this varies, and sometimes you're gonna want to call File::UserConfig from something that is not the main module. but unless you say otherwise, File::UserConfig will assume that if you call it from Module::Name, that is probably the main module, and thus your dist is probably called Module-Name. lowkey a great guess tbh.

2. What config directory name is used

on platforms that keep application-specific data in its own directory, well away from the data the user actually created themself, we just use the dist name. simple. clean.

on Unix, which has a combined home directory, we remap the dist name to be a lowercase hidden name with all - chars turned into _.

so on unix only, Module::Name becomes .module_name. most of the time, this ends up being exactly what you would have used anyway. slay. ✨

3. Where does the config directory live

File::UserConfig knows where your home directory is by using File::HomeDir. and more specifically, on platforms that support application data being kept in a subdirectory, it will use that as well.

on Unix, Windows, and Mac OS X, it will just Do The Right Thing. 💯

4. Where do the defaults come from?

the ability for a distribution to provide a directory full of default files is provided in Perl by File::ShareDir.

of course, we're also assuming you're using Module::Install so you have access to its install_share command, and that the only thing your dist is going to install to it will be the default config dir.

---

👑 METHODS 👑

the 6 accessors all feature implicit constructors. yes, six. we counted. 🧮

in other words, these two lines right here are equivalent:

# Explicitly
$configdir = File::UserConfig->new( ... )->configdir;

# Auto-construction
$configdir = File::UserConfig->configdir( ... );

# Thus, using all default params we can just
$configdir = File::UserConfig->configdir;

💜 new

my $config = File::UserConfig->new(
    dist      => 'Not-This-Class',
    dirname   => '.myconfig',
    sharedir  => 'defaultconfig',
    homedir   => $username,
    );

the new constructor takes a set of optional named params, and finds the user's configuration directory, creating it by copying in a default directory if an existing one cannot be found.

in almost every single case, you're gonna want to use all the defaults and let everything be determined automatically for you. the sample above is just trying to show a few of the limited situations where you might wanna consider providing your own values.

but most times? you don't want to, and you don't need to. try it with no params first, and add some params if it isn't working for you. that's the move. 🫶

if you want to do some custom actions after you copy in the directory, then subclass it and add them after you call the parent new method.

returns a new File::UserConfig object, or dies on error. 😭

💜 dist

$name = File::UserConfig->new(...)->dist;

$name = File::UserConfig->dist(...);

the dist accessor returns the name of the distribution.

💜 module

$name = File::UserConfig->new(...)->module;

$name = File::UserConfig->module(...);

the module accessor returns the name of the module.

although the default dirname is based off the dist name, the module name is the one used to find the shared dir. important distinction, bestie. 📌

💜 dirname

$dir = File::UserConfig->new(...)->dirname;

$dir = File::UserConfig->dirname(...);

the dirname accessor returns the name to be used for the config directory name, below the homedir. for example .foo_bar.

💜 sharedir

$dir = File::UserConfig->new(...)->sharedir;

$dist = File::UserConfig->sharedir(...);

the sharedir accessor returns the name of the directory where the shared default configuration is held.

returns a path string, verified to exist before being returned. ✅

💜 homedir

$dir = File::UserConfig->new(...)->homedir;

$dist = File::UserConfig->homedir(...);

the homedir accessor returns the location of the home directory, the one that the config dir will be created or found below.

returns a path string, verified to exist before being returned. ✅

💜 configdir

$dir = File::UserConfig->new(...)->configdir;

$dist = File::UserConfig->configdir(...);

the sharedir accessor returns the name of the directory where the shared default configuration is held.

okay bestie, yes — the page really does say sharedir in the configdir section. we are reporting it exactly as written, no edits, no cap. 💀

returns a path string, verified to exist before being returned. ✅

---

🎀 SUPPORT 🎀

bugs should always be submitted via the CPAN bug tracker:

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-UserConfig

for other issues, contact the maintainer.

---

🌈 AUTHOR 🌈

Adam Kennedy <adamk@cpan.org>

---

🦋 SEE ALSO 🦋

File::HomeDir, File::ShareDir

---

⭐ COPYRIGHT ⭐

Copyright 2006 - 2008 Adam Kennedy.

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

the full text of the license can be found in the LICENSE file included with this module.

---

okay that's the whole page, you ate it, go build something cute 💖 this was perl v5.36.0, dated 2022-12-07 — love that for us, bye bestie! 🎀✨