#!/usr/bin/env perl
# perlheader - generate template for perl/sh/awk/python/... scripts
# pure Perl version created by Stewart C. Russell on 02002/12/11

use strict;
use warnings;
use integer;		    # because we're only processing text
use File::Basename;
sub which($);   # proto for a very Unixcentric 'which'

my $progopt=''; # any additional options needed by the program
my $extra='';   # handy line of code that you might need
my $today=localtime(time);
my $scriptlang=basename($0);
my $username=getlogin || getpwuid($<) || "me"; # attempt at user name

if (@ARGV < 1) {		# give usage if not called properly
    print STDERR "Usage: $scriptlang scriptname blurb ...\n";
    exit 1;
}
my $scriptname=shift(@ARGV);
my $base=basename($scriptname);
my $blurb=join(' ', @ARGV);

$scriptlang =~ s/header$//; # remove 'header' from end of script name

# go through the various cases
if ($scriptlang eq 'perl') {
    # a nasty hack, since the Perl interpreter can be in different
    # places on many different systems. So we use env(1) ...
    $progopt=$scriptlang;
    $scriptlang='env';
    # the here document has hashes to deconfuse the POD parser
    ($extra=<<BIGPELAHEREDOCO) =~ s/^\#//gm;
#use strict;
#use warnings;
#use diagnostics;
#use integer;	# You may want to delete this
#
## Your program goes here
#
#
#exit;
#__END__
#
#=head1 NAME
#
#$base - $blurb
#
#=head1 SYNOPSIS
#
#
#
#=head1 DESCRIPTION
#
#
#
#=head1 OPTIONS
#
#
#
#=head1 RETURN VALUE
#
#
#
#=head1 ERRORS
#
#
#
#=head1 EXAMPLES
#
#
#
#=head1 ENVIRONMENT
#
#
#
#=head1 FILES
#
#
#
#=head1 SEE ALSO
#
#
#
#=head1 NOTES
#
#
#
#=head1 CAVEATS
#
#
#
#=head1 DIAGNOSTICS
#
#
#
#=head1 BUGS
#
#
#
#=head1 RESTRICTIONS
#
#
#
#=head1 AUTHOR
#
#$username
#
#=head1 HISTORY
#
#Created $today by $username
#
#\$Log\$
#
#=cut
#
BIGPELAHEREDOCO
}
elsif (($scriptlang =~ /awk$/) or ($scriptlang =~ /sed$/)) {
    $progopt='-f';
}
else {				# no options or extras for the others
    $progopt='';
    $extra='';
}

my $whichlang=which($scriptlang); # path of language executable
unless (defined($whichlang)) {	  # complain and exit if not found
    print STDERR "No $scriptlang in your path.\n";
    exit 1;
}

# now create output script
open(SCRIPT, ">$scriptname") or die "Cannot create $scriptname\n";
print SCRIPT '#!', $whichlang, ' ', $progopt, "\n", 
    '# ', $base, ' - ', $blurb, "\n", 
    '# created by ', $username, ' on ', $today, "\n", 
    '# SCCS:    ', "\%W\% \%G\%\n", 
    '# RCS/CVS: ', "\$Id\$\n", "\n", 
    $extra, "\n";
close(SCRIPT);
chmod 0775, $scriptname;	# make executable
exit;

# a very Unixcentric 'which' near-workalike.
# Because gentlemen don't backtick.
# there are better, more portable (but longer) ways to do this. See:
# http://www.perl.com/language/ppt/src/which/
sub which($) {
    my $filename=shift;
    foreach (split /:/, $ENV{'PATH'}) {
	return "$_/$filename" if (-x "$_/$filename");
    }
    return undef;		# if nothing found
}
__END__

=head1 NAME

perlheader - generate template for perl/sh/awk/python/... scripts

=head1 SYNOPSIS

B<perlheader> F<scriptname> S<blurb ...>

B<awkheader> F<scriptname> S<blurb ...>

B<sedheader> F<scriptname> S<blurb ...>

B<shheader> F<scriptname> S<blurb ...>

B<pythonheader> F<scriptname> S<blurb ...>

...

=head1 DESCRIPTION

B<perlheader> creates an executable script template file F<scriptname>
containing useful C<use> statements, blank revision control tags
and a skeleton POD entry.

If linked to B<awkheader>, B<sedheader>, B<shheader>, ..., it will
create a small executable template for those script languages.

=head1 OPTIONS

None

=head1 RETURN VALUE

Returns zero if successful. Otherwise returns one.

=head1 ERRORS

Helpful error messages ensue:

=over

=item *

if called with too few parameters.

=item *

if the script interpreter can't be found in PATH

=item *

if the output script can't be created.

=back

=head1 EXAMPLES

       perlheader flarp a program to do something or other

will create executable script B<flarp> containing something like:

       #!/usr/bin/env perl
       # flarp - a program to do something or other
       # created by stewart on Dec 01 2002
       # SCCS:    %W% %G%
       # RCS/CVS: $Id$
       
       use strict;
       use warnings;
       use diagnostics;
       use integer;     # You may want to delete this
       
       # Your program goes here
       
       
       exit;
       __END__
       ... lots of POD deleted ...

If a link has been made to B<sedheader>:

       sedheader flarp.sed foo bar

will create B<flarp.sed>:

       #!/bin/sed -f
       # flarp.sed - foo bar
       # created by stewart on Dec 01 2002
       # SCCS:    %W% %G%
       # RCS/CVS: $Id$
       
Just to prove that there are no hard feelings, linking to
B<pythonheader> and running:

       pythonheader flarp.py foo bar

will create B<flarp.py>:

       #!/usr/bin/python 
       # flarp.py - foo bar
       # created by stewart on Dec 01 2002
       # SCCS:    %W% %G%
       # RCS/CVS: $Id$
       
You get the idea.

=head1 ENVIRONMENT

Looks in PATH to find script executables.

=head1 FILES

No external files used.

=head1 SEE ALSO

"The Art of Looking Sideways", by Alan Fletcher (pub Phaidon,
2001. ISBN: 0714834491).

(okay, so what would I<you> put here ...?)

=head1 NOTES

Only perl, awk and sed gave explicit behaviours. Other languages are
supported by default. This means that this will probably work for lots
of languages I've never heard of.

Because the Perl interpreter occasionally appears in different places
on different installations, this program uses B<env> to find the
interpreter. Some people may find this slow in a single-OS
environment, but at least it's likely to work.

=head1 CAVEATS

Very Unixcentric. Assumes that:

=over

=item *

script languages use the # character
for comments

=item *

that the hash-bang method will invoke a particular
interpreter

=item *

that the enviroment variable PATH contains a colon-separated list of
directories.

=back

=head1 DIAGNOSTICS

No useful ones.

=head1 BUGS

None found, but this Perl version only lightly tested on 
Solaris and Linux.

=head1 RESTRICTIONS

None. 

=head1 AUTHOR

Stewart C. Russell, aka Willard B. Trophy on PerlMonks.

=head1 HISTORY

First Perl version Dec 2002 by Stewart C. Russell.
Based on a Bourne Shell script of the same name, written some years 
before.

=cut