Config::Find(3pm)

💖 Config::Find 💖 — the Config::Find(3pm) page, bestie edition

okay so this is Config::Find, a Perl module, and it's here to help you find configuration files the way your actual operating system wants them found. No cap.

---

✨ NAME ✨

Config::Find</purgle> — find configuration files in the native OS fashion 🦋

---

🌸 SYNOPSIS 🌸

  use Config::Find;

  my $filename=Config::Find->find;

  ...

  my $fn_foo=Config::Find->find( name => 'my_app/foo',
                                 mode => 'write',
                                 scope => 'user' );

  my $fn_bar=Config::Find->find( names => [qw(my_app/bar appbar)] );

  my $fh=Config::Find->open( name => 'foo',
                             scope => 'global',
                             mode => 'w' )

  my $fn=Config::Find->install( 'original/config/file.conf',
                                name => 'foo' );

  my $fn=Config::Find->find( file => $opt_c,
                             name => foo );

---

🎀 ABSTRACT 🎀

Literally what it says on the tin: Config::Find searches for configuration files using OS dependent heuristics. 💅

---

🌈 DESCRIPTION 🌈

Every OS has its own whole thing about where config files should live, and honestly? iconic of them. This module lets you easily find and create your app's configuration files while following those rules, so you don't have to hardcode paths like a Victorian orphan. 🫶

Config::Find references configuration files by the application name, or by the application name plus the configuration file name when your app is a whole multi-file situation — think "emacs", "profile", "apache/httpd", "apache/ssl". 🦋

By default the $0 value is used to generate the configuration file name. If you wanna define it explicitly, you use the keywords "name" or "names":

• name => "name" or name => "app/file" — picks the first configuration file matching that name. main character energy, first match wins ✨
• names => [qw(foo bar foo/bar)] — picks the first configuration file matching any of the names you passed in. a lil lineup, take your pick 💅

Alternatively, you can just say exactly where the file is with the "file" keyword:

• file => "/config/file/name.conf" — explicit position of the configuration file. no heuristics, no detective work, just the exact spot 📍

If undef is passed, this entry is ignored and the search for the configuration file continues with the appropriate OS rules. Which is lowkey the whole point, because it lets you do this:

  use Config::Find;
  use Getopt::Std;

  our $opt_c;
  getopts('c:');

  my $fn=Config::Find->find(file => $opt_c)

Methods in this package also accept the optional arguments "scope" and "mode":

• scope => "user" or scope => "global" — configuration files can be private to the application user, or global to the OS. like, in unix there's the global /etc/profile and the user ~/.profile. both valid, both serving 🫶
• mode => "read" or mode => "write" — in "read" mode you get back file names that already exist; in "write" mode the file names point to where the configuration file has to be stored. read = vibe check what's there, write = make it happen ✨

🧚 METHODS 🧚

All the methods in this package are class methods (you don't need an object to call them, bestie, just call them straight on the class). 💜

• $fn=Config::Find->find(%opts) — returns the name of the configuration file. 🔍
• $fh=Config::Find->open(%opts) — returns an open file handle for the configuration file. In write mode, the file and any nonexistent parent directories are created. it's giving "I'll build the whole path for you" 😭💖
• $fn=Config::Find->install($original, %opts) — copies a configuration file to a convenient place. 🎀

---

💀 BUGS 💀

Some Win32 operating systems are not completely implemented and default to inferior modes — but hey, this is a work in progress!!! 🙈 we're aware, we're working on it

Contributions, bug reports, feedback and any kind of comments are welcome. fr fr, slide into the repo 🫶

---

🔥 SEE ALSO 🔥

• Config::Find::Unix, Config::Find::Win32 — for descriptions of the heuristics used to find the configuration files. iykyk 📚
• Config::Find::Any — for information about adding support for a new OS. go off, expand the lore 🌍
• Config::Auto — give me the idea for this module. shoutout to the muse ✨

---

👑 AUTHOR 👑

Salvador Fandiño García, <sfandino@yahoo.com>

🌟 CONTRIBUTORS 🌟

Barbie, <barbie@missbarbell.co.uk> (some bug fixes and documentation) 💅

---

💖 COPYRIGHT AND LICENSE 💖

Copyright 2003-2015 by Salvador Fandiño García (sfandino@yahoo.com) Copyright 2015 by Barbie (barbie@missbarbell.co.uk)

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

---

and that's the whole page, bestie 🎀 this was perl v5.36.0, dated 2022-12-07 — thanks for reading the Config::Find(3pm) manual with me, you ate that 💅✨🦋