File::ShareDir(3)

📦
version 1.118 · 11 versions
, in opensuse-leap 16.0

💖 NAME 💖

File::ShareDir — bestie, this is the module that finds stuff for you. Specifically: locate per-dist and per-module shared files. That's it, that's the whole gig. ✨

(this is File::ShareDir(3), from the User Contributed Perl Documentation set — yes, the fancy official Perl docs club 🎀)

✨ SYNOPSIS ✨

okay so here's the whole vibe in code form, no cap:

use File::ShareDir ':ALL';

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

iconic. moving on 🦋

🌸 DESCRIPTION 🌸

so the whole point of File::ShareDir, per the original vibes, is to be a companion to Class::Inspector and File::HomeDir — modules that do stuff that's like, super well-known to advanced Perl devs but gets a lil tricky, and this makes it more available to the larger Perl community. taking one for the team fr fr 🫶

quite often you want (or need) your Perl module — CPAN or otherwise — to have access to a large amount of read-only data that's stored on the file-system at run-time. very normal. very demure.

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 is the plot twist.)

Perl provides a little-known method for doing this, but almost nobody is aware that it exists. As a result, module authors often go through some very strange ways to make the data available to their code. 💀

the most common of these is to dump the data out to an enormous Perl data structure and save it into the module itself. The result are enormous multi-megabyte .pm files that chew up a lot of memory needlessly. not the multi-megabyte .pm files 😭🙈

another method is to put the data "file" after the __DATA__ compiler tag and limit yourself to access as a filehandle. meh.

the problem to solve is really quite simple. like, really:

  1. Write the data files to the system at install time.
  2. Know where you put them at run-time.

Perl's install system creates an "auto" directory for both every distribution and for every module file.

these are used by a couple of different auto-loading systems to store code fragments generated at install time, and various other modules written by the Perl "ancient masters". 👑 respect the elders.

but the same mechanism is available to any dist or module to store any sort of data. slay.

Using Data in your Module

File::ShareDir forms one half of a two part solution.

once the files have been installed to the correct directory, you can use File::ShareDir to find your files again after the installation. that's the second half. that's the job. 💅

for the installation half of the solution, see File::ShareDir::Install and its install_share directive.

using File::ShareDir::Install together with File::ShareDir allows one to rely on the files in appropriate dist_dir() or module_dir() in development phase, too. development phase representation matters!! 🎀

🔥 FUNCTIONS 🔥

File::ShareDir 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;
$dir = File::ShareDir::dist_dir('My-Dist');

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

# Import all the functions
use File::ShareDir ':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. so you get receipts before you get surprises 💅✨

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. 💀 (die is giving main character energy, honestly.)

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.

important✨ in order to find the directory, the module must be loaded when calling this function. like, already loaded. no loading, no directory.

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. (yes, the original really says "it will simply added" — we keep the lore intact 🫶)

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.

again bestie✨ 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. 😭

class_file

# Find a file in our module shared dir, or in our parent class
my $dir = class_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. (yes — the original describes class_file while naming module_file here. the lore. we preserve it. 🙈)

reminder✨ 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.

and now the fun part: if the file is NOT found for that module, class_file will scan up the module's @ISA tree, looking for the file in all of the parent classes. 🔥

this allows you to, in effect, "subclass" shared files. it's giving inheritance but make it files. iconic.

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. 💀

🦋 EXTENDING 🦋

Overriding Directory Resolution

File::ShareDir has two convenience hashes for people who have advanced usage requirements of File::ShareDir such as using uninstalled "share" directories during development. yup, you can hack it. legally. 💅

#
# Dist-Name => /absolute/path/for/DistName/share/dir
#
%File::ShareDir::DIST_SHARE

#
# Module::Name => /absolute/path/for/Module/Name/share/dir
#
%File::ShareDir::MODULE_SHARE

setting these values any time before the corresponding calls:

dist_dir('Dist-Name')
dist_file('Dist-Name','some/file');

module_dir('Module::Name');
module_file('Module::Name','some/file');

will override the base directory for resolving those calls. 👑

an example of where this would be useful is in a test for a module that depends on files installed into a share directory, to enable the tests to use the development copy without needing to install them first. no install required, we love to see it 🎀

use File::ShareDir;
use Cwd qw( getcwd );
use File::Spec::Functions qw( rel2abs catdir );

$File::ShareDir::MODULE_SHARE{'Foo::Module'} = rel2abs(catfile(getcwd,'share'));

use Foo::Module;

# internal calls in Foo::Module to module_file('Foo::Module','bar') now resolves to
# the source trees share/ directory instead of something in @INC

🌈 SUPPORT 🌈

Bugs should always be submitted via the CPAN request tracker, see below. always!! 🙏

you can find documentation for this module with the perldoc command.

perldoc File::ShareDir

you can also look for information at:

Where can I go for other help?

if you have a bug report, a patch or a suggestion, please open a new report ticket at CPAN (but please check previous reports first in case your issue has already been addressed). like, do a quick search bestie, i'm begging 🥺

report tickets should contain a detailed description of the bug or enhancement request and at least an easily verifiable way of reproducing the issue or fix. Patches are always welcome, too. 🫶

Where can I go for help with a concrete version?

bugs and feature requests are accepted against the latest version only. To get patches for earlier versions, you need to get an agreement with a developer of your choice — who may or not report the issue and a suggested fix upstream (depends on the license you have chosen). so like, make friends first. 💜

Business support and maintenance

for business support you can contact the maintainer via his CPAN email address. Please keep in mind that business support is neither available for free nor are you eligible to receive any support based on the license distributed with this package. 💀 real talk: business support is a paid activity, not a freebie from the license.

👑 AUTHOR 👑

Adam Kennedy <adamk@cpan.org>

MAINTAINER

Jens Rehsack <rehsack@cpan.org>

⭐ SEE ALSO ⭐

File::ShareDir::Install, File::ConfigDir, File::HomeDir, Module::Install, Module::Install::Share, File::ShareDir::PAR, Dist::Zilla::Plugin::ShareDir

Copyright 2005 - 2011 Adam Kennedy, Copyright 2014 - 2018 Jens Rehsack.

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 gem was perl v5.42.0, dated 2020-10-22, and it's the File::ShareDir(3) manpage — go forth and locate your shared files, you absolute icon. 🦋💅✨

📦 where this page comes from