NAME

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

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 File::Basename ();
     use File::Spec ();
     use lib File::Spec->catdir(File::Spec->rel2abs(File::Basename::dirname(__FILE__)), 'path/to/lib');

DESCRIPTION

   Adding a path to @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 @INC means that any later code that changes the
   current working directory will change where modules are loaded from.
   This applies to the . path that used to be in @INC by default until
   perl 5.26.0, or a relative path added in code like use lib
   'path/to/lib', and may be a vulnerability if such a location is not
   supposed to be writable. Additionally, the commonly used FindBin 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 current file,
   absolutize it, and add it to @INC.

   If this module is already available to be loaded, it can be used as
   with lib.pm, passing relative paths, which will be absolutized relative
   to the current file then passed on to lib. 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 "SYNOPSIS" can be copy-pasted into a file to perform the
   same task.

CAVEATS

   Due to __FILE__ possibly being a path relative to the current working
   directory, be sure to use lib::relative or the equivalent code from
   "SYNOPSIS" as early as possible in the file. If a chdir 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. ..\\foo\\bar on Windows. "catdir" in
   File::Spec can be used to form directory paths portably.

BUGS

   Report any issues on the public bugtracker.

AUTHOR

   Dan Book <[email protected]>

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)

SEE ALSO

   lib, FindBin, Dir::Self

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.