File::ShareDir::Tiny - Locate per-dist and per-module shared files

       Leon Timmermans <fawaka@gmail.com>

       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.

perl v5.40.0                                       2024-09-08                          File::ShareDir::Tiny(3pm)

       Quite often you want or need your Perl module (CPAN or otherwise) to have access to a large amount of
       read-only data that is stored on the file-system at run-time.

       On a linux-like system, this would be in a place such as /usr/share, however Perl runs on a wide variety
       of different systems, and so the use of any one location is unreliable.

       This module provides a more portable way to have (read-only) data for your module.

   UsingDatainyourModule
       "File::ShareDir::Tiny" forms 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.

       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.

       "File::ShareDir::Tiny" provides four functions for locating files and directories.

       For greater maintainability, none of these are exported by default and you are expected to name the ones
       you want at use-time, or provide the ':ALL' tag. All of the following are equivalent.

         # 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');

       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.

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

       The "dist_dir" function takes a single parameter of the name of an installed (CPAN or otherwise)
       distribution, and locates the shared data directory created at install time for it.

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

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

       The "module_dir" function takes a single parameter of the name of an installed (CPAN or otherwise)
       module, and locates the shared data directory created at install time for it.

       Note that unlike File::ShareDir the module does not have be loaded when calling this function.

       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 of the distribution name and file name, locates the dist
       directory, and then finds the file within it, verifying that the file actually exists, and that it is
       readable.

       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 of the module name and 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.

       In order to find the directory, the module must be loaded when calling this function.

       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.

       File::ShareDir::Tiny - Locate per-dist and per-module shared files

         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');

       version 0.001