Debian Codegraph @

README

raw
1 NAME
2 File::ShareDir::PAR - File::ShareDir with PAR support
3
4 SYNOPSIS
5 use File::SharedDir::PAR ':ALL';
6 # exact same interface as the normal File::ShareDir:
7
8 # Where are distribution-level shared data files kept
9 $dir = dist_dir('File-ShareDir');
10
11 # Where are module-level shared data files kept
12 $dir = module_dir('File::ShareDir');
13
14 # Find a specific file in our dist/module shared dir
15 $file = dist_file( 'File-ShareDir', 'file/name.txt');
16 $file = module_file('File::ShareDir', 'file/name.txt');
17
18 # Like module_file, but search up the inheritance tree
19 $file = class_file( 'Foo::Bar', 'file/name.txt' );
20
21 WARNING
22 This module contains *highly experimental* code. If you want to load
23 modules from ".par" files using PAR and then access their shared
24 directory using File::ShareDir, you probably have no choice but to use
25 it. But beware, here be dragons.
26
27 DESCRIPTION
28 "File::ShareDir::PAR" provides the same functionality as File::ShareDir
29 but tries hard to be compatible with PAR packaged applications.
30
31 The problem is, that the concept of having a distribution or module
32 specific *share* directory becomes a little hazy when you're loading
33 everything from a single file. PAR uses an @INC hook to intercept any
34 attempt to load a module. File::ShareDir uses the directory structure
35 that is typically found in the directories that are listed in @INC for
36 storing the shared data. In a "PAR" enviroment, this is not necessarily
37 possible.
38
39 When you call one of the functions that this module provides, it will
40 take care to search in any of the currently loaded ".par" files before
41 scanning @INC. This is the same order of preference you get for loading
42 modules when PAR is in effect. If the path or file you are asking for is
43 found in one of the loaded ".par" files, that containing ".par" file is
44 extracted and the path returned will point to the extracted copy on
45 disk.
46
47 Depending on how you're using PAR, the files that are extracted this way
48 are either cleaned up after program termination or cached for further
49 executions. Either way, you're safe if you use the shared data as
50 read-only data. If you write to it, your changes may be lost after the
51 program ends.
52
53 For any further usage information, including the list of exportable
54 functions, please refer to the documentation of File::ShareDir.
55
56 SUPPORT
57 Bugs should always be submitted via the CPAN bug tracker
58
59 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir-PAR>
60
61 For other issues, contact the PAR mailing list: <[email protected]>
62
63 AUTHOR
64 Steffen Mueller <[email protected]>
65
66 The code was adapted from Adam Kennedy's work on "File::ShareDir"
67
68 SEE ALSO
69 File::ShareDir, File::HomeDir, Module::Install, Module::Install::Share
70
71 COPYRIGHT AND LICENSE
72 Copyright (c) 2008 Steffen Mueller This program is free software; you
73 can redistribute it and/or modify it under the same terms as Perl
74 itself.
75
76 The portions of code that were copied from "File::ShareDir" are:
77
78 Copyright (c) 2005, 2006 Adam Kennedy. This program is free software;
79 you can redistribute it and/or modify it under the same terms as Perl
80 itself.
81
82 The full text of the license can be found in the LICENSE file included
83 with this module.
84