.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Config::Find::Where 3pm"
.TH Config::Find::Where 3pm "2022-12-07" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Config::Find::Where \- Find locations in the native OS fashion
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Config::Find::Where;
\&
\&  my $temp_dir=Config::Find::Where\->temp_dir( name => \*(Aqmy_app\*(Aq,
\&                                              scope => \*(Aqprocess\*(Aq,
\&                                              create => 1 );
\&
\&  my $path=Config::Find::Where\->bin_dir( scope => \*(Aqapp\*(Aq );
\&  system $path."/app_helper.exe";
.Ve
.SH "ABSTRACT"
.IX Header "ABSTRACT"
Config::Find searches for locations using \s-1OS\s0 dependent heuristics.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
After releasing Config::Find I found much of its code could be
reused to also find other interesting things like temporary
directories, the script location, etc.
.PP
This module adds a public \s-1API\s0 to all the hidden functionality.
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
As in Config::Find, all the methods in this package accept a common
set of options:
.ie n .IP "name => ""name"" or ""name/more/names""" 4
.el .IP "name => \f(CWname\fR or \f(CWname/more/names\fR" 4
.IX Item "name => name or name/more/names"
specifies the primary application name used to generate the location
paths or to search for them.
.ie n .IP "scope => ""user"", ""global"", ""app"" or ""process""" 4
.el .IP "scope => \f(CWuser\fR, \f(CWglobal\fR, \f(CWapp\fR or \f(CWprocess\fR" 4
.IX Item "scope => user, global, app or process"
\&\-
.IP "create => 1" 4
.IX Item "create => 1"
creates any nonexistent directory in the path returned
.SS "\s-1METHODS\s0"
.IX Subsection "METHODS"
All the methods in this package are class methods (you don't need an
object to call them).
.ie n .IP "$path=Config::Find::Where\->temp_dir(%opts)" 4
.el .IP "\f(CW$path\fR=Config::Find::Where\->temp_dir(%opts)" 4
.IX Item "$path=Config::Find::Where->temp_dir(%opts)"
returns a directory path inside a system temporary location. i.e.:
.Sp
.Vb 3
\&  Config::Find::Where\->temp_dir( name =>\*(Aqhello/world\*(Aq,
\&                                 scope => \*(Aqprocess\*(Aq,
\&                                 create => 1 )
.Ve
.Sp
returns something similar to
.Sp
.Vb 1
\&  \*(Aq/tmp/jacks/hello/974/world/\*(Aq
.Ve
.Sp
on unix like systems and
.Sp
.Vb 1
\&  \*(AqC:\eWindows\eTemp\ejacks\ehello\e974\eworld\*(Aq
.Ve
.Sp
on some Windows ones ('jacks' is supposed to be the current user name
and '974' the process number).
.Sp
The default scope for this method is \f(CW\*(C`user\*(C'\fR.
.ie n .IP "$path=Config::Find::Where\->bin_dir(%opts)" 4
.el .IP "\f(CW$path\fR=Config::Find::Where\->bin_dir(%opts)" 4
.IX Item "$path=Config::Find::Where->bin_dir(%opts)"
returns a place to find/place binary files. The default scope for this
method is \f(CW\*(C`app\*(C'\fR.
.Sp
i.e.
.Sp
.Vb 1
\& Config::Find::Where\->bin_dir()
.Ve
.Sp
returns the path to the directory where binaries are located.
.Sp
Note that this directory is not necessarily the same as the one
containing the running script. See documentation for \f(CW\*(C`script_dir\*(C'\fR
below.
.ie n .IP "$path=Config::Find::Where\->var_dir(%opts)" 4
.el .IP "\f(CW$path\fR=Config::Find::Where\->var_dir(%opts)" 4
.IX Item "$path=Config::Find::Where->var_dir(%opts)"
returns a place to find/place working files.
.Sp
The default scope for this method is \f(CW\*(C`app\*(C'\fR.
.ie n .IP "$path = Config::Find::Where\->lib_dir(%opts)" 4
.el .IP "\f(CW$path\fR = Config::Find::Where\->lib_dir(%opts)" 4
.IX Item "$path = Config::Find::Where->lib_dir(%opts)"
returns a place to find/place library files.
.Sp
The default scope for this method is \f(CW\*(C`app\*(C'\fR.
.Sp
For instance:
.Sp
.Vb 1
\&  use lib => Config::Find::Where\->lib_dir;
.Ve
.ie n .IP "$path = Config::Find::Where\->application_dir(%opts)" 4
.el .IP "\f(CW$path\fR = Config::Find::Where\->application_dir(%opts)" 4
.IX Item "$path = Config::Find::Where->application_dir(%opts)"
returns the application root directory.
.ie n .IP "$name=Config::Find::Where\->\fBscript_name()\fR" 4
.el .IP "\f(CW$name\fR=Config::Find::Where\->\fBscript_name()\fR" 4
.IX Item "$name=Config::Find::Where->script_name()"
returns the name of the running script without any path information
.ie n .IP "$path=Config::Find::Where\->\fBscript_full_path()\fR" 4
.el .IP "\f(CW$path\fR=Config::Find::Where\->\fBscript_full_path()\fR" 4
.IX Item "$path=Config::Find::Where->script_full_path()"
returns the name of the script as the absolute full path to it.
.ie n .IP "$path=Config::Find::Where\->\fBscript_dir()\fR" 4
.el .IP "\f(CW$path\fR=Config::Find::Where\->\fBscript_dir()\fR" 4
.IX Item "$path=Config::Find::Where->script_dir()"
returns the name of the directory containing the current script
.IP "Config::Find::Where\->create_dir($dir)" 4
.IX Item "Config::Find::Where->create_dir($dir)"
creates directory \f(CW$dir\fR and any needed parents
.IP "Config::Find::Where\->create_parent_dir($file)" 4
.IX Item "Config::Find::Where->create_parent_dir($file)"
recursively creates all the nonexistent parent directories for
\&\f(CW$file\fR.
.ie n .IP "Config::Find::Where\->helper_path($file, %opts)" 4
.el .IP "Config::Find::Where\->helper_path($file, \f(CW%opts\fR)" 4
.IX Item "Config::Find::Where->helper_path($file, %opts)"
searches for a script, based on the directories given in \f(CW%opts\fR, which are the
same as \fBbin_dir()\fR method.
.SH "BUGS"
.IX Header "BUGS"
Some Win32 operating systems are not completely implemented and
default to inferior modes, but hey, this is a work in progress!!!
.PP
Contributions, bug reports, feedback and any kind of comments are
welcome.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Config::Find
.SH "AUTHOR"
.IX Header "AUTHOR"
Salvador Fandiño García, <sfandino@yahoo.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Barbie, <barbie@missbarbell.co.uk> (some bug fixes and documentation)
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003\-2015 by Salvador Fandiño García (sfandino@yahoo.com)
Copyright 2015 by Barbie (barbie@missbarbell.co.uk)
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.