NAME

FindBin::Parents - List the parent directories of a path, from the path to root.

SYNOPSIS

use FindBin::Parents qw( dir_paths );

# on *NIX (incl. OSX)
# '/foo/bar/bim/bam' yields
# /foo/bar/bim/bam
# /foo/bar/bim
# /foo/bar
# /foo
# /
#
# on VMS
# 'Bletch$Blort:[foo.bar.bim.bam]' yields
# Bletch$Blort:[foo.bar.bim.bam]
# Bletch$Blort:[foo.bar.bim]
# Bletch$Blort:[foo.bar]
# Bletch$Blort:[foo]
# followed by the device root.
#
# on MSW
# 'z:/foo/bar/bim/bam' yields
# z:\foo\bar\bim\bam
# z:\foo\bar\bim
# z:\foo\bar
# z:\foo
# z:\
#
# (each example assumes the path is an existing directory,
# see below.)
#
# $path must be absolute, or the literal 'pwd'; a relative
# path croaks (see "Relative paths" below).  the directory is
# passed through FindBin::Bin::canon_dir, which cleans '.' and
# '..' without resolving symlinks.
#
# note that the return value is context-sensitive:

my $array_ref   = dir_paths $path;
my @array       = dir_paths $path;

# the second argument, $assume_dir, decides whether the last
# component of $path is a directory:
#
# defined: used as given, without examining the path.  this
# is for paths that do not exist, mainly in testing, or before
# creating a directory, e.g., to check the directories above a
# temporary directory.  a true value treats the path as a
# directory; a defined false value ('' or 0) treats the last
# component as a file.
#
# not given or undef: the path must exist and is checked with
# -d.  a directory is the first entry; anything else (e.g., a
# file such as $0) is dropped and the walk starts at its
# parent.  a path that does not exist croaks: there is nothing
# to check.
#
# see also: File::Spec::splitpath.

# $assume_dir not given or undef, the path exists:

dir_paths '/etc';                     # /etc /       (a directory)
dir_paths '/etc/passwd';              # /etc /       (a file)
dir_paths '/etc', undef;              # same as not given

# $assume_dir not given or undef, the path does not exist:

dir_paths '/foo/bar/bletch';          # croaks

# $assume_dir defined, the path need not exist:

dir_paths '/foo/bar/bletch', 1;       # /foo/bar/bletch /foo/bar /foo /
dir_paths '/foo/bar/bletch', '';      # /foo/bar /foo /
dir_paths '/usr/bin', '';             # /usr /  ('' overrides -d)

# full example of a non-existent path with assume_dir true
# or false:

my @found
= dir_paths '/foo/bar/bletch/blort/non-existent', 1;

# returns:
# /foo/bar/bletch/blort/non-existent    <- second argument true
# /foo/bar/bletch/blort
# /foo/bar/bletch
# /foo/bar
# /foo
# /

my @found
= dir_paths '/foo/bar/bletch/blort/non-existent', '';

# returns:
# /foo/bar/bletch/blort
# /foo/bar/bletch
# /foo/bar
# /foo
# /

# without the second argument this path croaks, since it
# does not exist.

# The literal string 'pwd' is a shorthand: dir_paths resolves it
# to FindBin::Bin::pwd before the walk.  No separate import of
# pwd is required:

use FindBin::Parents qw( dir_paths );

my @above_cwd = dir_paths 'pwd';

# If the working directory is /home/user/projects/myapp:
# /home/user/projects/myapp
# /home/user/projects
# /home/user
# /home
# /

# This differs from passing $Bin_l or $Bin_p, which walk up from
# the directory containing the running program ($0), not from CWD.
# In most scripts those are the same; they diverge when the script
# is invoked from a different directory or via a wrapper.

# To resolve symlinks in the CWD before the walk, call pwd yourself
# and pass the result through Cwd::abs_path:

use FindBin::Bin    qw( pwd );
use Cwd             qw( abs_path );

my @above_real_cwd = dir_paths abs_path( pwd );

# A relative path croaks; convert it to an absolute path first.
# canon_dir prepends pwd, giving a logical path; prepending the
# physical working directory gives a physical one.  'lib' must
# exist, or pass $assume_dir:

use FindBin::Bin            qw( canon_dir pwd );
use Cwd                     qw( abs_path );
use File::Spec::Functions   qw( catdir );

my @logical     = dir_paths canon_dir 'lib';
my @physical    = dir_paths canon_dir catdir abs_path( pwd ), 'lib';

# Relative to the program's directory: prepend $Bin, $Bin_l, or
# $Bin_p and clean the result with canon_dir.  '..' is removed
# lexically, so it climbs the logical path with $Bin_l and the
# physical path with $Bin_p:

use FindBin::Bin            qw( canon_dir $Bin $Bin_l $Bin_p );

my @from_bin    = dir_paths canon_dir catdir $Bin,   '..', 'lib';
my @from_bin_l  = dir_paths canon_dir catdir $Bin_l, '..', 'lib';
my @from_bin_p  = dir_paths canon_dir catdir $Bin_p, '..', 'lib';

DESCRIPTION

FindBin::Parents exports dir_paths, which returns the given path, if it is a directory, and each of its ancestors through root, nearest first. If the last component of the path is not a directory the list starts at its parent. A path that does not exist croaks unless $assume_dir says what it is.

The canonical use is to inspect which directories FindBin::libs searched when looking for lib, etc, or other named trees:

use FindBin::Bin    qw( $Bin_l $Bin_p );
use FindBin::Parents qw( dir_paths );

# show the logical walk (what FindBin::libs sees with noabspath)
say for dir_paths $Bin_l;

# show the physical walk (what FindBin::libs sees by default)
say for dir_paths $Bin_p;

# show the walk above CWD (independent of $0)
say for dir_paths 'pwd';

Passing the literal string 'pwd' is a built-in shorthand: dir_paths calls FindBin::Bin::pwd internally and uses the result as the starting path, without requiring the caller to import pwd. pwd returns the logical working directory (symlinks preserved, like pwd -L) when $ENV{ PWD } is valid; otherwise it warns and returns getcwd, with symlinks resolved. It caches its first result, so 'pwd' is the working directory at that first call: a later chdir does not change it. See "pwd()" in FindBin::Bin.

'pwd' is useful when the script is invoked from a directory different from the one it lives in. It produces a walk up from where the process is running, whereas $Bin_l and $Bin_p walk up from where the script lives. In interactive sessions (e.g., perl -d -e 0) there is no script: $Bin_l is pwd and $Bin_p is its physical path.

Relative paths

dir_paths requires an absolute path. A relative path would be checked with -e and -d against the process's current directory but walked from FindBin::Bin::pwd, which is cached: after a chdir the two differ. Rejecting relative paths leaves the caller to choose which directory they are relative to:

logical

canon_dir $relative prepends pwd, symlinks preserved.

physical

canon_dir catdir abs_path( pwd ), $relative prepends the working directory with symlinks resolved.

program directory

canon_dir catdir $Bin, $relative, canon_dir catdir $Bin_l, $relative, or canon_dir catdir $Bin_p, $relative makes it relative to the directory of $0.

Paths relative to the program: $Bin, $Bin_l, $Bin_p

FindBin::Bin gives the program's directory two ways: $Bin_l, the logical path (symlinks preserved), and $Bin_p, the physical path (symlinks resolved). $Bin is $Bin_p by default and $Bin_l with noabspath, matching the path FindBin::libs searches from. All three are absolute.

canon_dir cleans . and .. lexically, without examining the filesystem. Applied to one of these with a relative path appended, .. removes the preceding component of that path: with $Bin_l it climbs the logical tree, with $Bin_p the physical one. These differ when the program's directory is reached through a symlink:

# /home/user/bin is a symlink to /opt/tools/bin,
# the program is /home/user/bin/frobnicate:
#
# $Bin_l = /home/user/bin
# $Bin_p = /opt/tools/bin

dir_paths canon_dir catdir $Bin_l, '..', 'lib';
# /home/user/lib /home/user /home /

dir_paths canon_dir catdir $Bin_p, '..', 'lib';
# /opt/tools/lib /opt/tools /opt /

Each path must exist, or $assume_dir must be given; see "$assume_dir".

See "canon_dir()" in FindBin::Bin, "$Bin_l and Bin_l()" in FindBin::Bin, "$Bin_p and Bin_p()" in FindBin::Bin, and "$Bin and Bin()" in FindBin::Bin.

Arguments

$path

The starting path, which must be absolute. The literal 'pwd' is replaced by FindBin::Bin::pwd. A false path, including '0', croaks with Bogus dir_paths: false path argument. A relative path croaks with Bogus dir_paths: '$path' is not an absolute path. Without $assume_dir, a path that does not exist croaks with Bogus dir_paths: '$path' does not exist; pass $assume_dir to treat it as a directory (true) or a file ('').

$assume_dir

Optional. Whether the last component of $path is a directory:

defined

Used as given; the path is not examined and need not exist. A true value treats the path as a directory, so it is the first entry:

dir_paths '/foo/bar/bletch', 1;   # /foo/bar/bletch /foo/bar /foo /

A defined false value ('' or 0) treats the last component as a file, so the list starts at its parent, even for an existing directory:

dir_paths '/foo/bar/bletch', '';  # /foo/bar /foo /
dir_paths '/usr/bin', '';         # /usr /

This is for paths that do not exist, mainly in testing.

It is also useful before creating a directory. The security of a temporary directory depends on the directories above it: anyone who can write to one of them can rename or replace what is below it. When that affects the code's execution, list the directories above the planned path and check them before creating it:

my $tmpdir  = catdir $base, "frobnicate.$$";

for my $dir ( dir_paths $tmpdir, '' )
{
    # e.g., owned by root or the user, not group or other
    # writable unless sticky, as /tmp is.
    ...
}

mkdir $tmpdir, 0700
or die "mkdir '$tmpdir': $!";

With '' the planned directory itself is dropped, and the walk starts at $base, which must exist to be checked. With 1 the list starts at $tmpdir, before it exists.

not given, or undef, and the path exists

The path is checked with -d. A directory is the first entry; anything else, such as a file, is dropped:

dir_paths '/etc';                 # /etc /
dir_paths '/etc/passwd';          # /etc /
not given, or undef, and the path does not exist

There is nothing to check, so dir_paths croaks:

dir_paths '/foo/bar/bletch';      # croaks

Return value

In list context, the list of directories. In scalar context, a reference to a copy of that list: changing it does not change the cache.

Caching

Results are cached by $path as given ('pwd' replaced by FindBin::Bin::pwd) and whether its last component is treated as a directory ($assume_dir, or the -e and -d tests, made on every call before the cache is consulted).

The walk is computed from those strings alone, without examining the filesystem: canon_dir cleans the path lexically and FindBin::Bin::pwd is cached. Relative paths, which would depend on the current directory, are rejected. A cached entry does not go stale, including after a chdir. clear_parent_cache empties the cache, releasing its memory:

use FindBin::Parents qw( dir_paths clear_parent_cache );

clear_parent_cache;

SEE ALSO

FindBin::Bin

$Bin, $Bin_l, and $Bin_p for the program's directory; "pwd()" in FindBin::Bin for the working directory, its $ENV{ PWD } check, and caching; "canon_dir()" in FindBin::Bin for converting relative paths; "Resolving the working directory" in FindBin::Bin for chdir.

FindBin::libs