Hi Paul,
> One quibble: those long comments are
> probably more trouble than they're worth.
I heavily disagree: This piece of code needs to consider
- the distinction between POSIX:2017 and earlier versions,
- execlp/execvp vs. execl/execv,
- GuixSD vs. traditional file system layouts,
- perl documentation,
- perl source code (toke.c).
> I suggest we just cite perlrun's man page
No, that man page represents only a small part of the entire picture.
Future maintainers should not have to wade through a mail thread of 12 mails
in order to understand a piece of code.
> I found that at least one important detail
> was missing: the "#! -*-perl-*-" line is not just there for Emacs, but is
> also
> there for Perl.
Oh, indeed! So, both this line and the '-x' option are essential for perl.
I'm updating the comment:
--- a/build-aux/useless-if-before-free
+++ b/build-aux/useless-if-before-free
@@ -6,12 +6,12 @@
# or execvp() fails with ENOEXEC if it is a script that does not start
# with a #! line. The script interpreter mentioned in the #! line has
# to be /bin/sh, because on GuixSD systems that is the only program that
-# has a fixed file name. The second line is for editing this file in
-# Emacs. The next two lines below are valid code in both sh and perl.
-# When executed by sh, they re-execute the script through the perl
-# program found in $PATH. The '-x' option is essential; without it,
-# perl would re-execute the script through /bin/sh. When executed by
-# perl, the next two lines are a no-op.
+# has a fixed file name. The second line is essential for perl and is
+# also useful for editing this file in Emacs. The next two lines below
+# are valid code in both sh and perl. When executed by sh, they re-execute
+# the script through the perl program found in $PATH. The '-x' option
+# is essential as well; without it, perl would re-execute the script
+# through /bin/sh. When executed by perl, the next two lines are a no-op.
eval 'exec perl -wSx "$0" "$@"'
if 0;
> I found that they got in the way of my understanding the code
Do you mean, we should highlight the comment about the program itself?
Like this:
#!/bin/sh
#! -*-perl-*-
# This is a prologue that allows to run a perl script as an executable
# on systems that are compliant to a POSIX version before POSIX:2017.
# On such systems, the usual invocation of an executable through execlp()
# or execvp() fails with ENOEXEC if it is a script that does not start
# with a #! line. The script interpreter mentioned in the #! line has
# to be /bin/sh, because on GuixSD systems that is the only program that
# has a fixed file name. The second line is essential for perl and is
# also useful for editing this file in Emacs. The next two lines below
# are valid code in both sh and perl. When executed by sh, they re-execute
# the script through the perl program found in $PATH. The '-x' option
# is essential as well; without it, perl would re-execute the script
# through /bin/sh. When executed by perl, the next two lines are a no-op.
eval 'exec perl -wSx "$0" "$@"'
if 0;
# ╭───────────────────────────────────────────────────────────────────────╮
# │ Detect instances of "if (p) free (p);". │
# │ Likewise "if (p != 0)", "if (0 != p)", or with NULL; and with braces. │
# ╰───────────────────────────────────────────────────────────────────────╯
my $VERSION = '2018-03-07 03:47'; # UTC
...
Bruno
