Jens Rehsack > File-ConfigDir-0.004 > File::ConfigDir

Download:
File-ConfigDir-0.004.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Module Version: 0.004   Source   Latest Release: File-ConfigDir-0.015

NAME ^

File::ConfigDir - Get directories of configuration files

SYNOPSIS ^

    use File::ConfigDir ':ALL';

    my @cfgdirs = config_dirs();
    my @appcfgdirs = config_dirs('app');

    # install support
    my $site_cfg_dir = site_cfg_dir();
    my $vendor_cfg_dir = site_cfg_dir();

DESCRIPTION ^

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.

EXPORT ^

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

SUBROUTINES/METHODS ^

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.

system_cfg_dir

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%.

machine_cfg_dir

Alias for desktop_cfg_dir - depreciated.

xdg_config_dirs

Alias for desktop_cfg_dir

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%.

core_cfg_dir

Returns the etc directory below $Config{prefix}.

site_cfg_dir

Returns the etc directory below $Config{sitelib_stem} or the common base directory of $Config{sitelib} and $Config{sitebin}.

vendor_cfg_dir

Returns the etc directory below $Config{vendorlib_stem} or the common base directory of $Config{vendorlib} and $Config{vendorbin}.

singleapp_cfg_dir

local_cfg_dir

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.

locallib_cfg_dir

Extracts the INSTALL_BASE from $ENV{PERL_MM_OPT} and returns the etc directory below it.

here_cfg_dir

Returns the path for the etc directory below the current working directory.

user_cfg_dir

Returns the users home folder using File::HomeDir. Without File::HomeDir, nothing is returned.

xdg_config_home

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.

config_dirs

    @cfgdirs = config_dirs();
    @cfgdirs = config_dirs( 'appname' );

Tries to get all available configuration directories as described above. Returns those who exists and are readable.

AUTHOR ^

Jens Rehsack, <rehsack at cpan.org>

BUGS ^

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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc File::ConfigDir

You can also look for information at:

ACKNOWLEDGEMENTS ^

Thanks are sent out to Lars Dieckow for his suggestion to add support for the Base Directory Specification of the Free Desktop Group. Matthew S. Trout earns the credit to suggest singleapp_cfg_dir and remind about /usr/local/etc.

LICENSE AND COPYRIGHT ^

Copyright 2010 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.

SEE ALSO ^

File::HomeDir, File::ShareDir, File::BaseDir (Unices only)

syntax highlighting: