NAME
File::ShareDir::Tiny - Locate per-dist and per-module shared files
VERSION
version 0.001
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
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.
Using Data in your Module
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.
FUNCTIONS
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.
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.