From Code to Community: Sponsoring The Perl and Raku Conference 2025 Learn more

 / 
App-hopen-0.000015
River stage zero No dependents
/ App::hopen::Util::BasedPath

NAME

App::hopen::Util::BasedPath - A path relative to a specified base

SYNOPSIS

A BasedPath represents a path to a file or directory, plus a directory with respect to which that path is defined. That means you can rebase the file or dir while retaining the relative path. Usage example:


            

              
              
my $based = based_path(path => file('foo'), base => dir('bar'));
$based->orig;                   # Path::Class::File for bar/foo
$based->path_on(dir('quux'));   # Path::Class::File for quux/foo

MEMBERS

path

The path, as a Path::Class::File or Path::Class::Dir instance. May not be specified as a string when creating a new object, since there's no reliable way to tell whether a file or directory would be intended.

This must be a relative path, since the whole point of this module is to combine partial paths!

base

A Path::Class::Dir to which the "path" is relative. May be specified as a string for convenience; however, '' (the empty string) is forbidden (to avoid confusion). Use dir() for the current directory or dir('') for the root directory.

orig_cwd

The working directory at the time the BasedPath instance was created. This is an absolute path.

FUNCTIONS

is_file

Convenience function returning whether "path" is a Path::Class::File.

orig

Returns a Path::Class::* representing "path" relative to "base", i.e., the original location.

path_wrt

Returns a Path::Class::* representing the relative path from a given directory to the original location. (wrt = With Respect To) Example:


            

              
              
# In directory "project"
my $based = based_path(path => file('foo'), base => dir('bar'));
$based->orig;                   # Path::Class::File for bar/foo
$based->path_wrt('..');         # Path::Class::File for project/bar/foo

path_on


            

              
              
my $new_path = $based_path->path_on($new_base);

Given a Path::Class::Dir, return a Path::Class::* instance representing "path", but relative to $new_base instead of to "base".

This is in some ways the opposite of Path::Class::File::relative():


            

              
              
# in directory 'dir'
my $file = file('foo.txt');     # The foo.txt in dir/
say $file->relative('..');      # "dir/foo.txt" - same file, but
                                # accessed from "..".
my $based = based_path(path=>file('foo.txt'), base=>'');
    # Name foo.txt, based off dir
say $based->path_on(dir('..')); # dir/../foo.txt - a different file

_stringify

Stringify the instance in a way that is human-readable, but NOT suitable for machine consumption.

BUILD

Sanity-check the arguments.

STATIC FUNCTIONS

based_path

A synonym for App::hopen::Util::BasedPath->new(). Exported by default.