https://github.com/grinnz/lib-relative

lib::relative
https://github.com/grinnz/lib-relative

Last synced: about 2 months ago
JSON representation

lib::relative

• Host: GitHub
• URL: https://github.com/grinnz/lib-relative
• Owner: Grinnz
• License: other
• Created: 2017-06-26T17:23:48.000Z (over 7 years ago)
• Default Branch: master
• Last Pushed: 2023-07-24T01:21:26.000Z (over 1 year ago)
• Last Synced: 2024-10-11T21:23:37.166Z (3 months ago)
• Language: Perl
• Homepage: https://metacpan.org/pod/lib::relative
• Size: 32.2 KB
• Stars: 2
• Watchers: 2
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.pod
  • Changelog: Changes
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

README

        
=pod

=head1 NAME

lib::relative - Add paths relative to the current file to @INC

=head1 SYNOPSIS

  # Path is relative to this file, not current working directory

  use lib::relative 'path/to/lib';

  use lib::relative '../../lib';

  

  # Add two lib paths, as in lib.pm

  use lib::relative 'foo', 'bar';

  

  # Absolute paths are passed through unchanged

  use lib::relative 'foo/baz', '/path/to/lib';

  

  # Equivalent code using core modules

  use Cwd ();

  use File::Basename ();

  use File::Spec ();

  use lib File::Spec->catdir(File::Basename::dirname(Cwd::abs_path __FILE__), 'path/to/lib');

=head1 DESCRIPTION

Adding a path to L<@INC|perlvar/"@INC"> to load modules from a local directory

may seem simple, but has a few common pitfalls to be aware of. Directly adding

a relative path to C<@INC> means that any later code that changes the current

working directory will change where modules are loaded from. This applies to

the C<.> path that used to be in C<@INC> by default until perl 5.26.0, or a

relative path added in code like C, and may be a

vulnerability if such a location is not supposed to be writable. Additionally,

the commonly used L module relies on interpreter state and the path to

the original script invoked by the perl interpreter, sometimes requiring

workarounds in uncommon cases like generated or embedded code. This module

proposes a more straightforward method: take a path relative to the

L, absolutize it, and add it to

C<@INC>.

If this module is already available to be loaded, it can be used as with

L.pm, passing relative paths, which will be absolutized relative to the

current file then passed on to L. Multiple arguments will be separately

absolutized, and absolute paths will be passed on unchanged.

For cases where this module cannot be loaded beforehand, the last section of

the L"SYNOPSIS"> can be copy-pasted into a file to perform the same task.

=head1 CAVEATS

Due to C<__FILE__> possibly being a path relative to the current working

directory, be sure to use C or the equivalent code from

L"SYNOPSIS"> as early as possible in the file. If a C occurs before

this code, it will add the incorrect directory path.

All file paths are expected to be in a format appropriate to the current

operating system, e.g. C<..\\foo\\bar> on Windows. L can

be used to form directory paths portably.

=head1 BUGS

Report any issues on the public bugtracker.

=head1 AUTHOR

Dan Book 

=head1 COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Dan Book.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

=head1 SEE ALSO

L, L, L

=cut