local-lib5/man/man3/File::ShareDir.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "File::ShareDir 3"
 132 .TH File::ShareDir 3 "2009-11-23" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 File::ShareDir \- Locate per\-dist and per\-module shared files
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use File::ShareDir ':ALL';
 139 .Ve
 140 .PP
 141 .Vb 2
 142 \&  # Where are distribution\-level shared data files kept
 143 \&  $dir = dist_dir('File\-ShareDir');
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  # Where are module\-level shared data files kept
 148 \&  $dir = module_dir('File::ShareDir');
 149 .Ve
 150 .PP
 151 .Vb 3
 152 \&  # Find a specific file in our dist/module shared dir
 153 \&  $file = dist_file(  'File\-ShareDir',  'file/name.txt');
 154 \&  $file = module_file('File::ShareDir', 'file/name.txt');
 155 .Ve
 156 .PP
 157 .Vb 2
 158 \&  # Like module_file, but search up the inheritance tree
 159 \&  $file = class_file( 'Foo::Bar', 'file/name.txt' );
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 The intent of File::ShareDir is to provide a companion to
 164 Class::Inspector and File::HomeDir, modules that take a
 165 process that is well-known by advanced Perl developers but gets a
 166 little tricky, and make it more available to the larger Perl community.
 167 .PP
 168 Quite often you want or need your Perl module (\s-1CPAN\s0 or otherwise)
 169 to have access to a large amount of read-only data that is stored
 170 on the file-system at run\-time.
 171 .PP
 172 On a linux-like system, this would be in a place such as /usr/share,
 173 however Perl runs on a wide variety of different systems, and so
 174 the use of any one location is unreliable.
 175 .PP
 176 Perl provides a little-known method for doing this, but almost
 177 nobody is aware that it exists. As a result, module authors often
 178 go through some very strange ways to make the data available to
 179 their code.
 180 .PP
 181 The most common of these is to dump the data out to an enormous
 182 Perl data structure and save it into the module itself. The
 183 result are enormous multi-megabyte .pm files that chew up a
 184 lot of memory needlessly.
 185 .PP
 186 Another method is to put the data \*(L"file\*(R" after the _\|_DATA_\|_ compiler
 187 tag and limit yourself to access as a filehandle.
 188 .PP
 189 The problem to solve is really quite simple.
 190 .PP
 191 .Vb 1
 192 \&  1. Write the data files to the system at install time.
 193 .Ve
 194 .PP
 195 .Vb 1
 196 \&  2. Know where you put them at run\-time.
 197 .Ve
 198 .PP
 199 Perl's install system creates an \*(L"auto\*(R" directory for both
 200 every distribution and for every module file.
 201 .PP
 202 These are used by a couple of different auto-loading systems
 203 to store code fragments generated at install time, and various
 204 other modules written by the Perl \*(L"ancient masters\*(R".
 205 .PP
 206 But the same mechanism is available to any dist or module to
 207 store any sort of data.
 208 .Sh "Using Data in your Module"
 209 .IX Subsection "Using Data in your Module"
 210 \&\f(CW\*(C`File::ShareDir\*(C'\fR forms one half of a two part solution.
 211 .PP
 212 Once the files have been installed to the correct directory,
 213 you can use \f(CW\*(C`File::ShareDir\*(C'\fR to find your files again after
 214 the installation.
 215 .PP
 216 For the installation half of the solution, see Module::Install
 217 and its \f(CW\*(C`install_share\*(C'\fR directive.
 218 .SH "FUNCTIONS"
 219 .IX Header "FUNCTIONS"
 220 \&\f(CW\*(C`File::ShareDir\*(C'\fR provides four functions for locating files and
 221 directories.
 222 .PP
 223 For greater maintainability, none of these are exported by default
 224 and you are expected to name the ones you want at use\-time, or provide
 225 the \f(CW':ALL'\fR tag. All of the following are equivalent.
 226 .PP
 227 .Vb 3
 228 \&  # Load but don't import, and then call directly
 229 \&  use File::ShareDir;
 230 \&  $dir = File::ShareDir::dist_dir('My\-Dist');
 231 .Ve
 232 .PP
 233 .Vb 3
 234 \&  # Import a single function
 235 \&  use File::ShareDir 'dist_dir';
 236 \&  dist_dir('My\-Dist');
 237 .Ve
 238 .PP
 239 .Vb 3
 240 \&  # Import all the functions
 241 \&  use File::ShareDir ':ALL';
 242 \&  dist_dir('My\-Dist');
 243 .Ve
 244 .PP
 245 All of the functions will check for you that the dir/file actually
 246 exists, and that you have read permissions, or they will throw an
 247 exception.
 248 .Sh "dist_dir"
 249 .IX Subsection "dist_dir"
 250 .Vb 2
 251 \&  # Get a distribution's shared files directory
 252 \&  my $dir = dist_dir('My\-Distribution');
 253 .Ve
 254 .PP
 255 The \f(CW\*(C`dist_dir\*(C'\fR function takes a single parameter of the name of an
 256 installed (\s-1CPAN\s0 or otherwise) distribution, and locates the shared
 257 data directory created at install time for it.
 258 .PP
 259 Returns the directory path as a string, or dies if it cannot be
 260 located or is not readable.
 261 .Sh "module_dir"
 262 .IX Subsection "module_dir"
 263 .Vb 2
 264 \&  # Get a module's shared files directory
 265 \&  my $dir = module_dir('My::Module');
 266 .Ve
 267 .PP
 268 The \f(CW\*(C`module_dir\*(C'\fR function takes a single parameter of the name of an
 269 installed (\s-1CPAN\s0 or otherwise) module, and locates the shared data
 270 directory created at install time for it.
 271 .PP
 272 In order to find the directory, the module \fBmust\fR be loaded when
 273 calling this function.
 274 .PP
 275 Returns the directory path as a string, or dies if it cannot be
 276 located or is not readable.
 277 .Sh "dist_file"
 278 .IX Subsection "dist_file"
 279 .Vb 2
 280 \&  # Find a file in our distribution shared dir
 281 \&  my $dir = dist_file('My\-Distribution', 'file/name.txt');
 282 .Ve
 283 .PP
 284 The \f(CW\*(C`dist_file\*(C'\fR function takes two params of the distribution name
 285 and file name, locates the dist dir, and then finds the file within
 286 it, verifying that the file actually exists, and that it is readable.
 287 .PP
 288 The filename should be a relative path in the format of your local
 289 filesystem. It will simply added to the directory using File::Spec's
 290 \&\f(CW\*(C`catfile\*(C'\fR method.
 291 .PP
 292 Returns the file path as a string, or dies if the file or the dist's
 293 directory cannot be located, or the file is not readable.
 294 .Sh "module_file"
 295 .IX Subsection "module_file"
 296 .Vb 2
 297 \&  # Find a file in our module shared dir
 298 \&  my $dir = module_file('My::Module', 'file/name.txt');
 299 .Ve
 300 .PP
 301 The \f(CW\*(C`module_file\*(C'\fR function takes two params of the module name
 302 and file name. It locates the module dir, and then finds the file within
 303 it, verifying that the file actually exists, and that it is readable.
 304 .PP
 305 In order to find the directory, the module \fBmust\fR be loaded when
 306 calling this function.
 307 .PP
 308 The filename should be a relative path in the format of your local
 309 filesystem. It will simply added to the directory using File::Spec's
 310 \&\f(CW\*(C`catfile\*(C'\fR method.
 311 .PP
 312 Returns the file path as a string, or dies if the file or the dist's
 313 directory cannot be located, or the file is not readable.
 314 .Sh "class_file"
 315 .IX Subsection "class_file"
 316 .Vb 2
 317 \&  # Find a file in our module shared dir, or in our parent class
 318 \&  my $dir = class_file('My::Module', 'file/name.txt');
 319 .Ve
 320 .PP
 321 The \f(CW\*(C`module_file\*(C'\fR function takes two params of the module name
 322 and file name. It locates the module dir, and then finds the file within
 323 it, verifying that the file actually exists, and that it is readable.
 324 .PP
 325 In order to find the directory, the module \fBmust\fR be loaded when
 326 calling this function.
 327 .PP
 328 The filename should be a relative path in the format of your local
 329 filesystem. It will simply added to the directory using File::Spec's
 330 \&\f(CW\*(C`catfile\*(C'\fR method.
 331 .PP
 332 If the file is \s-1NOT\s0 found for that module, \f(CW\*(C`class_file\*(C'\fR will scan up
 333 the module's \f(CW@ISA\fR tree, looking for the file in all of the parent
 334 classes.
 335 .PP
 336 This allows you to, in effect, \*(L"subclass\*(R" shared files.
 337 .PP
 338 Returns the file path as a string, or dies if the file or the dist's
 339 directory cannot be located, or the file is not readable.
 340 .SH "SUPPORT"
 341 .IX Header "SUPPORT"
 342 Bugs should always be submitted via the \s-1CPAN\s0 bug tracker
 343 .PP
 344 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File\-ShareDir>
 345 .PP
 346 For other issues, contact the maintainer.
 347 .SH "AUTHOR"
 348 .IX Header "AUTHOR"
 349 Adam Kennedy <adamk@cpan.org>
 350 .SH "SEE ALSO"
 351 .IX Header "SEE ALSO"
 352 File::HomeDir, Module::Install, Module::Install::Share,
 353 File::ShareDir::PAR
 354 .SH "COPYRIGHT"
 355 .IX Header "COPYRIGHT"
 356 Copyright 2005 \- 2009 Adam Kennedy.
 357 .PP
 358 This program is free software; you can redistribute
 359 it and/or modify it under the same terms as Perl itself.
 360 .PP
 361 The full text of the license can be found in the
 362 \&\s-1LICENSE\s0 file included with this module.