File::...::Tiny(3pm)

✨ NAME ✨

File::ShareDir::Tiny — bestie, this is how you find your per-dist and per-module shared files 💖

It lives in the User Contributed Perl Documentation, and honestly? iconic.

🌸 VERSION 🌸

version 0.001 — babes, it's a baby version number, we love a fresh release 🍼✨

🎀 SYNOPSIS 🎀

  use File::ShareDir::Tiny ':ALL';

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

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

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

---

💅 DESCRIPTION 💅

okay so picture this: your Perl module (CPAN or otherwise, no judgement either way 🫶) needs a whole pile of read-only data sitting on the file-system at run-time. Like, a LOT of it.

On a linux-like system you'd just yeet it into somewhere like /usr/share, right? Cute. But Perl runs on a wide variety of different systems, and so relying on any one single location is unreliable. It's giving chaos. 😭

So this module gives you a way more portable way to have (read-only) data for your module. Portable slay. 🌈

🦋 Using Data in your Module 🦋

File::ShareDir::Tiny is literally one half of a two part solution. Once the files have been installed to the correct directory, you can use File::ShareDir::Tiny to find your files again after the installation. Find + installed = reunited and it feels so good ✨

For the installation half of the solution, there are several options available that depend on your installation tool:

• For ExtUtils::MakeMaker there is File::ShareDir::Install
• Other tools like Module::Build, Module::Build::Tiny and Dist::Build have built in support for sharedirs 👑

Pick your fighter, they all get the job done.

---

🔥 FUNCTIONS 🔥

File::ShareDir::Tiny provides four functions for locating files and directories. Four! A little squad 🫶

For greater maintainability, none of these are exported by default — nope, not a single one, no sneaky auto-imports here. You are expected to name the ones you want at use-time, or provide the ':ALL' tag. All of the following are equivalent, fr fr:

  # Load but don't import, and then call directly
  use File::ShareDir::Tiny;
  $dir = File::ShareDir::Tiny::dist_dir('My-Dist');

  # Import a single function
  use File::ShareDir::Tiny 'dist_dir';
  dist_dir('My-Dist');

  # Import all the functions
  use File::ShareDir::Tiny ':ALL';
  dist_dir('My-Dist');

⚠️ heads up bestie: all of the functions will check for you that the dir/file actually exists, and that you have read permissions, or they will throw an exception. So if it vanishes on you, that's not a vibe, that's a die. 💀

---

💜 dist_dir 💜

  # Get a distribution's shared files directory
  my $dir = dist_dir('My-Distribution');

The dist_dir function takes a single parameter — the name of an installed (CPAN or otherwise) distribution — and locates the shared data directory created at install time for it. Like a little detective for your dist 🕵️

Returns the directory path as a string, or dies if it cannot be located or is not readable. no cap.

---

🩵 module_dir 🩵

  # Get a module's shared files directory
  my $dir = module_dir('My::Module');

The module_dir function takes a single parameter — the name of an installed (CPAN or otherwise) module — and locates the shared data directory created at install time for it. Same energy as dist_dir, but make it a module. 💫

Note that unlike File::ShareDir the module does not have be loaded when calling this function. (yes, that phrasing is exactly how the original says it, and honestly? it's giving unbothered, and I respect it ✨)

Returns the directory path as a string, or dies if it cannot be located or is not readable.

---

💖 dist_file 💖

  # Find a file in our distribution shared dir
  my $dir = dist_file('My-Distribution', 'file/name.txt');

The dist_file function takes two parameters — the distribution name and the file name — locates the dist directory, and then finds the file within it, verifying that the file actually exists, and that it is readable. Double-checking queen 👑

The filename should be a relative path in the format of your local filesystem. It will simply added to the directory using File::Spec's catfile method.

Returns the file path as a string, or dies if the file or the dist's directory cannot be located, or the file is not readable.

---

🧚 module_file 🧚

  # Find a file in our module shared dir
  my $dir = module_file('My::Module', 'file/name.txt');

The module_file function takes two parameters — the module name and the file name. It locates the module directory, and then finds the file within it, verifying that the file actually exists, and that it is readable. Same perfectionism, different scope, obsessed. 💅

In order to find the directory, the module must be loaded when calling this function. Like, actually loaded. Required. Non-negotiable 🔥

The filename should be a relative path in the format of your local filesystem. It will simply added to the directory using File::Spec's catfile method.

Returns the file path as a string, or dies if the file or the dist's directory cannot be located, or the file is not readable.

---

👑 AUTHOR 👑

Leon Timmermans <fawaka@gmail.com>

💜 COPYRIGHT AND LICENSE 💜

This software is copyright (c) 2024 by Leon Timmermans.

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

---

aaaand that's the whole page bestie!! 🌸 It's perl v5.40.0, dated 2024-09-08, and it ships as File::...::Tiny(3pm) from the User Contributed Perl Documentation. go forth and find your files 💖🦋🎀