|
Packit |
bc8539 |
# NAME
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
File::ShareDir - Locate per-dist and per-module shared files
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# SYNOPSIS
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
use File::ShareDir ':ALL';
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Where are distribution-level shared data files kept
|
|
Packit |
bc8539 |
$dir = dist_dir('File-ShareDir');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Where are module-level shared data files kept
|
|
Packit |
bc8539 |
$dir = module_dir('File::ShareDir');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Find a specific file in our dist/module shared dir
|
|
Packit |
bc8539 |
$file = dist_file( 'File-ShareDir', 'file/name.txt');
|
|
Packit |
bc8539 |
$file = module_file('File::ShareDir', 'file/name.txt');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Like module_file, but search up the inheritance tree
|
|
Packit |
bc8539 |
$file = class_file( 'Foo::Bar', 'file/name.txt' );
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# DESCRIPTION
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The intent of [File::ShareDir](https://metacpan.org/pod/File::ShareDir) is to provide a companion to
|
|
Packit |
bc8539 |
[Class::Inspector](https://metacpan.org/pod/Class::Inspector) and [File::HomeDir](https://metacpan.org/pod/File::HomeDir), modules that take a
|
|
Packit |
bc8539 |
process that is well-known by advanced Perl developers but gets a
|
|
Packit |
bc8539 |
little tricky, and make it more available to the larger Perl community.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Quite often you want or need your Perl module (CPAN or otherwise)
|
|
Packit |
bc8539 |
to have access to a large amount of read-only data that is stored
|
|
Packit |
bc8539 |
on the file-system at run-time.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
On a linux-like system, this would be in a place such as /usr/share,
|
|
Packit |
bc8539 |
however Perl runs on a wide variety of different systems, and so
|
|
Packit |
bc8539 |
the use of any one location is unreliable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Perl provides a little-known method for doing this, but almost
|
|
Packit |
bc8539 |
nobody is aware that it exists. As a result, module authors often
|
|
Packit |
bc8539 |
go through some very strange ways to make the data available to
|
|
Packit |
bc8539 |
their code.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The most common of these is to dump the data out to an enormous
|
|
Packit |
bc8539 |
Perl data structure and save it into the module itself. The
|
|
Packit |
bc8539 |
result are enormous multi-megabyte .pm files that chew up a
|
|
Packit |
bc8539 |
lot of memory needlessly.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Another method is to put the data "file" after the \_\_DATA\_\_ compiler
|
|
Packit |
bc8539 |
tag and limit yourself to access as a filehandle.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The problem to solve is really quite simple.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
1. Write the data files to the system at install time.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
2. Know where you put them at run-time.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Perl's install system creates an "auto" directory for both
|
|
Packit |
bc8539 |
every distribution and for every module file.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
These are used by a couple of different auto-loading systems
|
|
Packit |
bc8539 |
to store code fragments generated at install time, and various
|
|
Packit |
bc8539 |
other modules written by the Perl "ancient masters".
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
But the same mechanism is available to any dist or module to
|
|
Packit |
bc8539 |
store any sort of data.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## Using Data in your Module
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
`File::ShareDir` forms one half of a two part solution.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Once the files have been installed to the correct directory,
|
|
Packit |
bc8539 |
you can use `File::ShareDir` to find your files again after
|
|
Packit |
bc8539 |
the installation.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
For the installation half of the solution, see [Module::Install](https://metacpan.org/pod/Module::Install)
|
|
Packit |
bc8539 |
and its `install_share` directive.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# FUNCTIONS
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
`File::ShareDir` provides four functions for locating files and
|
|
Packit |
bc8539 |
directories.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
For greater maintainability, none of these are exported by default
|
|
Packit |
bc8539 |
and you are expected to name the ones you want at use-time, or provide
|
|
Packit |
bc8539 |
the `':ALL'` tag. All of the following are equivalent.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Load but don't import, and then call directly
|
|
Packit |
bc8539 |
use File::ShareDir;
|
|
Packit |
bc8539 |
$dir = File::ShareDir::dist_dir('My-Dist');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Import a single function
|
|
Packit |
bc8539 |
use File::ShareDir 'dist_dir';
|
|
Packit |
bc8539 |
dist_dir('My-Dist');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Import all the functions
|
|
Packit |
bc8539 |
use File::ShareDir ':ALL';
|
|
Packit |
bc8539 |
dist_dir('My-Dist');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
All of the functions will check for you that the dir/file actually
|
|
Packit |
bc8539 |
exists, and that you have read permissions, or they will throw an
|
|
Packit |
bc8539 |
exception.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## dist\_dir
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Get a distribution's shared files directory
|
|
Packit |
bc8539 |
my $dir = dist_dir('My-Distribution');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The `dist_dir` function takes a single parameter of the name of an
|
|
Packit |
bc8539 |
installed (CPAN or otherwise) distribution, and locates the shared
|
|
Packit |
bc8539 |
data directory created at install time for it.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Returns the directory path as a string, or dies if it cannot be
|
|
Packit |
bc8539 |
located or is not readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## module\_dir
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Get a module's shared files directory
|
|
Packit |
bc8539 |
my $dir = module_dir('My::Module');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The `module_dir` function takes a single parameter of the name of an
|
|
Packit |
bc8539 |
installed (CPAN or otherwise) module, and locates the shared data
|
|
Packit |
bc8539 |
directory created at install time for it.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
In order to find the directory, the module **must** be loaded when
|
|
Packit |
bc8539 |
calling this function.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Returns the directory path as a string, or dies if it cannot be
|
|
Packit |
bc8539 |
located or is not readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## dist\_file
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Find a file in our distribution shared dir
|
|
Packit |
bc8539 |
my $dir = dist_file('My-Distribution', 'file/name.txt');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The `dist_file` function takes two params of the distribution name
|
|
Packit |
bc8539 |
and file name, locates the dist dir, and then finds the file within
|
|
Packit |
bc8539 |
it, verifying that the file actually exists, and that it is readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The filename should be a relative path in the format of your local
|
|
Packit |
bc8539 |
filesystem. It will simply added to the directory using [File::Spec](https://metacpan.org/pod/File::Spec)'s
|
|
Packit |
bc8539 |
`catfile` method.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Returns the file path as a string, or dies if the file or the dist's
|
|
Packit |
bc8539 |
directory cannot be located, or the file is not readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## module\_file
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Find a file in our module shared dir
|
|
Packit |
bc8539 |
my $dir = module_file('My::Module', 'file/name.txt');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The `module_file` function takes two params of the module name
|
|
Packit |
bc8539 |
and file name. It locates the module dir, and then finds the file within
|
|
Packit |
bc8539 |
it, verifying that the file actually exists, and that it is readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
In order to find the directory, the module **must** be loaded when
|
|
Packit |
bc8539 |
calling this function.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The filename should be a relative path in the format of your local
|
|
Packit |
bc8539 |
filesystem. It will simply added to the directory using [File::Spec](https://metacpan.org/pod/File::Spec)'s
|
|
Packit |
bc8539 |
`catfile` method.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Returns the file path as a string, or dies if the file or the dist's
|
|
Packit |
bc8539 |
directory cannot be located, or the file is not readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
## class\_file
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# Find a file in our module shared dir, or in our parent class
|
|
Packit |
bc8539 |
my $dir = class_file('My::Module', 'file/name.txt');
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The `module_file` function takes two params of the module name
|
|
Packit |
bc8539 |
and file name. It locates the module dir, and then finds the file within
|
|
Packit |
bc8539 |
it, verifying that the file actually exists, and that it is readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
In order to find the directory, the module **must** be loaded when
|
|
Packit |
bc8539 |
calling this function.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The filename should be a relative path in the format of your local
|
|
Packit |
bc8539 |
filesystem. It will simply added to the directory using [File::Spec](https://metacpan.org/pod/File::Spec)'s
|
|
Packit |
bc8539 |
`catfile` method.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
If the file is NOT found for that module, `class_file` will scan up
|
|
Packit |
bc8539 |
the module's @ISA tree, looking for the file in all of the parent
|
|
Packit |
bc8539 |
classes.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
This allows you to, in effect, "subclass" shared files.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Returns the file path as a string, or dies if the file or the dist's
|
|
Packit |
bc8539 |
directory cannot be located, or the file is not readable.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# SUPPORT
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Bugs should always be submitted via the CPAN bug tracker
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
[http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir)
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
For other issues, contact the maintainer.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# AUTHOR
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Adam Kennedy <adamk@cpan.org>
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# SEE ALSO
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
[File::ShareDir::Install](https://metacpan.org/pod/File::ShareDir::Install), [File::HomeDir](https://metacpan.org/pod/File::HomeDir),
|
|
Packit |
bc8539 |
[Module::Install](https://metacpan.org/pod/Module::Install), [Module::Install::Share](https://metacpan.org/pod/Module::Install::Share),
|
|
Packit |
bc8539 |
[File::ShareDir::PAR](https://metacpan.org/pod/File::ShareDir::PAR), [Dist::Zilla::Plugin::ShareDir](https://metacpan.org/pod/Dist::Zilla::Plugin::ShareDir)
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
# COPYRIGHT
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
Copyright 2005 - 2011 Adam Kennedy.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
This program is free software; you can redistribute
|
|
Packit |
bc8539 |
it and/or modify it under the same terms as Perl itself.
|
|
Packit |
bc8539 |
|
|
Packit |
bc8539 |
The full text of the license can be found in the
|
|
Packit |
bc8539 |
LICENSE file included with this module.
|