File::ConfigDir(3pm)

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

NAME

6       File::ConfigDir - Get directories of configuration files
7

SYNOPSIS

9           use File::ConfigDir ':ALL';
10
11           my @cfgdirs = config_dirs();
12           my @appcfgdirs = config_dirs('app');
13
14           # install support
15           my $site_cfg_dir = (site_cfg_dir())[0];
16           my $vendor_cfg_dir = (site_cfg_dir()))[0];
17

DESCRIPTION

19       This module is a helper for installing, reading and finding
20       configuration file locations. It's intended to work in every supported
21       Perl5 environment and will always try to Do The Right Thing(TM).
22
23       "File::ConfigDir" is a module to help out when perl modules (especially
24       applications) need to read and store configuration files from more than
25       one location. Writing user configuration is easy thanks to
26       File::HomeDir, but what when the system administrator needs to place
27       some global configuration or there will be system related configuration
28       (in "/etc" on UNIX(TM) or $ENV{windir} on Windows(TM)) and some network
29       configuration in NFS mapped "/etc/p5-app" or "$ENV{ALLUSERSPROFILE} .
30       "\\Application Data\\p5-app"", respectively.
31
32       "File::ConfigDir" has no "do what I mean" mode - it's entirely up to
33       the user to pick the right directory for each particular application.
34

EXPORT

36       Every function listed below can be exported, either by name or using
37       the tag ":ALL".
38

SUBROUTINES/METHODS

40       All functions can take one optional argument as application specific
41       configuration directory. If given, it will be embedded at the right
42       (TM) place of the resulting path.
43
44   system_cfg_dir
45       Returns the configuration directory where configuration files of the
46       operating system resides. For Unices this is "/etc", for MSWin32 it's
47       the value of the environment variable "%windir%".
48
49   machine_cfg_dir
50       Alias for desktop_cfg_dir - deprecated.
51
52   xdg_config_dirs
53       Alias for desktop_cfg_dir
54
55   desktop_cfg_dir
56       Returns the configuration directory where configuration files of the
57       desktop applications resides. For Unices this is "/etc/xdg", for
58       MSWin32 it's the value of the environment variable "%ALLUSERSPROFILE%"
59       concatenated with the basename of the environment variable "%APPDATA%".
60
61   core_cfg_dir
62       Returns the "etc" directory below $Config{prefix}.
63
64   site_cfg_dir
65       Returns the "etc" directory below $Config{sitelib_stem} or the common
66       base directory of $Config{sitelib} and $Config{sitebin}.
67
68   vendor_cfg_dir
69       Returns the "etc" directory below $Config{vendorlib_stem} or the common
70       base directory of $Config{vendorlib} and $Config{vendorbin}.
71
72   singleapp_cfg_dir
73       Returns the configuration file for stand-alone installed applications.
74       In Unix speak, installing JRE to "/usr/local/jre-<version>" means there
75       is a "/usr/local/jre-<version>/bin/java" and going from it's directory
76       name one above and into "etc" there is the singleapp_cfg_dir. For a
77       Perl module it means, we're assuming that $FindBin::Bin is installed as
78       a stand-alone package somewhere, e.g. into "/usr/pkg" - as recommended
79       for pkgsrc <http://www.pkgsrc.org/>.
80
81   vendorapp_cfg_dir
82       Returns the configuration file for vendor installed applications. In
83       Unix speak, installing bacula to "/opt/${vendor}" means there is a
84       "/opt/${vendor}/bin/bacula" and going from it's directory name one
85       above and into "etc" there is the vendorapp_cfg_dir. For a Perl module
86       it means, we're assuming that $FindBin::Bin is installed as a stand-
87       alone package somewhere, e.g. into "/usr/pkg" - as recommended for
88       pkgsrc <http://www.pkgsrc.org/>.
89
90   local_cfg_dir
91       Returns the configuration directory for distribution independent, 3rd
92       party applications. While this directory doesn't exists for MSWin32,
93       there will be only the path "/usr/local/etc" for Unices.
94
95   locallib_cfg_dir
96       Extracts the "INSTALL_BASE" from $ENV{PERL_MM_OPT} and returns the
97       "etc" directory below it.
98
99   here_cfg_dir
100       Returns the path for the "etc" directory below the current working
101       directory.
102
103   user_cfg_dir
104       Returns the users home folder using File::HomeDir. Without
105       File::HomeDir, nothing is returned.
106
107   xdg_config_home
108       Returns the user configuration directory for desktop applications.  If
109       $ENV{XDG_CONFIG_HOME} is not set, for MSWin32 the value of
110       $ENV{APPDATA} is return and on Unices the ".config" directory in the
111       users home folder. Without File::HomeDir, on Unices the returned list
112       might be empty.
113
114   config_dirs
115           @cfgdirs = config_dirs();
116           @cfgdirs = config_dirs( 'appname' );
117
118       Tries to get all available configuration directories as described
119       above.  Returns those who exists and are readable.
120
121   _plug_dir_source
122           my $dir_src = sub { return _better_config_dir(@_); }
123           File::ConfigDir::_plug_dir_source($dir_src);
124
125           my $pure_src = sub { return _better_config_plain_dir(@_); }
126           File::ConfigDir::_plug_dir_source($pure_src, 1); # see 2nd arg is true
127
128       Registers more sources to ask for suitable directories to check or
129       search for config files. Each "config_dirs" will traverse them in
130       subsequent invocations, too.
131
132       Returns the number of directory sources in case of success. Returns
133       nothing when $dir_src is not a code ref.
134

AUTHOR

136       Jens Rehsack, "<rehsack at cpan.org>"
137

BUGS

139       Please report any bugs or feature requests to "bug-File-ConfigDir at
140       rt.cpan.org", or through the web interface at
141       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ConfigDir>.  I
142       will be notified, and then you'll automatically be notified of progress
143       on your bug as I make changes.
144

SUPPORT

146       You can find documentation for this module with the perldoc command.
147
148           perldoc File::ConfigDir
149
150       You can also look for information at:
151
152       •   RT: CPAN's request tracker
153
154           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ConfigDir>
155
156       •   AnnoCPAN: Annotated CPAN documentation
157
158           <http://annocpan.org/dist/File-ConfigDir>
159
160       •   CPAN Ratings
161
162           <http://cpanratings.perl.org/d/File-ConfigDir>
163
164       •   Search CPAN
165
166           <http://search.cpan.org/dist/File-ConfigDir/>
167

ACKNOWLEDGEMENTS

169       Thanks are sent out to Lars Dieckow (daxim) for his suggestion to add
170       support for the Base Directory Specification of the Free Desktop Group.
171       Matthew S. Trout (mst) earns the credit to suggest "singleapp_cfg_dir"
172       and remind about "/usr/local/etc".
173

LICENSE AND COPYRIGHT

175       Copyright 2010-2018 Jens Rehsack.
176
177       This program is free software; you can redistribute it and/or modify it
178       under the terms of either: the GNU General Public License as published
179       by the Free Software Foundation; or the Artistic License.
180
181       See http://dev.perl.org/licenses/ for more information.
182