package Config::Find::Where;

use strict;
use warnings;

use Carp;
use Config::Find;
our @ISA=@Config::Find::ISA;

sub temp_dir {
    my $class = shift;
    my ($name, $more_name, $create, $dn, $scope)=
    $class->parse_opts(scope=> 'user', @_);

    $class->create_dir_if( (defined $dn
                ? $dn
                : $class->_temp_dir($name, $more_name, $scope)),

sub var_dir {
    my $class = shift;
    my ($name, $more_name, $create, $dn, $scope)=
    $class->parse_opts(scope => 'app', @_);

    $class->create_dir_if( (defined $dn
                ? $dn
                : $class->_var_dir($name, $more_name, $scope) ),

sub bin_dir {
    my $class = shift;
    my ($name, $more_name, $create, $dn, $scope)=
    $class->parse_opts(scope=> 'app', @_);

    $class->create_dir_if( (defined $dn
                ? $dn
                : $class->_bin_dir($name, $more_name, $scope) ),

sub lib_dir {
    my $class = shift;
    my ($name, $more_name, $create, $dn, $scope) =
        $class->parse_opts(scope => 'app', @_);

    $class->create_dir_if( (defined $dn
                            ? $dn
                            : $class->_lib_dir($name, $more_name, $scope) ),

sub application_dir {
    my $class=shift;
    my ($name, $more_name, $create, $dn, $scope)=

    $class->create_dir_if( (defined $dn
                ? $dn
                : $class->app_dir($name) ),

sub create_dir_if {
    my ($class, $dir, $create)=@_;
    # warn ("$class->create_dir($dir, $create)");
    if ($create) {

sub create_dir {
    my ($class, $dir)=@_;

sub create_parent_dir {
    my ($class, $dir)=@_;

sub script_full_path { shift->guess_full_script_name }

sub script_name { shift->guess_script_name }

sub script_dir { shift->guess_script_dir }

sub helper_path {
    my $class=shift;
    my $helper=shift;
    my $path=$class->bin_dir(@_);
    $class->look_for_helper($path, $helper);

sub parse_opts {
    my ($class, %opts)=@_;
    my ($name, $more_name, $create, $dn, $scope);

    if (defined $opts{name}) {
            or croak "invalid name '$opts{name}' specification";
    } else {

    if (defined $opts{scope}) {
        if ($opts{scope}=~/^u(ser)?$/i) {
        } elsif ($opts{scope}=~/^g(lobal)?$/i) {
        } elsif ($opts{scope}=~/^a(pp(lication)?)?$/i) {
        } elsif ($opts{scope}=~/^p(rocess)?$/i) {
        } else {
            croak "invalid option scope => '$opts{scope}'";
    } else {

    return ($name, $more_name, $create, $dn, $scope);



=encoding latin1

=head1 NAME

Config::Find::Where - Find locations in the native OS fashion


  use Config::Find::Where;

  my $temp_dir=Config::Find::Where->temp_dir( name => 'my_app',
                                              scope => 'process',
                                              create => 1 );

  my $path=Config::Find::Where->bin_dir( scope => 'app' );
  system $path."/app_helper.exe";


Config::Find searches for locations using OS dependant heuristics.


After releasing L<Config::Find> I found much of its code could be
reused to also find other interesting things like temporary
directories, the script location, etc.

This module adds a public API to all the hidden functionality.

=head2 OPTIONS

As in L<Config::Find>, all the methods in this package accept a common
set of options:

=over 4

=item name => C<name> or C<name/more/names>

specifies the primary application name used to generate the location
paths or to search for them.

=item scope => C<user>, C<global>, C<app> or C<process>


=item create => 1

creates any nonexistent directory in the path returned


=head2 METHODS

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

=over 4

=item $path=Config::Find::Where-E<gt>temp_dir(%opts)

returns a directory path inside a system temporary location. i.e.:

  Config::Find::Where->temp_dir( name =>'hello/world',
                                 scope => 'process',
                                 create => 1 )

returns something similar to


on unix like systems and


on some Windows ones ('jacks' is supposed to be the current user name
and '974' the process number).

The default scope for this method is C<user>.

=item $path=Config::Find::Where-E<gt>bin_dir(%opts)

returns a place to find/place binary files. The default scope for this
method is C<app>.



returns the path to the directory where binaries are located.

Note that this directory is not necessarily the same as the one
containing the running script. See documentation for C<script_dir>

=item $path=Config::Find::Where-E<gt>var_dir(%opts)

returns a place to find/place working files.

The default scope for this method is C<app>.

=item $path = Config::Find::Where-E<gt>lib_dir(%opts)

returns a place to find/place library files.

The default scope for this method is C<app>.

For instance:

  use lib => Config::Find::Where->lib_dir;

=item $path = Config::Find::Where-E<gt>application_dir(%opts)

returns the application root directory.

=item $name=Config::Find::Where-E<gt>script_name()

returns the name of the running script without any path information

=item $path=Config::Find::Where-E<gt>script_full_path()

returns the name of the script as the absolute full path to it.

=item $path=Config::Find::Where-E<gt>script_dir()

returns the name of the directory containing the current script

=item Config::Find::Where-E<gt>create_dir($dir)

creates directory C<$dir> and any needed parents

=item Config::Find::Where-E<gt>create_parent_dir($file)

recursively creates all the nonexistent parent directories for

=item Config::Find::Where-E<gt>helper_path($file, %opts)

searches for a script, based on the directories given in %opts, which are the
same as bin_dir() method.


=head1 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

=head1 SEE ALSO


=head1 AUTHOR

Salvador FandiE<ntilde>o GarcE<iacute>a, E<lt>sfandino@yahoo.comE<gt>


Barbie, E<lt><gt> (some bug fixes and documentation)


Copyright 2003-2015 by Salvador FandiE<ntilde>o GarcE<iacute>a (
Copyright 2015 by Barbie (

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