- NAME
- SYNOPSIS
- DESCRIPTION
- BUGS

# NAME

ActiveState::Path - Collection of small utility functions

# SYNOPSIS

      use ActiveState::Path qw(find_prog);
      my $ls = find_prog("ls");

# DESCRIPTION

This module provides a collection of small utility functions dealing with file paths.

The following functions are provided:

abs_path( $path )

  Returns an absolute pathname denoting the same file as $path. If $path is already absolute it is returned unchanged. The $path does not have to reference an existing file or directory.

  This functions differs from realpath() by only removing "." or ".." segments at the beginning of $path and by only resolving the symlinks needed to process the ".." segments correctly. The realpath() function also requires the file at $path to exist.

find_prog( $name )
find_prog( $path )

  This function returns the full path to the given program if it can be located on the system. Otherwise `undef` is returned.

  The returned path might be relative.

is_abs_path( $path )

  Returns TRUE if $path is an absolute file name. This function works the same as File::Spec method file_name_is_absolute().

join_path( $base, $path )

  Returns a path that will reference the same file as $path does when the current directory is $base. If $path is absolute then it is returned unchanged.

  The $base should reference an existing directory. The $path does not have to refence an existing file or directory.

  Any leading "." and ".." segments are removed from the $path before the paths are joined. In order to process ".." segments join_path() will need to resolve symlinks in $base, and the function might croak if this involves a symlink cycle.

path_list()

  Returns the list of directories that will be searched to find programs. The path_list() is derived from the PATH environment variable. In scalar context this returns the number of paths to be searched.

  On Unix when the PATH environment variable is not present then this function returns an empty list, but most shells still default to a path list like (/usr/bin, /bin).

realpath( $path )

  Returns the canonicalized absolute pathname of the path passed in. All symbolic links are expanded and references to /./, /../ and extra / characters are resolved. The $path passed in must be an existing file. The function will croak if not, or if the symbolic links can't be expanded.

  This differs from the Cwd::realpath() function in that $path does not have to be a directory.

rel_path( $base, $path )

  Return a relative pathname that denotes the same file as $path when $base is the current directory.

  The $base should reference an existing directory. The $path does not have to refence an existing file or directory.

  This function differs from the File::Spec method abs2rel() in that it make sure that any ".." segments in the returned value is correct when the corresponding $base segments are symlinks. If the $base path contains symlink cycles there might not be any relative path that can be produced, and in that case rel_path() falls back to returning abs_path($path).

unsymlinked( $path )

  If $path denotes a symlink expand it, otherwise return $path unchanged. The $path must reference an existing file. This function differs from realpath() by only expanding the symlink at the last segment of $path.

  On systems that don't implement symlinks this function is a noop, always returning $path unchanged.

  This function will croak if it's not possible to expand the symlink because of cycles.

# BUGS

none.