.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "File::ShareDir 3pm" .TH File::ShareDir 3pm "2014-05-11" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::ShareDir \- Locate per\-dist and per\-module shared files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::ShareDir \*(Aq:ALL\*(Aq; \& \& # Where are distribution\-level shared data files kept \& $dir = dist_dir(\*(AqFile\-ShareDir\*(Aq); \& \& # Where are module\-level shared data files kept \& $dir = module_dir(\*(AqFile::ShareDir\*(Aq); \& \& # Find a specific file in our dist/module shared dir \& $file = dist_file( \*(AqFile\-ShareDir\*(Aq, \*(Aqfile/name.txt\*(Aq); \& $file = module_file(\*(AqFile::ShareDir\*(Aq, \*(Aqfile/name.txt\*(Aq); \& \& # Like module_file, but search up the inheritance tree \& $file = class_file( \*(AqFoo::Bar\*(Aq, \*(Aqfile/name.txt\*(Aq ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The intent of File::ShareDir is to provide a companion to Class::Inspector and File::HomeDir, modules that take a process that is well-known by advanced Perl developers but gets a little tricky, and make it more available to the larger Perl community. .PP Quite often you want or need your Perl module (\s-1CPAN\s0 or otherwise) to have access to a large amount of read-only data that is stored on the file-system at run-time. .PP 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. .PP 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. .PP 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. .PP Another method is to put the data \*(L"file\*(R" after the _\|_DATA_\|_ compiler tag and limit yourself to access as a filehandle. .PP The problem to solve is really quite simple. .PP .Vb 1 \& 1. Write the data files to the system at install time. \& \& 2. Know where you put them at run\-time. .Ve .PP Perl's install system creates an \*(L"auto\*(R" directory for both every distribution and for every module file. .PP 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 \*(L"ancient masters\*(R". .PP But the same mechanism is available to any dist or module to store any sort of data. .SS "Using Data in your Module" .IX Subsection "Using Data in your Module" \&\f(CW\*(C`File::ShareDir\*(C'\fR forms one half of a two part solution. .PP Once the files have been installed to the correct directory, you can use \f(CW\*(C`File::ShareDir\*(C'\fR to find your files again after the installation. .PP For the installation half of the solution, see Module::Install and its \f(CW\*(C`install_share\*(C'\fR directive. .SH "FUNCTIONS" .IX Header "FUNCTIONS" \&\f(CW\*(C`File::ShareDir\*(C'\fR provides four functions for locating files and directories. .PP 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 \f(CW\*(Aq:ALL\*(Aq\fR tag. All of the following are equivalent. .PP .Vb 3 \& # Load but don\*(Aqt import, and then call directly \& use File::ShareDir; \& $dir = File::ShareDir::dist_dir(\*(AqMy\-Dist\*(Aq); \& \& # Import a single function \& use File::ShareDir \*(Aqdist_dir\*(Aq; \& dist_dir(\*(AqMy\-Dist\*(Aq); \& \& # Import all the functions \& use File::ShareDir \*(Aq:ALL\*(Aq; \& dist_dir(\*(AqMy\-Dist\*(Aq); .Ve .PP 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. .SS "dist_dir" .IX Subsection "dist_dir" .Vb 2 \& # Get a distribution\*(Aqs shared files directory \& my $dir = dist_dir(\*(AqMy\-Distribution\*(Aq); .Ve .PP The \f(CW\*(C`dist_dir\*(C'\fR function takes a single parameter of the name of an installed (\s-1CPAN\s0 or otherwise) distribution, and locates the shared data directory created at install time for it. .PP Returns the directory path as a string, or dies if it cannot be located or is not readable. .SS "module_dir" .IX Subsection "module_dir" .Vb 2 \& # Get a module\*(Aqs shared files directory \& my $dir = module_dir(\*(AqMy::Module\*(Aq); .Ve .PP The \f(CW\*(C`module_dir\*(C'\fR function takes a single parameter of the name of an installed (\s-1CPAN\s0 or otherwise) module, and locates the shared data directory created at install time for it. .PP In order to find the directory, the module \fBmust\fR be loaded when calling this function. .PP Returns the directory path as a string, or dies if it cannot be located or is not readable. .SS "dist_file" .IX Subsection "dist_file" .Vb 2 \& # Find a file in our distribution shared dir \& my $dir = dist_file(\*(AqMy\-Distribution\*(Aq, \*(Aqfile/name.txt\*(Aq); .Ve .PP The \f(CW\*(C`dist_file\*(C'\fR function takes two params of the distribution name and file name, locates the dist dir, and then finds the file within it, verifying that the file actually exists, and that it is readable. .PP 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 \&\f(CW\*(C`catfile\*(C'\fR method. .PP 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. .SS "module_file" .IX Subsection "module_file" .Vb 2 \& # Find a file in our module shared dir \& my $dir = module_file(\*(AqMy::Module\*(Aq, \*(Aqfile/name.txt\*(Aq); .Ve .PP The \f(CW\*(C`module_file\*(C'\fR function takes two params of the module name and file name. It locates the module dir, and then finds the file within it, verifying that the file actually exists, and that it is readable. .PP In order to find the directory, the module \fBmust\fR be loaded when calling this function. .PP 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 \&\f(CW\*(C`catfile\*(C'\fR method. .PP 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. .SS "class_file" .IX Subsection "class_file" .Vb 2 \& # Find a file in our module shared dir, or in our parent class \& my $dir = class_file(\*(AqMy::Module\*(Aq, \*(Aqfile/name.txt\*(Aq); .Ve .PP The \f(CW\*(C`module_file\*(C'\fR function takes two params of the module name and file name. It locates the module dir, and then finds the file within it, verifying that the file actually exists, and that it is readable. .PP In order to find the directory, the module \fBmust\fR be loaded when calling this function. .PP 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 \&\f(CW\*(C`catfile\*(C'\fR method. .PP If the file is \s-1NOT\s0 found for that module, \f(CW\*(C`class_file\*(C'\fR will scan up the module's \f(CW@ISA\fR tree, looking for the file in all of the parent classes. .PP This allows you to, in effect, \*(L"subclass\*(R" shared files. .PP 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. .SH "SUPPORT" .IX Header "SUPPORT" Bugs should always be submitted via the \s-1CPAN\s0 bug tracker .PP .PP For other issues, contact the maintainer. .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .SH "SEE ALSO" .IX Header "SEE ALSO" File::ShareDir::Install, File::HomeDir, Module::Install, Module::Install::Share, File::ShareDir::PAR, Dist::Zilla::Plugin::ShareDir .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005 \- 2011 Adam Kennedy. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module.