The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
scriptname-0.94
River stage zero No dependents
++
/ scriptname

NAME

scriptname - Locate original perl script

VERSION

version 0.94

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. As a special case,

    use scriptname 'lib';

is equivalent to

    use scriptname lib => 'lib';

(unshift the path to the current script + 'lib' in @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.

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

$0

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.

Also depends on version.

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.

THANKS

stevenl@cpan.org, for pointing a silly mistake in my tests

ALTERNATIVE LICENSE TERMS

Optionally, instead of using the Perl 5 programming language licensing terms, you are also autorized to redistribute and/or modify it under the terms of any of the following licenses, at your will: GNU LGPLv2, GNU LGPLv3, CC-LGPLv2, CC-By-SAv3.0.

Please notice that the alternatives given in the previous paragraph apply only for this module and other modules where explicitly stated.

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.

AUTHOR

Humberto Massa <massa@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Humberto Massa.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.