.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "App::Info::Util 3pm"
.TH App::Info::Util 3pm "2022-12-06" "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"
App::Info::Util \- Utility class for App::Info subclasses
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use App::Info::Util;
\&
\&  my $util = App::Info::Util\->new;
\&
\&  # Subclasses File::Spec.
\&  my @paths = $util\->paths;
\&
\&  # First directory that exists in a list.
\&  my $dir = $util\->first_dir(@paths);
\&
\&  # First directory that exists in a path.
\&  $dir = $util\->first_path($ENV{PATH});
\&
\&  # First file that exists in a list.
\&  my $file = $util\->first_file(\*(Aqthis.txt\*(Aq, \*(Aq/that.txt\*(Aq, \*(AqC:\e\efoo.txt\*(Aq);
\&
\&  # First file found among file base names and directories.
\&  my $files = [\*(Aqthis.txt\*(Aq, \*(Aqthat.txt\*(Aq];
\&  $file = $util\->first_cat_file($files, @paths);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class subclasses File::Spec and adds its own methods in
order to offer utility methods to App::Info classes. Although
intended to be used by App::Info subclasses, in truth App::Info::Util's
utility may be considered more general, so feel free to use it elsewhere.
.PP
The methods added in addition to the usual File::Spec suspects are designed to
facilitate locating files and directories on the file system, as well as
searching those files. The assumption is that, in order to provide useful
meta data about a given software package, an App::Info subclass must find
relevant files and directories and parse them with regular expressions. This
class offers methods that simplify those tasks.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 1
\&  my $util = App::Info::Util\->new;
.Ve
.PP
This is a very simple constructor that merely returns an App::Info::Util
object. Since, like its File::Spec super class, App::Info::Util manages no
internal data itself, all methods may be used as class methods, if one prefers
to. The constructor here is provided merely as a convenience.
.SH "OBJECT METHODS"
.IX Header "OBJECT METHODS"
In addition to all of the methods offered by its super class,
File::Spec, App::Info::Util offers the following methods.
.SS "first_dir"
.IX Subsection "first_dir"
.Vb 2
\&  my @paths = $util\->paths;
\&  my $dir = $util\->first_dir(@dirs);
.Ve
.PP
Returns the first file system directory in \f(CW@paths\fR that exists on the local
file system. Only the first item in \f(CW@paths\fR that exists as a directory will be
returned; any other paths leading to non-directories will be ignored.
.SS "first_path"
.IX Subsection "first_path"
.Vb 2
\&  my $path = $ENV{PATH};
\&  $dir = $util\->first_path($path);
.Ve
.PP
Takes the \f(CW$path\fR string and splits it into a list of directory paths, based on
the path delimiter on the local file system. Then calls \f(CW\*(C`first_dir()\*(C'\fR to
return the first directory in the path list that exists on the local file
system. The path delimiter is specified for the following file systems:
.IP "\(bu" 4
MacOS: \*(L",\*(R"
.IP "\(bu" 4
MSWin32: \*(L";\*(R"
.IP "\(bu" 4
os2: \*(L";\*(R"
.IP "\(bu" 4
\&\s-1VMS:\s0 undef
.Sp
This method always returns undef on \s-1VMS.\s0 Patches welcome.
.IP "\(bu" 4
epoc: undef
.Sp
This method always returns undef on epoch. Patches welcome.
.IP "\(bu" 4
Unix: \*(L":\*(R"
.Sp
All other operating systems are assumed to be Unix-based.
.SS "first_file"
.IX Subsection "first_file"
.Vb 1
\&  my $file = $util\->first_file(@filelist);
.Ve
.PP
Examines each of the files in \f(CW@filelist\fR and returns the first one that exists
on the file system. The file must be a regular file \*(-- directories will be
ignored.
.SS "first_exe"
.IX Subsection "first_exe"
.Vb 1
\&  my $exe = $util\->first_exe(@exelist);
.Ve
.PP
Examines each of the files in \f(CW@exelist\fR and returns the first one that exists
on the file system as an executable file. Directories will be ignored.
.SS "first_cat_path"
.IX Subsection "first_cat_path"
.Vb 2
\&  my $file = $util\->first_cat_path(\*(Aqick.txt\*(Aq, @paths);
\&  $file = $util\->first_cat_path([\*(Aqthis.txt\*(Aq, \*(Aqthat.txt\*(Aq], @paths);
.Ve
.PP
The first argument to this method may be either a file or directory base name
(that is, a file or directory name without a full path specification), or a
reference to an array of file or directory base names. The remaining arguments
constitute a list of directory paths. \f(CW\*(C`first_cat_path()\*(C'\fR processes each of
these directory paths, concatenates (by the method native to the local
operating system) each of the file or directory base names, and returns the
first one that exists on the file system.
.PP
For example, let us say that we were looking for a file called either \fIhttpd\fR
or \fIapache\fR, and it could be in any of the following paths:
\&\fI/usr/local/bin\fR, \fI/usr/bin/\fR, \fI/bin\fR. The method call looks like this:
.PP
.Vb 2
\&  my $httpd = $util\->first_cat_path([\*(Aqhttpd\*(Aq, \*(Aqapache\*(Aq], \*(Aq/usr/local/bin\*(Aq,
\&                                    \*(Aq/usr/bin/\*(Aq, \*(Aq/bin\*(Aq);
.Ve
.PP
If the \s-1OS\s0 is a Unix variant, \f(CW\*(C`first_cat_path()\*(C'\fR will then look for the first
file that exists in this order:
.IP "/usr/local/bin/httpd" 4
.IX Item "/usr/local/bin/httpd"
.PD 0
.IP "/usr/local/bin/apache" 4
.IX Item "/usr/local/bin/apache"
.IP "/usr/bin/httpd" 4
.IX Item "/usr/bin/httpd"
.IP "/usr/bin/apache" 4
.IX Item "/usr/bin/apache"
.IP "/bin/httpd" 4
.IX Item "/bin/httpd"
.IP "/bin/apache" 4
.IX Item "/bin/apache"
.PD
.PP
The first of these complete paths to be found will be returned. If none are
found, then undef will be returned.
.SS "first_cat_dir"
.IX Subsection "first_cat_dir"
.Vb 2
\&  my $dir = $util\->first_cat_dir(\*(Aqick.txt\*(Aq, @paths);
\&  $dir = $util\->first_cat_dir([\*(Aqthis.txt\*(Aq, \*(Aqthat.txt\*(Aq], @paths);
.Ve
.PP
Functionally identical to \f(CW\*(C`first_cat_path()\*(C'\fR, except that it returns the
directory path in which the first file was found, rather than the full
concatenated path. Thus, in the above example, if the file found was
\&\fI/usr/bin/httpd\fR, while \f(CW\*(C`first_cat_path()\*(C'\fR would return that value,
\&\f(CW\*(C`first_cat_dir()\*(C'\fR would return \fI/usr/bin\fR instead.
.SS "first_cat_exe"
.IX Subsection "first_cat_exe"
.Vb 2
\&  my $exe = $util\->first_cat_exe(\*(Aqick.exe\*(Aq, @paths);
\&  $exe = $util\->first_cat_exe([\*(Aqthis.exe\*(Aq, \*(Aqthat.exe\*(Aq], @paths);
.Ve
.PP
Functionally identical to \f(CW\*(C`first_cat_path()\*(C'\fR, except that it returns the full
path to the first executable file found, rather than simply the first file
found.
.SS "search_file"
.IX Subsection "search_file"
.Vb 3
\&  my $file = \*(Aqfoo.txt\*(Aq;
\&  my $regex = qr/(text\es+to\es+find)/;
\&  my $value = $util\->search_file($file, $regex);
.Ve
.PP
Opens \f(CW$file\fR and executes the \f(CW$regex\fR regular expression against each line
in the file. Once the line matches and one or more values is returned by the
match, the file is closed and the value or values returned.
.PP
For example, say \fIfoo.txt\fR contains the line \*(L"Version 6.5, patch level 8\*(R",
and you need to grab each of the three version parts. All three parts can
be grabbed like this:
.PP
.Vb 2
\&  my $regex = qr/Version\es+(\ed+)\e.(\ed+),[^\ed]*(\ed+)/;
\&  my @nums = $util\->search_file($file, $regex);
.Ve
.PP
Now \f(CW@nums\fR will contain the values \f(CW\*(C`(6, 5, 8)\*(C'\fR. Note that in a scalar
context, the above search would yield an array reference:
.PP
.Vb 2
\&  my $regex = qr/Version\es+(\ed+)\e.(\ed+),[^\ed]*(\ed+)/;
\&  my $nums = $util\->search_file($file, $regex);
.Ve
.PP
So now \f(CW$nums\fR contains \f(CW\*(C`[6, 5, 8]\*(C'\fR. The same does not hold true if the
match returns only one value, however. Say \fIfoo.txt\fR contains the line
\&\*(L"king of the who?\*(R", and you wish to know who the king is king of. Either
of the following two calls would get you the data you need:
.PP
.Vb 2
\&  my $minions = $util\->search_file($file, qr/King\es+of\es+(.*)/);
\&  my @minions = $util\->search_file($file, qr/King\es+of\es+(.*)/);
.Ve
.PP
In the first case, because the regular expression contains only one set of
parentheses, \f(CW\*(C`search_file()\*(C'\fR will simply return that value: \f(CW$minions\fR
contains the string \*(L"the who?\*(R". In the latter case, \f(CW@minions\fR of course
contains a single element: \f(CW\*(C`("the who?")\*(C'\fR.
.PP
Note that a regular expression without parentheses \*(-- that is, one that
doesn't grab values and put them into \f(CW$1\fR, \f(CW$2\fR, etc., will never successfully
match a line in this method. You must include something to parenthetically
match. If you just want to know the value of what was matched, parenthesize
the whole thing and if the value returns, you have a match. Also, if you need
to match patterns across lines, try using multiple regular expressions with
\&\f(CW\*(C`multi_search_file()\*(C'\fR, instead.
.SS "files_in_dir"
.IX Subsection "files_in_dir"
.Vb 4
\&  my @files = $util\->files_in_dir($dir);
\&     @files = $util\->files_in_dir($dir, $filter);
\&  my $files = $util\->files_in_dir($dir);
\&     $files = $util\->files_in_dir($dir, $filter);
.Ve
.PP
Returns an list or array reference of all of the files and directories in the
file system directory \f(CW$dir\fR. An optional second argument is a code reference
that filters the files. The code reference should examine the \f(CW$_\fR for a file
name and return true if it's a file that you're interested and false if it's
not.
.SS "multi_search_file"
.IX Subsection "multi_search_file"
.Vb 2
\&  my @regexen = (qr/(one)/, qr/(two)\es+(three)/);
\&  my @matches = $util\->multi_search_file($file, @regexen);
.Ve
.PP
Like \f(CW\*(C`search_file()\*(C'\fR, this method opens \f(CW$file\fR and parses it for regular
expression matches. This method, however, can take a list of regular
expressions to look for, and will return the values found for all of them.
Regular expressions that match and return multiple values will be returned as
array references, while those that match and return a single value will return
just that single value.
.PP
For example, say you are parsing a file with lines like the following:
.PP
.Vb 3
\&  #define XML_MAJOR_VERSION 1
\&  #define XML_MINOR_VERSION 95
\&  #define XML_MICRO_VERSION 2
.Ve
.PP
You need to get each of these numbers, but calling \f(CW\*(C`search_file()\*(C'\fR for each
of them would be wasteful, as each call to \f(CW\*(C`search_file()\*(C'\fR opens the file and
parses it. With \f(CW\*(C`multi_search_file()\*(C'\fR, on the other hand, the file will be
opened only once, and, once all of the regular expressions have returned
matches, the file will be closed and the matches returned.
.PP
Thus the above values can be collected like this:
.PP
.Vb 3
\&  my @regexen = ( qr/XML_MAJOR_VERSION\es+(\ed+)$/,
\&                  qr/XML_MINOR_VERSION\es+(\ed+)$/,
\&                  qr/XML_MICRO_VERSION\es+(\ed+)$/ );
\&
\&  my @nums = $file\->multi_search_file($file, @regexen);
.Ve
.PP
The result will be that \f(CW@nums\fR contains \f(CW\*(C`(1, 95, 2)\*(C'\fR. Note that
\&\f(CW\*(C`multi_file_search()\*(C'\fR tries to do the right thing by only parsing the file
until all of the regular expressions have been matched. Thus, a large file
with the values you need near the top can be parsed very quickly.
.PP
As with \f(CW\*(C`search_file()\*(C'\fR, \f(CW\*(C`multi_search_file()\*(C'\fR can take regular expressions
that match multiple values. These will be returned as array references. For
example, say the file you're parsing has files like this:
.PP
.Vb 2
\&  FooApp Version 4
\&  Subversion 2, Microversion 6
.Ve
.PP
To get all of the version numbers, you can either use three regular
expressions, as in the previous example:
.PP
.Vb 3
\&  my @regexen = ( qr/FooApp\es+Version\es+(\ed+)$/,
\&                  qr/Subversion\es+(\ed+),/,
\&                  qr/Microversion\es+(\ed$)$/ );
\&
\&  my @nums = $file\->multi_search_file($file, @regexen);
.Ve
.PP
In which case \f(CW@nums\fR will contain \f(CW\*(C`(4, 2, 6)\*(C'\fR. Or, you can use just two
regular expressions:
.PP
.Vb 2
\&  my @regexen = ( qr/FooApp\es+Version\es+(\ed+)$/,
\&                  qr/Subversion\es+(\ed+),\es+Microversion\es+(\ed$)$/ );
\&
\&  my @nums = $file\->multi_search_file($file, @regexen);
.Ve
.PP
In which case \f(CW@nums\fR will contain \f(CW\*(C`(4, [2, 6])\*(C'\fR. Note that the two
parentheses that return values in the second regular expression cause the
matches to be returned as an array reference.
.SS "lib_dirs"
.IX Subsection "lib_dirs"
.Vb 1
\&  my @dirs = $util\->lib_dirs;
.Ve
.PP
Returns a list of possible library directories to be searched. These are
gathered from the \f(CW\*(C`libsdirs\*(C'\fR and \f(CW\*(C`loclibpth\*(C'\fR Config settings. These are
useful for passing to \f(CW\*(C`first_cat_dir()\*(C'\fR to search typical directories for
library files.
.SH "SUPPORT"
.IX Header "SUPPORT"
This module is stored in an open GitHub
repository <http://github.com/theory/app-info/>. Feel free to fork and
contribute!
.PP
Please file bug reports via GitHub
Issues <http://github.com/theory/app-info/issues/> or by sending mail to
bug\-App\-Info@rt.cpan.org <mailto:bug-App-Info@rt.cpan.org>.
.SH "AUTHOR"
.IX Header "AUTHOR"
David E. Wheeler <david@justatheory.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
App::Info, File::Spec,
App::Info::HTTPD::Apache
App::Info::RDBMS::PostgreSQL
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (c) 2002\-2011, David E. Wheeler. Some Rights Reserved.
.PP
This module is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.