NAME

File::Path::Redirect - Poor mans symbolic link path redirection

SYNOPSIS

use File::Path::Redirect;

# Run this example in 'examples' dir
# Create  a test file to link to
#
my $source_path="path_to_file.txt";
my $contents="Probably a large file";

open my $fh, ">", $source_path or die $!;
print $fh $contents;
close $fh;



# 'Link' or redirect a file to another
#
my $link_path="my_link.txt";

make_redirect($source_path, $link_path);


# Elsewhere in the application normal and redirect files are tested
my $path=follow_redirect($link_path);

# open/process $path as normal
open my $f,"<", $path or die $!;
while(<$f>){
  print $_;
}

DESCRIPTION

This module implements a handful of functions implementing 'user space' file path redirection, similar to a symbolic link on your file system.

It supports chained redirect files, with recursion limit.

WHY SHOULD I USE THIS?

• Not all File Systems support Sumbolic links

  For example FAT and exFAT variants do not support symbolic links.

• Symbolic links only work withing the same volume

  If you wanted to symbolic link to a file on a different volume, you can't

• Copying files my night be feasable

  Slow and size constrained external media means extra copies of large files might not fit. Also slow devices would take too long to physically copy

HOW IT WORKS

The redirect ( or link ) file is just a basic text file. It contains a single line of the format:

!<symlink>PATH

!<symlink> is a magic header PATH is the relative path to a file it links to. It can be a link to another link file.

Before using a path in an open function, the path can be passed to follow_redirect. The return value is the path of the first non link file found. This is path can be used in the open call instead.

API

Creating Redirects

make_redirect

my $path = make_redirect $existing_file, $link_file, $force;

Creates a new redirect file at $link_file containing a link to the file located at $existing_file.

$existing_file can be a relative or absolute path.

The file is only created if $link_file doesn't already exist, or $force is a true value.

Returns the relative path between the two files if possible, otherwise a absolute path. Dies on any IO related errors in creating / opening / writing / closing the link file.

Using Redirects

follow_redirect

my $path = follow_redirect $file_path, $limit;

Given a file path $path, it attempts to open the file, check it is a redirect file. If so it parses and follows the link path. The process is recursive until the file does not look like a link path, or until the total number of redirects is equal to or greater than $limit.

$limit is an optional parameter and by default is 10.

Returns the final redirect path. The path could be relative or absolute.

Dies on any IO errors when processing a redirect chain.

PERFORMANCE CONSIDERATIONS

Each redirect file encountered is opened and read. For repeated access to the same file, it is best to store the results of the follow_redirect function.

For more comprehensive solution, File::Meta::Cache (which uses this module) might suit your needs

REPOSITORY and BUG REPORTING

Please report any bugs and feature requests on the repo page: GitHub

AUTHOR

Ruben Westerberg, drclaw@mac.com

COPYRIGHT AND LICENSE

Copyright (C) 2026 by Ruben Westerberg

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, or under the MIT license