/ 
Unix-Shebang-0.1
/ Unix::Shebang

NAME

Unix::Shebang - Utility module for Unix shebang lines.

VERSION

This document describes Unix::Shebang version 0.1

SYNOPSIS

You can use Unix::Shebang from the command line like this:

perl -MUnix::Shebang -e'set_shebangs' file1.pl file2.pl ... fileN.pl

Or like this:

perl Shebang.pm file1.pl file2.pl fileN.pl

Or you can use the object-oriented interface:

use Unix::Shebang ( );

# This object is using the defaults, which is to replace any shebangs
# that matches /perl to the path of the currently running interpreter.
my $shebang = Unix::Shebang->new( );

# This object is configured to add a /opt/bin/sh shebang on files
# that has a shebang that matches /sh.
my $sh_shebang = Unix::Shebang->new({
    interpreter => '/opt/bin/sh',
    must_match  => '/sh',
});

# This object is configured to add a /opt/bin/perl shebang on files
# that has a shebang that matches /perl.
my $perl_shebang = Unix::Shebang->new({
    interpreter => '/opt/bin/perl',
    must_match  => 'perl',
});

my $file = './blib/scripts/my_wicked_perl_script';
my $interpreter_for_file = $shebang->has_shebang($file);
if ($interpreter_for_file) {
    print "$file is a script using $interpreter_for_file as interpreter.\n";

    # set shebang to path of the perl we are running under,
    # (which is according to the config for the $shebang object above).
    $shebang->set_shebang($file); 
}
else {
    print "$file has no interpreter set, or is not a script.";
}

DESCRIPTION

Shebang you say? This term also uncommonly and commonly called hashbang or hashpling is the pair of characters in the first line of a file that causes Unix-like operating systems to execute the file using the interpreter specified by the rest of the line. A shebang consists of the two characters, # and ! followed by the full path of the interpreter program and it's arguments. This is a great feature for us interpreter-loving creatures, but it certainly has its limitations, especially when it comes to script distribution.

One common problem when juggling different perl installations on the same system, or even when using a different perl location than the more common /usr/bin/perl is the tedious job of changing the interpreter path in the first line of the script.

This module can be used by module authors and end users alike to set the interpreter to the running perl (or a custom perl interpreter) upon installation of a distribution.

SUBROUTINES/METHODS

CONSTRUCTOR

Unix::Shebang->new(\%options)

Create a new Unix::Shebang object. Valid options are:

interpreter -  The new interpreter to be used.

If the interpreter is not set, the currently running perl will be used when changing files.

ATTRIBUTES

Unix::Shebang->get_interpreter
Unix::Shebang->set_interpreter

This is the new interpreter the scripts will change to when sending files to change_shebang.

Unix::Shebang->get_must_match
Unix::Shebang->set_must_match

This is a text string pattern (not regular expression), that any existing shebang must contain if we're going to change it.

METHODS

Unix::Shebang->has_shebang($file)

Returns the interpreter path if the file has a shebang.

Unix::Shebang->set_shebang($file)

Set the shebang for a file. Will add a shebang if the file has no shebang, but tests if the file is a text file first. In general it's a smart move to check if the file already has a shebang with has_shebang first.

The interpreter path in the interpreter attribute will be used, if it does not exist the path of the currently running perl will be used.

PRIVATE METHODS

Unix::Shebang->_find_perl( )

Try to find the path of the running perl interpreter. Will return the custom interpreter if it is set.

SUBROUTINES

Unix::Shebang->run(@ARGV)

This is the function that is run if this module is run as a script.

set_shebangs

This is a function that is exported by default so we can use this module on the command line. It is just a shortcut to run.

Example usage:

$ perl -MUnix::Shebang -e'set_shebangs' file1 file2 ... fileN

EXPORT

This module exports the function set_shebangs by default. See description for the function above.

DIAGNOSTICS

Couldn't open file %s for reading: %s

An error occured when trying to open a file for reading. This is likely to be a problem with insufficient permissions to access the file or with the underlying operating system.

Couldn't close file %s: %s

An error occured when closing the file. Probably an error with the underlying operating system. Consult the documentation of your operating system.

Couldn't open file %s for writing: %s

An error occured while trying to open a file for writing. Do you have sufficient privileges to write to the file? See the end of the error message for a possible explaination and look up the error in your operating systems documentation.

Couldn't close file %s after writing: %s

An error occured when closing the file. Probably an error with the underlying operating system. Consult the documentation of your operating system.

CONFIGURATION AND ENVIRONMENT

Unix::Shebang requires no configuration files or environment variables.

DEPENDENCIES

IO::File
File::Spec

INCOMPATIBILITIES

This module has little purpose on non Unix-like operating systems, but we do not take any action when running under i.e Win32 for example. This is because someone might still have a perfectly good reason for changing shebangs. :-)

BUGS AND LIMITATIONS

No bugs have been reported.

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

AUTHOR

Ask Solem <asksh@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2007, Ask Solem <asksh@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.

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.