1File::ShareDir(3)     User Contributed Perl Documentation    File::ShareDir(3)
2
3
4

NAME

6       File::ShareDir - Locate per-dist and per-module shared files
7

SYNOPSIS

9         use File::SharedDir ':ALL';
10
11         # Where are distribution-level shared data files kept
12         $dir = dist_dir('File-ShareDir');
13
14         # Where are module-level shared data files kept
15         $dir = module_dir('File::ShareDir');
16
17         # Find a specific file in our dist/module shared dir
18         $file = dist_file(  'File-ShareDir',  'file/name.txt');
19         $file = module_file('File::ShareDir', 'file/name.txt');
20
21         # Like module_file, but search up the inheritance tree
22         $file = class_file( 'Foo::Bar', 'file/name.txt' );
23

DESCRIPTION

25       The intent of File::ShareDir is to provide a companion to
26       Class::Inspector and File::HomeDir, modules that take a process that is
27       well-known by advanced Perl developers but gets a little tricky, and
28       make it more available to the larger Perl community.
29
30       Quite often you want or need your Perl module (CPAN or otherwise) to
31       have access to a large amount of read-only data that is stored on the
32       file-system at run-time.
33
34       On a linux-like system, this would be in a place such as /usr/share,
35       however Perl runs on a wide variety of different systems, and so the
36       use of any one location is unreliable.
37
38       Perl provides a little-known method for doing this, but almost nobody
39       is aware that it exists. As a result, module authors often go through
40       some very strange ways to make the data available to their code.
41
42       The most common of these is to dump the data out to an enormous Perl
43       data structure and save it into the module itself. The result are
44       enormous multi-megabyte .pm files that chew up a lot of memory
45       needlessly.
46
47       Another method is to put the data "file" after the __DATA__ compiler
48       tag and limit yourself to access as a filehandle.
49
50       The problem to solve is really quite simple.
51
52         1. Write the data files to the system at install time.
53
54         2. Know where you put them at run-time.
55
56       Perl's install system creates an "auto" directory for both every
57       distribution and for every module file.
58
59       These are used by a couple of different auto-loading systems to store
60       code fragments generated at install time, and various other modules
61       written by the Perl "ancient masters".
62
63       But the same mechanism is available to any dist or module to store any
64       sort of data.
65
66   Using Data in your Module
67       "File::ShareDir" forms one half of a two part solution.
68
69       Once the files have been installed to the correct directory, you can
70       use "File::ShareDir" to find your files again after the installation.
71
72       For the installation half of the solution, see Module::Install and its
73       "install_share" directive.
74

FUNCTIONS

76       "File::ShareDir" provides four functions for locating files and
77       directories.
78
79       For greater maintainability, none of these are exported by default and
80       you are expected to name the ones you want at use-time, or provide the
81       ':ALL' tag. All of the following are equivalent.
82
83         # Load but don't import, and then call directly
84         use File::ShareDir;
85         $dir = File::ShareDir::dist_dir('My-Dist');
86
87         # Import a single function
88         use File::ShareDir 'dist_dir';
89         dist_dir('My-Dist');
90
91         # Import all the functions
92         use File::ShareDir ':ALL';
93         dist_dir('My-Dist');
94
95       All of the functions will check for you that the dir/file actually
96       exists, and that you have read permissions, or they will throw an
97       exception.
98
99   dist_dir
100         # Get a distribution's shared files directory
101         my $dir = dist_dir('My-Distribution');
102
103       The "dist_dir" function takes a single parameter of the name of an
104       installed (CPAN or otherwise) distribution, and locates the shared data
105       directory created at install time for it.
106
107       Returns the directory path as a string, or dies if it cannot be located
108       or is not readable.
109
110   module_dir
111         # Get a module's shared files directory
112         my $dir = module_dir('My::Module');
113
114       The "module_dir" function takes a single parameter of the name of an
115       installed (CPAN or otherwise) module, and locates the shared data
116       directory created at install time for it.
117
118       In order to find the directory, the module must be loaded when calling
119       this function.
120
121       Returns the directory path as a string, or dies if it cannot be located
122       or is not readable.
123
124   dist_file
125         # Find a file in our distribution shared dir
126         my $dir = dist_file('My-Distribution', 'file/name.txt');
127
128       The "dist_file" function takes two params of the distribution name and
129       file name, locates the dist dir, and then finds the file within it,
130       verifying that the file actually exists, and that it is readable.
131
132       The filename should be a relative path in the format of your local
133       filesystem. It will simply added to the directory using File::Spec's
134       "catfile" method.
135
136       Returns the file path as a string, or dies if the file or the dist's
137       directory cannot be located, or the file is not readable.
138
139   module_file
140         # Find a file in our module shared dir
141         my $dir = module_file('My::Module', 'file/name.txt');
142
143       The "module_file" function takes two params of the module name and file
144       name. It locates the module dir, and then finds the file within it,
145       verifying that the file actually exists, and that it is readable.
146
147       In order to find the directory, the module must be loaded when calling
148       this function.
149
150       The filename should be a relative path in the format of your local
151       filesystem. It will simply added to the directory using File::Spec's
152       "catfile" method.
153
154       Returns the file path as a string, or dies if the file or the dist's
155       directory cannot be located, or the file is not readable.
156
157   class_file
158         # Find a file in our module shared dir, or in our parent class
159         my $dir = class_file('My::Module', 'file/name.txt');
160
161       The "module_file" function takes two params of the module name and file
162       name. It locates the module dir, and then finds the file within it,
163       verifying that the file actually exists, and that it is readable.
164
165       In order to find the directory, the module must be loaded when calling
166       this function.
167
168       The filename should be a relative path in the format of your local
169       filesystem. It will simply added to the directory using File::Spec's
170       "catfile" method.
171
172       If the file is NOT found for that module, "class_file" will scan up the
173       module's @ISA tree, looking for the file in all of the parent classes.
174
175       This allows you to, in effect, "subclass" shared files.
176
177       Returns the file path as a string, or dies if the file or the dist's
178       directory cannot be located, or the file is not readable.
179

SUPPORT

181       Bugs should always be submitted via the CPAN bug tracker
182
183       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir
184       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir>
185
186       For other issues, contact the maintainer.
187

AUTHOR

189       Adam Kennedy <adamk@cpan.org>
190

SEE ALSO

192       File::HomeDir, Module::Install, Module::Install::Share
193
195       Copyright 2005 - 2008 Adam Kennedy.
196
197       This program is free software; you can redistribute it and/or modify it
198       under the same terms as Perl itself.
199
200       The full text of the license can be found in the LICENSE file included
201       with this module.
202
203
204
205perl v5.12.0                      2008-07-17                 File::ShareDir(3)
Impressum