NAME

scriptname - Locate original perl script

VERSION

This document describes scriptname version 0.6

SYNOPSIS

    use scriptname;
    use lib scriptname::mydir . '/../lib';

or

    use scriptname lib => '../lib';

or

    use scriptname ':all';
    my $scriptbasename = mybase;

you can also use

    no scriptname lib => '../lib';

to remove a relative path from @INC.

DESCRIPTION

Locates the full path to the current script's directory to allow the use of of paths relative to the script's directory. Also, unshift paths relative to the script's directory in @INC.

This allows a user to setup a directory tree for some software with directories <root>/bin and <root>/lib, and then the above example will allow the use of modules in the lib directory without knowing where the software tree is installed, even if the name by which the script was called is a symbolic link to the path where the ../bin and the ../lib actually are.

If perl is invoked using the -e option or the perl script is read from STDIN then the module sets mydir to the current working directory.

EXPORTABLE FUNCTIONS

myname

fully qualified path for the script (with all links resolved), undef if called from -e or STDIN

mybase

basename of myname, or undef

mydir

dirname of myname, or the current working directory if called from -e or STDIN

The result of myname is also put in $0 unless called from -e or STDIN.

DIAGNOSTICS

chdir() too early

The module croaks if the script can manage to call chdir() before the

  use scriptname;

Please, don't do that.

KNOWN ISSUES

The module can, under some circumstances, not croak even if the the script called chdir() before the use. In that case, the returned results can be WRONG. So, as I said, please, don't do that.

DEPENDENCIES

perl5.8 and the standard modules File::Basename, Carp, Exporter, Cwd and lib.

The tests depend on Test::More, which is a standard module, and Test::Perl::Critic, which is not.

INCOMPATIBILITIES

Differences from FindBin

scriptname does not search PATH. It makes one of the following assumptions:

$0 comes with an absolute filename (starting from root)

This can happen:

• When the script was called with perl -S -- in this case, perl looked the PATH for the script;
• When the script was called with perl absolute_file_name;
• When the script was called by the shebang and the shell/kernel (whoever interpreted the shebang) was passed pathless command name -- when the shell/kernel searched the PATH and found the file, it passes the absolute filename to perl;
• When the script was called by the shebang and the shell/kernel was passed an absolute filename -- when this is the case, the shell/kernel passes the absolute pathname unaltered to perl.

$0 comes with a filename relative to the current directory

This happens:

• When the script was called with perl relative_file_name -- perl will search the filename under the current directory;
• When the script was called by the shebang and the shell/kernel was passed a relative filename -- when this is the case, the kernel/shell passes the relative filename to perl, also unaltered.

scriptname follows symbolic links.

And scriptname has the lib option, to prepend library paths relative to scriptname::mydir to @INC.

BUGS AND LIMITATIONS

See "KNOWN ISSUES".

Please report any bugs or feature requests to bug-scriptname@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Humberto Massa <massa@cpan.org>

LICENCE AND COPYRIGHT

Copyright (c) 2008, Humberto Massa <massa@cpan.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. Optionally, you can redistribute and/or modify it under the terms of any of the following licenses, at your will: GNU GPLv2, GNU GPLv3, CC-GPLv2, CC-SAv3.0.

Please notice that the alternatives given in the previous paragraph apply only for this module.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.