plucky (3) Config::Find.3pm.gz

Provided by: libconfig-find-perl_0.31-3_all bug

NAME
       Config::Find - Find configuration files in the native OS fashion


SYNOPSIS
         use Config::Find;

         my $filename=Config::Find->find;

         ...

         my $fn_foo=Config::Find->find( name => 'my_app/foo',
                                        mode => 'write',
                                        scope => 'user' );

         my $fn_bar=Config::Find->find( names => [qw(my_app/bar appbar)] );

         my $fh=Config::Find->open( name => 'foo',
                                    scope => 'global',
                                    mode => 'w' )

         my $fn=Config::Find->install( 'original/config/file.conf',
                                       name => 'foo' );

         my $fn=Config::Find->find( file => $opt_c,
                                    name => foo );


ABSTRACT
       Config::Find searches for configuration files using OS dependent heuristics.


DESCRIPTION
       Every OS has different rules for configuration files placement, this module allows one to easily find and
       create your app configuration files following those rules.

       Config::Find references configuration files by the application name or by the application name and the
       configuration file name when the app uses several application files, i.e "emacs", "profile",
       "apache/httpd", "apache/ssl".

       By default the $0 value is used to generate the configuration file name. To define it explicitly the
       keywords "name" or "names" have to be used:

       name => "name" or "app/file"
           picks the first configuration file matching that name.

       names => [qw(foo bar foo/bar)]
           picks the first configuration file matching any of the names passed.

       Alternatively, the exact position for the file can be specified with the "file" keyword:

       file => "/config/file/name.conf"
           explicit position of the configuration file.

           If undef is passed this entry is ignored and the search for the configuration file continues with the
           appropriate OS rules. This allows for:

             use Config::Find;
             use Getopt::Std;

             our $opt_c;
             getopts('c:');

             my $fn=Config::Find->find(file => $opt_c)

       Methods in this package also accept the optional arguments "scope" and "mode":

       scope => "user" or "global"
           Configuration files can be private to the application user or global to the OS, i.e. in unix there is
           the global "/etc/profile" and the user "~/.profile".

       mode => "read" or "write"
           In "read" mode already existent file names are returned, in "write" mode the file names point to
           where the configuration file has to be stored.

   METHODS
       All the methods in this package are class methods (you don't need an object to call them).

       $fn=Config::Find->find(%opts)
           returns the name of the configuration file.

       $fh=Config::Find->open(%opts)
           returns a open file handle for the configuration file. In write mode, the file and any nonexistent
           parent directories are created.

       $fn=Config::Find->install($original, %opts)
           copies a configuration file to a convenient place.


BUGS
       Some Win32 operating systems are not completely implemented and default to inferior modes, but hey, this
       is a work in progress!!!

       Contributions, bug reports, feedback and any kind of comments are welcome.


SEE ALSO
       Config::Find::Unix, Config::Find::Win32 for descriptions of the heuristics used to find the configuration
       files.

       Config::Find::Any for information about adding support for a new OS.

       Config::Auto give me the idea for this module.


AUTHOR
       Salvador Fandiño García, <sfandino@yahoo.com>


CONTRIBUTORS
       Barbie, <barbie@missbarbell.co.uk> (some bug fixes and documentation)


       Copyright 2003-2015 by Salvador Fandiño García (sfandino@yahoo.com) Copyright 2015 by Barbie
       (barbie@missbarbell.co.uk)

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl
       itself.