The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
lib-relative-to-1.1000
River stage zero No dependents
/ Directory::relative::to

NAME

Directory::relative::to

DESCRIPTION

Find paths relative to something else

SYNOPSIS

Both of these will look up through the parent directories of the file that contains this code until it finds the root of a git repository, then return the absolute paths of the 'lib' and 't/lib' directories in that repository.

    use Directory::relative::to (relative_dir);

    my @dirs = relative_dir( GitRepository => qw(lib t/lib) );

or:

    use Directory::relative::to;

    my @dirs = Directory::relative::to->relative_dir(
        ParentContaining => '.git/config' => qw(lib t/lib)
    );

Yes, it's practically identical to how you'd invoke lib::relative::to. This module is just a very thin wrapper around that.

WHY?

Just like how I got fed up with Sam for the reasons explained in lib::relative::to I have a new colleague who wrote:

    use FindBin qw($Bin);
    ...
    my $fixture_path = "$Bin/../../fixtures";

That string of repeated ../s is an abomination unto the Lord.

FUNCTIONS

relative_dir

Can be invoked either as a class method or can optionally be exported and called as a normal function.

This takes the several arguments, the first of which is the name of a lib::relative::to plugin, the remainder being arguments to that plugin. In general the argument list will take the form:

plugin_name
plugin_configuration
list_of_directories

Note that under the bonnet this function uses lib::relative::to's undocumented private functions.

It normally returns a list of fully-qualified directory names, but if there is only one directory to be returned and you call it in scalar context you will get a scalar name.

If there aer multiple directory names but you use scalar context that is a fatal error.

BUGS

I only have access to Unix machines for development and debugging. There may be bugs lurking that affect users of exotic platforms like Amiga, Windows, and VMS. I welcome patches, preferably in the form of a pull request. Ideally any patches will be accompanied by tests, and those tests will either skip or pass on Unix.

AUTHOR, COPYRIGHT and LICENCE

Copyright 2022 David Cantrell <david@cantrell.org.uk>.

This software is free-as-in-speech as well as free-as-in-beer, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

This software is also free-as-in-mason.