File::ConfigDir - Get directories of configuration files
use File::ConfigDir ':ALL';
my @cfgdirs = config_dirs();
my @appcfgdirs = config_dirs('app');
# install support
my $site_cfg_dir = (site_cfg_dir())[0];
my $vendor_cfg_dir = (site_cfg_dir()))[0];
This module is a helper for installing, reading and finding configuration file locations. It's intended to work in every supported Perl5 environment and will always try to Do The Right Thing(TM).
File::ConfigDir is a module to help out when perl modules (especially
applications) need to read and store configuration files from more than
one location. Writing user configuration is easy thanks to
File::HomeDir, but what when the system administrator needs to place
some global configuration or there will be system related configuration
(in /etc on UNIX(TM) or $ENV{windir} on Windows(TM)) and some
network configuration in NFS mapped /etc/p5-app or
$ENV{ALLUSERSPROFILE} . "\\Application Data\\p5-app", respectively.
File::ConfigDir has no "do what I mean" mode - it's entirely up to the
user to pick the right directory for each particular application.
Every function listed below can be exported, either by name or using the
tag :ALL.
All functions can take one optional argument as application specific configuration directory. If given, it will be embedded at the right (TM) place of the resulting path.
Returns the configuration directory where configuration files of the
operating system resides. For Unices this is /etc, for MSWin32 it's
the value of the environment variable %windir%.
Alias for desktop_cfg_dir - deprecated.
Alias for desktop_cfg_dir
Returns the configuration directory where configuration files of the
desktop applications resides. For Unices this is /etc/xdg, for MSWin32
it's the value of the environment variable %ALLUSERSPROFILE%
concatenated with the basename of the environment variable %APPDATA%.
Returns the etc directory below $Config{prefix}.
Returns the etc directory below $Config{sitelib_stem} or the common
base directory of $Config{sitelib} and $Config{sitebin}.
Returns the etc directory below $Config{vendorlib_stem} or the common
base directory of $Config{vendorlib} and $Config{vendorbin}.
Returns the configuration file for stand-alone installed applications. In
Unix speak, installing JRE to /usr/local/jre-<version> means there is
a /usr/local/jre-<version>/bin/java and going from it's directory
name one above and into etc there is the singleapp_cfg_dir. For a
Perl module it means, we're assuming that $FindBin::Bin is installed as
a stand-alone package somewhere, e.g. into /usr/pkg - as recommended for
pkgsrc.
Returns the configuration file for vendor installed applications. In Unix
speak, installing bacula to /opt/${vendor} means there is
a /opt/${vendor}/bin/bacula and going from it's directory
name one above and into etc there is the vendorapp_cfg_dir. For a
Perl module it means, we're assuming that $FindBin::Bin is installed as
a stand-alone package somewhere, e.g. into /usr/pkg - as recommended for
pkgsrc.
Returns the configuration directory for distribution independent, 3rd
party applications. While this directory doesn't exists for MSWin32,
there will be only the path /usr/local/etc for Unices.
Extracts the INSTALL_BASE from $ENV{PERL_MM_OPT} and returns the
etc directory below it.
Returns the path for the etc directory below the current working directory.
Returns the users home folder using File::HomeDir. Without File::HomeDir, nothing is returned.
Returns the user configuration directory for desktop applications.
If $ENV{XDG_CONFIG_HOME} is not set, for MSWin32 the value
of $ENV{APPDATA} is return and on Unices the .config directory
in the users home folder. Without File::HomeDir, on Unices the returned
list might be empty.
@cfgdirs = config_dirs();
@cfgdirs = config_dirs( 'appname' );
Tries to get all available configuration directories as described above. Returns those who exists and are readable.
my $dir_src = sub { return _better_config_dir(@_); }
File::ConfigDir::_plug_dir_source($dir_src);
my $pure_src = sub { return _better_config_plain_dir(@_); }
File::ConfigDir::_plug_dir_source($pure_src, 1); # see 2nd arg is true
Registers more sources to ask for suitable directories to check or search for config files. Each "config_dirs" will traverse them in subsequent invocations, too.
Returns the number of directory sources in case of success. Returns nothing
when $dir_src is not a code ref.
Jens Rehsack, <rehsack at cpan.org>
Please report any bugs or feature requests to
bug-File-ConfigDir at rt.cpan.org, or through the web interface at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ConfigDir.
I will be notified, and then you'll automatically be notified of progress
on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc File::ConfigDir
You can also look for information at:
-
RT: CPAN's request tracker
-
AnnoCPAN: Annotated CPAN documentation
-
CPAN Ratings
-
Search CPAN
Thanks are sent out to Lars Dieckow (daxim) for his suggestion to add
support for the Base Directory Specification of the Free Desktop Group.
Matthew S. Trout (mst) earns the credit to suggest singleapp_cfg_dir
and remind about /usr/local/etc.
Copyright 2010-2018 Jens Rehsack.
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
File::HomeDir, File::ShareDir, File::BaseDir (Unices only)