.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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 >0, 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 .\" ======================================================================== .\" .IX Title "File::ShareDir::PAR 3pm" .TH File::ShareDir::PAR 3pm "2022-06-13" "perl v5.34.0" "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::PAR \- File::ShareDir with PAR support .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use File::SharedDir::PAR \*(Aq:ALL\*(Aq; \& # exact same interface as the normal File::ShareDir: \& \& # 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 .PP You may choose to install the \f(CW\*(C`File::ShareDir::PAR\*(C'\fR functions into \f(CW\*(C`File::ShareDir\*(C'\fR so that they become available globally. In that case, you must do the following before anybody can import functions from \f(CW\*(C`File::ShareDir\*(C'\fR: .PP .Vb 1 \& use File::ShareDir::PAR \*(Aqglobal\*(Aq; .Ve .SH "WARNING" .IX Header "WARNING" This module contains \fIhighly experimental\fR code. If you want to load modules from \f(CW\*(C`.par\*(C'\fR files using \s-1PAR\s0 and then access their shared directory using \f(CW\*(C`File::ShareDir\*(C'\fR, you probably have no choice but to use it. But beware, here be dragons. .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`File::ShareDir::PAR\*(C'\fR provides the same functionality as File::ShareDir but tries hard to be compatible with \&\s-1PAR\s0 packaged applications. .PP The problem is, that the concept of having a distribution or module specific \fIshare\fR directory becomes a little hazy when you're loading everything from a single file. \&\s-1PAR\s0 uses an \f(CW@INC\fR hook to intercept any attempt to load a module. File::ShareDir uses the directory structure that is typically found in the directories that are listed in \f(CW@INC\fR for storing the shared data. In a \f(CW\*(C`PAR\*(C'\fR environment, this is not necessarily possible. .PP When you call one of the functions that this module provides, it will take care to search in any of the currently loaded \&\f(CW\*(C`.par\*(C'\fR files before scanning \f(CW@INC\fR. This is the same order of preference you get for loading modules when \s-1PAR\s0 is in effect. If the path or file you are asking for is found in one of the loaded \f(CW\*(C`.par\*(C'\fR files, that containing \&\f(CW\*(C`.par\*(C'\fR file is extracted and the path returned will point to the extracted copy on disk. .PP Depending on how you're using \s-1PAR,\s0 the files that are extracted this way are either cleaned up after program termination or cached for further executions. Either way, you're safe if you use the shared data as read-only data. If you write to it, your changes may be lost after the program ends. .PP For any further usage information, including the list of exportable functions, please refer to the documentation of File::ShareDir. .SH "SUPPORT" .IX Header "SUPPORT" Bugs should always be submitted via the \s-1CPAN\s0 bug tracker .PP .PP For other issues, contact the \s-1PAR\s0 mailing list: .SH "AUTHOR" .IX Header "AUTHOR" Steffen Mueller .PP The code was adapted from Adam Kennedy's work on \f(CW\*(C`File::ShareDir\*(C'\fR .SH "SEE ALSO" .IX Header "SEE ALSO" File::ShareDir, File::HomeDir, Module::Install, Module::Install::Share .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (c) 2008\-2010 Steffen Mueller This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The portions of code that were copied from \f(CW\*(C`File::ShareDir\*(C'\fR are: .PP Copyright (c) 2005, 2006 Adam Kennedy. 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.