File::...ir::PAR(3pm)

✨ File::ShareDir::PAR ✨

okay bestie, gather round 💖 this is the File::ShareDir::PAR page from the User Contributed Perl Documentation, and yes it's giving "niche but essential" energy. it's File::ShareDir, but with PAR support bolted on. let's get into it 🫶

---

🌸 NAME 🌸

File::ShareDir::PAR — literally File::ShareDir, except it also speaks PAR. no cap 💅

---

🦋 SYNOPSIS 🦋

use File::SharedDir::PAR ':ALL';
# exact same interface as the normal File::ShareDir:

# Where are distribution-level shared data files kept
$dir = dist_dir('File-ShareDir');

# Where are module-level shared data files kept
$dir = module_dir('File::ShareDir');

# Find a specific file in our dist/module shared dir
$file = dist_file(  'File-ShareDir',  'file/name.txt');
$file = module_file('File::ShareDir', 'file/name.txt');

# Like module_file, but search up the inheritance tree
$file = class_file( 'Foo::Bar', 'file/name.txt' );

so, you could also choose to install the File::ShareDir::PAR functions straight into File::ShareDir so they're globally available, main character style 👑. if you want that, you have to do this before literally anybody is allowed to import functions from File::ShareDir:

use File::ShareDir::PAR 'global';

like, before. before before. no sneaking it in later 🙈

---

💀 WARNING 💀

bestie. listen. this module contains highly experimental code. if you wanna load modules out of .par files with PAR and then reach their shared directory through File::ShareDir, you basically have no choice but to use this. but beware — here be dragons 🐉😭

---

🎀 DESCRIPTION 🎀

File::ShareDir::PAR hands you the exact same functionality as File::ShareDir, but it tries so hard to be compatible with PAR packaged applications. it's giving supportive bestie energy 🫶

here's the tea ☕: the whole concept of "a distribution-specific or module-specific share directory" gets a lil hazy the moment you're loading absolutely everything out of one single file. PAR uses an @INC hook to intercept every attempt to load a module. File::ShareDir, meanwhile, uses the directory structure you'd typically find in the directories listed in @INC to store shared data. and in a PAR environment? yeah, that's not necessarily possible. not the vibe. 😭

so when you call one of the functions this module gives you, it will take care to search in any of the currently loaded .par files before scanning @INC. and that's the same order of preference you get for loading modules when PAR is in effect — consistent, iconic, slay ✨. if the path or file you're asking for is found in one of those loaded .par files, that containing .par file gets extracted, and the path returned will point to the extracted copy on disk.

now, depending on how you're using PAR, files extracted this way are either cleaned up after the program terminates, or cached for further executions. either way? you're safe if you use the shared data as read-only data. but if you write to it, your changes may be lost after the program ends. so like. don't do that 🙈💀

for any further usage info — including the list of exportable functions — please go read the documentation of File::ShareDir. that's where the rest of the lore lives 📚

---

🌈 SUPPORT 🌈

bugs should always be submitted via the CPAN bug tracker:

<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir-PAR>

and for other issues, hit up the PAR mailing list: <par@perl.org> 💌

---

👑 AUTHOR 👑

Steffen Mueller <smueller@cpan.org>

the code was adapted from Adam Kennedy's work on File::ShareDir — shoutout to the OG 🫡

---

⭐ SEE ALSO ⭐

• File::ShareDir
• File::HomeDir
• Module::Install
• Module::Install::Share

---

💜 COPYRIGHT AND LICENSE 💜

Copyright (c) 2008-2010 Steffen Mueller. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

the portions of code that were copied from File::ShareDir are:

Copyright (c) 2005, 2006 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 📄

---

and that's the whole page, bestie!! this one's from perl v5.34.0, dated 2022-06-13, and it's filed under File::...ir::PAR(3pm) 💖✨ go read your shared data responsibly 🎀🦋