FM / bin

/usr/bin

Name	Size	Mode	Actions
aclocal	36478	0755	edit dl rm
aclocal-1.16	36478	0755	edit dl rm
addr2line	34224	0755	edit dl rm
agentxtrap	25128	0755	edit dl rm
animate	12128	0755	edit dl rm
ar	63448	0755	edit dl rm
arch	38232	0755	edit dl rm
arpaname	12104	0755	edit dl rm
as	911264	0755	edit dl rm
aspell	163328	0755	edit dl rm
at	1276	0755	edit dl rm
atq	1278	0755	edit dl rm
atrm	1280	0755	edit dl rm
autoconf	14768	0755	edit dl rm
autoheader	8534	0755	edit dl rm
autom4te	32181	0755	edit dl rm
automake	257949	0755	edit dl rm
automake-1.16	257949	0755	edit dl rm
autoreconf	21066	0755	edit dl rm
autoscan	17124	0755	edit dl rm
autoupdate	33872	0755	edit dl rm
awk	685848	0755	edit dl rm
b2sum	59072	0755	edit dl rm
base32	42464	0755	edit dl rm
base64	42488	0755	edit dl rm
basename	38312	0755	edit dl rm
bash	1154680	0755	edit dl rm
bashbug-64	7348	0755	edit dl rm
batch	137	0755	edit dl rm
bison	448224	0755	edit dl rm
bunzip2	37744	0755	edit dl rm
bzcat	37744	0755	edit dl rm
bzcmp	2128	0755	edit dl rm
bzdiff	2128	0755	edit dl rm
bzgrep	1677	0755	edit dl rm
bzip2	37744	0755	edit dl rm
bzip2recover	16832	0755	edit dl rm
bzless	1259	0755	edit dl rm
bzmore	1259	0755	edit dl rm
c++	1266616	0755	edit dl rm
c++filt	29584	0755	edit dl rm
c89	224	0755	edit dl rm
c99	215	0755	edit dl rm
cagefs_enter.proxied	1296	0755	edit dl rm
cal	67560	0755	edit dl rm
captoinfo	87360	0755	edit dl rm
cat	38360	0755	edit dl rm
catchsegv	3283	0755	edit dl rm
cc	1266576	0755	edit dl rm
chcon	72024	0755	edit dl rm
chgrp	67864	0755	edit dl rm
chmod	63688	0755	edit dl rm
chown	71976	0755	edit dl rm
chrt	38080	0755	edit dl rm
cksum	38288	0755	edit dl rm
cldetect	10593	0755	edit dl rm
clear	12840	0755	edit dl rm
cmp	106248	0755	edit dl rm
col	29704	0755	edit dl rm
colcrt	16872	0755	edit dl rm
colrm	25480	0755	edit dl rm
column	50656	0755	edit dl rm
comm	42560	0755	edit dl rm
compare	12136	0755	edit dl rm
composite	12120	0755	edit dl rm
conjure	12120	0755	edit dl rm
convert	12120	0755	edit dl rm
cp	151568	0755	edit dl rm
cpan	8370	0755	edit dl rm
cpp	1266552	0755	edit dl rm
crontab	1524	0755	edit dl rm
crontab.cagefs	55456	0755	edit dl rm
csplit	54968	0755	edit dl rm
curl	235600	0755	edit dl rm
cut	50704	0755	edit dl rm
date	108496	0755	edit dl rm
dbiprof	6206	0755	edit dl rm
dd	79840	0755	edit dl rm
delv	43480	0755	edit dl rm
df	93272	0755	edit dl rm
diff	274440	0755	edit dl rm
diff3	131688	0755	edit dl rm
dig	166072	0755	edit dl rm
dir	143256	0755	edit dl rm
dircolors	50744	0755	edit dl rm
dirname	34160	0755	edit dl rm
display	12128	0755	edit dl rm
dnstap-read	20920	0755	edit dl rm
du	109568	0755	edit dl rm
easy_install-3	-	0	edit dl rm
echo	38248	0755	edit dl rm
egrep	28	0755	edit dl rm
enc2xs	41958	0755	edit dl rm
enchant	21584	0755	edit dl rm
enchant-lsmod	13408	0755	edit dl rm
env	42344	0755	edit dl rm
eps2eps	639	0755	edit dl rm
eqn	237728	0755	edit dl rm
ex	1180352	0755	edit dl rm
expand	42592	0755	edit dl rm
expr	50760	0755	edit dl rm
factor	88032	0755	edit dl rm
false	34120	0755	edit dl rm
fc-cache	132	0755	edit dl rm
fc-cache-64	20840	0755	edit dl rm
fc-cat	16744	0755	edit dl rm
fc-conflist	12544	0755	edit dl rm
fc-list	12544	0755	edit dl rm
fc-match	16648	0755	edit dl rm
fc-pattern	12552	0755	edit dl rm
fc-query	12536	0755	edit dl rm
fc-scan	12552	0755	edit dl rm
fc-validate	16648	0755	edit dl rm
fgrep	28	0755	edit dl rm
file	25280	0755	edit dl rm
find	228632	0755	edit dl rm
flex	438728	0755	edit dl rm
flex++	438728	0755	edit dl rm
flock	33992	0755	edit dl rm
fmt	46584	0755	edit dl rm
fold	42408	0755	edit dl rm
free	21288	0755	edit dl rm
freetype-config	4416	0755	edit dl rm
funzip	37504	0755	edit dl rm
g++	1266616	0755	edit dl rm
gawk	685848	0755	edit dl rm
gcc	1266576	0755	edit dl rm
gcc-ar	37536	0755	edit dl rm
gcc-nm	37536	0755	edit dl rm
gcc-ranlib	37536	0755	edit dl rm
gcov	1377408	0755	edit dl rm
gcov-dump	584664	0755	edit dl rm
gcov-tool	622360	0755	edit dl rm
gencat	25432	0755	edit dl rm
geoiplookup	22416	0755	edit dl rm
geoiplookup6	22168	0755	edit dl rm
geqn	237728	0755	edit dl rm
GET	16217	0755	edit dl rm
getconf	33240	0755	edit dl rm
getent	33920	0755	edit dl rm
getopt	21024	0755	edit dl rm
ghostscript	12648	0755	edit dl rm
git	3845928	0755	edit dl rm
git-receive-pack	3845928	0755	edit dl rm
git-shell	2236688	0755	edit dl rm
git-upload-archive	3845928	0755	edit dl rm
git-upload-pack	3845928	0755	edit dl rm
gm	8024	0755	edit dl rm
gmake	240968	0755	edit dl rm
gneqn	908	0755	edit dl rm
gnroff	3312	0755	edit dl rm
gpg	1090344	0755	edit dl rm
gpg-agent	429360	0755	edit dl rm
gpg-error	34976	0755	edit dl rm
gpg-zip	3525	0755	edit dl rm
gpgsplit	89112	0755	edit dl rm
gpgv	462344	0755	edit dl rm
gpic	300896	0755	edit dl rm
gprof	105832	0755	edit dl rm
grep	198280	0755	edit dl rm
groff	127920	0755	edit dl rm
grops	195728	0755	edit dl rm
grotty	145304	0755	edit dl rm
groups	38288	0755	edit dl rm
gs	12648	0755	edit dl rm
gsnd	277	0755	edit dl rm
gsoelim	43576	0755	edit dl rm
gtar	459768	0755	edit dl rm
gtbl	158320	0755	edit dl rm
gtroff	824344	0755	edit dl rm
gunzip	2345	0755	edit dl rm
gzexe	6375	0755	edit dl rm
gzip	96944	0755	edit dl rm
h2ph	29382	0755	edit dl rm
h2xs	60866	0755	edit dl rm
head	46592	0755	edit dl rm
hexdump	58888	0755	edit dl rm
host	145704	0755	edit dl rm
hostid	34136	0755	edit dl rm
hostname	21664	0755	edit dl rm
hunspell	148168	0755	edit dl rm
iconv	62904	0755	edit dl rm
id	46528	0755	edit dl rm
identify	12128	0755	edit dl rm
idn	40352	0755	edit dl rm
ifnames	4128	0755	edit dl rm
import	12120	0755	edit dl rm
infocmp	62512	0755	edit dl rm
infotocap	87360	0755	edit dl rm
install	159912	0755	edit dl rm
instmodsh	4194	0755	edit dl rm
ionice	29680	0755	edit dl rm
ipcrm	29688	0755	edit dl rm
ipcs	54680	0755	edit dl rm
isosize	25480	0755	edit dl rm
ispell	988	0755	edit dl rm
join	54984	0755	edit dl rm
kill	38176	0755	edit dl rm
ld	1789080	0755	edit dl rm
ld.bfd	1789080	0755	edit dl rm
ldd	5441	0755	edit dl rm
less	177928	0755	edit dl rm
lessecho	12696	0755	edit dl rm
lesskey	22520	0755	edit dl rm
lesspipe.sh	3143	0755	edit dl rm
lex	438728	0755	edit dl rm
libnetcfg	15775	0755	edit dl rm
libtool	367724	0755	edit dl rm
libtoolize	129197	0755	edit dl rm
link	34136	0755	edit dl rm
ln	72192	0755	edit dl rm
locale	57800	0755	edit dl rm
localedef	314848	0755	edit dl rm
logger	51184	0755	edit dl rm
login	41944	0755	edit dl rm
logname	34144	0755	edit dl rm
look	16856	0755	edit dl rm
ls	143248	0755	edit dl rm
m4	190016	0755	edit dl rm
Magick-config	1460	0755	edit dl rm
MagickCore-config	1596	0755	edit dl rm
MagickWand-config	1597	0755	edit dl rm
Mail	418704	0755	edit dl rm
mail	418704	0755	edit dl rm
mailx	418704	0755	edit dl rm
make	240968	0755	edit dl rm
make-dummy-cert	610	0755	edit dl rm
mariadb	5586328	0755	edit dl rm
mariadb-access	111961	0755	edit dl rm
mariadb-admin	5111488	0755	edit dl rm
mariadb-binlog	5413112	0755	edit dl rm
mariadb-check	5104544	0755	edit dl rm
mariadb-conv	4800544	0755	edit dl rm
mariadb-convert-table-format	4221	0755	edit dl rm
mariadb-dump	5200936	0755	edit dl rm
mariadb-dumpslow	8242	0755	edit dl rm
mariadb-embedded	25435072	0755	edit dl rm
mariadb-find-rows	3290	0755	edit dl rm
mariadb-hotcopy	35359	0755	edit dl rm
mariadb-import	5095200	0755	edit dl rm
mariadb-plugin	4779408	0755	edit dl rm
mariadb-secure-installation	13799	0755	edit dl rm
mariadb-setpermission	17977	0755	edit dl rm
mariadb-show	5093680	0755	edit dl rm
mariadb-slap	5113168	0755	edit dl rm
mariadb-tzinfo-to-sql	4778792	0755	edit dl rm
mariadb-waitpid	4766200	0755	edit dl rm
mc	1360320	0755	edit dl rm
mcdiff	1360320	0755	edit dl rm
mcedit	1360320	0755	edit dl rm
mcookie	34064	0755	edit dl rm
mcview	1360320	0755	edit dl rm
md5sum	46632	0755	edit dl rm
mesg	16752	0755	edit dl rm
mkdir	84680	0755	edit dl rm
mkfifo	68056	0755	edit dl rm
mknod	72160	0755	edit dl rm
mktemp	46760	0755	edit dl rm
mogrify	12120	0755	edit dl rm
montage	12120	0755	edit dl rm
more	46016	0755	edit dl rm
msql2mysql	1446	0755	edit dl rm
mv	147408	0755	edit dl rm
mysql	5586328	0755	edit dl rm
mysqlaccess	111961	0755	edit dl rm
mysqladmin	5111488	0755	edit dl rm
mysqlbinlog	5413112	0755	edit dl rm
mysqlcheck	5104544	0755	edit dl rm
mysqldump	5200936	0755	edit dl rm
mysqlimport	5095200	0755	edit dl rm
mysqlshow	5093680	0755	edit dl rm
mysql_config	4623	0755	edit dl rm
mysql_find_rows	3290	0755	edit dl rm
mysql_waitpid	4766200	0755	edit dl rm
mytop	73757	0755	edit dl rm
my_print_defaults	4770672	0755	edit dl rm
namei	33896	0755	edit dl rm
nano	253888	0755	edit dl rm
neqn	908	0755	edit dl rm
net-snmp-create-v3-user	3223	0755	edit dl rm
nice	38224	0755	edit dl rm
nl	46648	0755	edit dl rm
nm	51584	0755	edit dl rm
nohup	38312	0755	edit dl rm
nproc	38304	0755	edit dl rm
nroff	3312	0755	edit dl rm
nslookup	149768	0755	edit dl rm
nsupdate	74808	0755	edit dl rm
numfmt	67216	0755	edit dl rm
objcopy	245832	0755	edit dl rm
objdump	429832	0755	edit dl rm
od	75576	0755	edit dl rm
openssl	763856	0755	edit dl rm
pango-list	12160	0755	edit dl rm
pango-view	58816	0755	edit dl rm
passwd	1284	0755	edit dl rm
paste	38280	0755	edit dl rm
patch	211416	0755	edit dl rm
pathchk	38224	0755	edit dl rm
pdf2dsc	698	0755	edit dl rm
pdf2ps	909	0755	edit dl rm
perl	12728	0755	edit dl rm
perl5.26.3	12728	0755	edit dl rm
perlbug	45458	0755	edit dl rm
perldoc	118	0755	edit dl rm
perlivp	10813	0755	edit dl rm
perlml	6768	0755	edit dl rm
perlthanks	45458	0755	edit dl rm
pgrep	29536	0755	edit dl rm
php	937	0755	edit dl rm
pic	300896	0755	edit dl rm
piconv	8271	0755	edit dl rm
pinentry	2404	0755	edit dl rm
pinentry-curses	79760	0755	edit dl rm
ping	67712	0755	edit dl rm
pinky	42456	0755	edit dl rm
pip-3	-	0	edit dl rm
pip3	-	0	edit dl rm
pkg-config	41000	0755	edit dl rm
pkgconf	41000	0755	edit dl rm
pkill	29536	0755	edit dl rm
pl2pm	4533	0755	edit dl rm
pmap	33568	0755	edit dl rm
pod2html	4134	0755	edit dl rm
pod2man	15034	0755	edit dl rm
pod2text	10803	0755	edit dl rm
pod2usage	3948	0755	edit dl rm
podchecker	3658	0755	edit dl rm
podselect	2527	0755	edit dl rm
post-grohtml	244456	0755	edit dl rm
pr	84120	0755	edit dl rm
pre-grohtml	133688	0755	edit dl rm
precat	5656	0755	edit dl rm
preunzip	5656	0755	edit dl rm
prezip	5656	0755	edit dl rm
prezip-bin	12264	0755	edit dl rm
printenv	34120	0755	edit dl rm
printf	54848	0755	edit dl rm
prove	13562	0755	edit dl rm
ps	137984	0755	edit dl rm
ps2ascii	631	0755	edit dl rm
ps2epsi	2752	0755	edit dl rm
ps2pdf	272	0755	edit dl rm
ps2pdf12	215	0755	edit dl rm
ps2pdf13	215	0755	edit dl rm
ps2pdf14	215	0755	edit dl rm
ps2pdfwr	1097	0755	edit dl rm
ps2ps	647	0755	edit dl rm
ps2ps2	669	0755	edit dl rm
ptx	79864	0755	edit dl rm
pwd	38320	0755	edit dl rm
pwdx	12984	0755	edit dl rm
pydoc-3	-	0	edit dl rm
pydoc3	-	0	edit dl rm
python2	8032	0755	edit dl rm
python2.7	8032	0755	edit dl rm
python3	11872	0755	edit dl rm
python3.6	11872	0755	edit dl rm
python3.6m	11872	0755	edit dl rm
pyvenv-3	-	0	edit dl rm
ranlib	63456	0755	edit dl rm
raw	16896	0755	edit dl rm
readelf	639528	0755	edit dl rm
readlink	46984	0755	edit dl rm
realpath	51144	0755	edit dl rm
recode	48160	0755	edit dl rm
rename	16896	0755	edit dl rm
renew-dummy-cert	725	0755	edit dl rm
renice	16856	0755	edit dl rm
replace	4748656	0755	edit dl rm
reset	25352	0755	edit dl rm
rev	12760	0755	edit dl rm
rm	72064	0755	edit dl rm
rmdir	46552	0755	edit dl rm
rnano	253888	0755	edit dl rm
run-with-aspell	85	0755	edit dl rm
runcon	38264	0755	edit dl rm
rvi	1180352	0755	edit dl rm
rview	1180352	0755	edit dl rm
rvim	3067744	0755	edit dl rm
scalar	2290912	0755	edit dl rm
scl	37752	0755	edit dl rm
scl_enabled	258	0755	edit dl rm
scl_source	1863	0755	edit dl rm
scp	105304	0755	edit dl rm
script	37680	0755	edit dl rm
sdiff	107856	0755	edit dl rm
sed	118248	0755	edit dl rm
selectorctl	7812	0755	edit dl rm
seq	54728	0755	edit dl rm
setsid	16768	0755	edit dl rm
setterm	46208	0755	edit dl rm
sftp	163576	0755	edit dl rm
sh	1154680	0755	edit dl rm
sha1sum	46640	0755	edit dl rm
sha224sum	46672	0755	edit dl rm
sha256sum	46680	0755	edit dl rm
sha384sum	46688	0755	edit dl rm
sha512sum	46680	0755	edit dl rm
shred	63336	0755	edit dl rm
shuf	59488	0755	edit dl rm
size	34048	0755	edit dl rm
skill	29488	0755	edit dl rm
slabtop	21344	0755	edit dl rm
sleep	38288	0755	edit dl rm
snice	29488	0755	edit dl rm
snmpconf	26051	0755	edit dl rm
soelim	43576	0755	edit dl rm
sort	126432	0755	edit dl rm
spell	122	0755	edit dl rm
splain	19150	0755	edit dl rm
split	59440	0755	edit dl rm
sprof	29360	0755	edit dl rm
sqlite3	1346512	0755	edit dl rm
ssh	775648	0755	edit dl rm
ssh-add	354416	0755	edit dl rm
ssh-agent	333400	0755	edit dl rm
ssh-copy-id	10694	0755	edit dl rm
ssh-keygen	437424	0755	edit dl rm
ssh-keyscan	438800	0755	edit dl rm
stat	88232	0755	edit dl rm
stdbuf	50688	0755	edit dl rm
strace	2029832	0755	edit dl rm
stream	12112	0755	edit dl rm
strings	38328	0755	edit dl rm
strip	245856	0755	edit dl rm
stty	79472	0755	edit dl rm
sum	46624	0755	edit dl rm
sync	38256	0755	edit dl rm
tabs	16952	0755	edit dl rm
tac	42488	0755	edit dl rm
tail	75912	0755	edit dl rm
tar	459768	0755	edit dl rm
taskset	38152	0755	edit dl rm
tbl	158320	0755	edit dl rm
tclsh	9256	0755	edit dl rm
tclsh8.6	9256	0755	edit dl rm
tee	42472	0755	edit dl rm
test	54848	0755	edit dl rm
tic	87360	0755	edit dl rm
timeout	42864	0755	edit dl rm
tload	17160	0755	edit dl rm
tmpwatch	36320	0755	edit dl rm
toe	16848	0755	edit dl rm
top	124616	0755	edit dl rm
touch	96192	0755	edit dl rm
tput	25392	0755	edit dl rm
tr	50816	0755	edit dl rm
troff	824344	0755	edit dl rm
true	34128	0755	edit dl rm
truncate	42352	0755	edit dl rm
tset	25352	0755	edit dl rm
tsort	42488	0755	edit dl rm
tty	34112	0755	edit dl rm
tzselect	15370	0755	edit dl rm
uapi	1280	0755	edit dl rm
ul	21080	0755	edit dl rm
uname	38224	0755	edit dl rm
unexpand	46704	0755	edit dl rm
uniq	50832	0755	edit dl rm
unlink	34144	0755	edit dl rm
unversioned-python	-	0	edit dl rm
unzip	206728	0755	edit dl rm
unzipsfx	103912	0755	edit dl rm
uptime	12888	0755	edit dl rm
users	38288	0755	edit dl rm
utmpdump	29352	0755	edit dl rm
vdir	143256	0755	edit dl rm
vi	1180352	0755	edit dl rm
view	1180352	0755	edit dl rm
vim	3067744	0755	edit dl rm
vimdiff	3067744	0755	edit dl rm
vimtutor	2121	0755	edit dl rm
vmstat	37672	0755	edit dl rm
Wand-config	1455	0755	edit dl rm
watch	29888	0755	edit dl rm
wc	50832	0755	edit dl rm
wget	533928	0755	edit dl rm
whereis	29976	0755	edit dl rm
which	30088	0755	edit dl rm
who	54880	0755	edit dl rm
whoami	34136	0755	edit dl rm
word-list-compress	12280	0755	edit dl rm
x86_64-redhat-linux-c++	1266616	0755	edit dl rm
x86_64-redhat-linux-g++	1266616	0755	edit dl rm
x86_64-redhat-linux-gcc	1266576	0755	edit dl rm
x86_64-redhat-linux-gcc-8	1266576	0755	edit dl rm
xargs	75888	0755	edit dl rm
xmlcatalog	20864	0755	edit dl rm
xmllint	75128	0755	edit dl rm
xmlwf	37848	0755	edit dl rm
xsltproc	29152	0755	edit dl rm
xsubpp	5080	0755	edit dl rm
xxd	21032	0755	edit dl rm
yes	34168	0755	edit dl rm
zcat	1983	0755	edit dl rm
zcmp	1677	0755	edit dl rm
zdiff	5879	0755	edit dl rm
zegrep	29	0755	edit dl rm
zfgrep	29	0755	edit dl rm
zforce	2080	0755	edit dl rm
zgrep	7582	0755	edit dl rm
zip	234496	0755	edit dl rm
zipcloak	105376	0755	edit dl rm
zipgrep	2953	0755	edit dl rm
zipinfo	206728	0755	edit dl rm
zipnote	100104	0755	edit dl rm
zipsplit	100104	0755	edit dl rm
zless	2205	0755	edit dl rm
zmore	1841	0755	edit dl rm
znew	4552	0755	edit dl rm
zsoelim	43576	0755	edit dl rm
[	54864	0755	edit dl rm

Edit: /usr/bin/splain (19150B)

#!/usr/bin/perl
    eval 'exec /usr/bin/perl -S $0 ${1+"$@"}'
	if $running_under_some_shell;

BEGIN { pop @INC if $INC[-1] eq '.' }

=head1 NAME

diagnostics, splain - produce verbose warning diagnostics

=head1 SYNOPSIS

Using the C<diagnostics> pragma:

use diagnostics;
    use diagnostics -verbose;

enable  diagnostics;
    disable diagnostics;

Using the C<splain> standalone filter program:

perl program 2>diag.out
    splain [-v] [-p] diag.out

Using diagnostics to get stack traces from a misbehaving script:

perl -Mdiagnostics=-traceonly my_script.pl

=head1 DESCRIPTION

=head2 The C<diagnostics> Pragma

This module extends the terse diagnostics normally emitted by both the
perl compiler and the perl interpreter (from running perl with a -w 
switch or C<use warnings>), augmenting them with the more
explicative and endearing descriptions found in L<perldiag>.  Like the
other pragmata, it affects the compilation phase of your program rather
than merely the execution phase.

To use in your program as a pragma, merely invoke

use diagnostics;

at the start (or near the start) of your program.  (Note 
that this I<does> enable perl's B<-w> flag.)  Your whole
compilation will then be subject(ed :-) to the enhanced diagnostics.
These still go out B<STDERR>.

Due to the interaction between runtime and compiletime issues,
and because it's probably not a very good idea anyway,
you may not use C<no diagnostics> to turn them off at compiletime.
However, you may control their behaviour at runtime using the 
disable() and enable() methods to turn them off and on respectively.

The B<-verbose> flag first prints out the L<perldiag> introduction before
any other diagnostics.  The $diagnostics::PRETTY variable can generate nicer
escape sequences for pagers.

Warnings dispatched from perl itself (or more accurately, those that match
descriptions found in L<perldiag>) are only displayed once (no duplicate
descriptions).  User code generated warnings a la warn() are unaffected,
allowing duplicate user messages to be displayed.

This module also adds a stack trace to the error message when perl dies.
This is useful for pinpointing what
caused the death.  The B<-traceonly> (or
just B<-t>) flag turns off the explanations of warning messages leaving just
the stack traces.  So if your script is dieing, run it again with

perl -Mdiagnostics=-traceonly my_bad_script

to see the call stack at the time of death.  By supplying the B<-warntrace>
(or just B<-w>) flag, any warnings emitted will also come with a stack
trace.

=head2 The I<splain> Program

While apparently a whole nuther program, I<splain> is actually nothing
more than a link to the (executable) F<diagnostics.pm> module, as well as
a link to the F<diagnostics.pod> documentation.  The B<-v> flag is like
the C<use diagnostics -verbose> directive.
The B<-p> flag is like the
$diagnostics::PRETTY variable.  Since you're post-processing with 
I<splain>, there's no sense in being able to enable() or disable() processing.

Output from I<splain> is directed to B<STDOUT>, unlike the pragma.

=head1 EXAMPLES

The following file is certain to trigger a few errors at both
runtime and compiletime:

use diagnostics;
    print NOWHERE "nothing\n";
    print STDERR "\n\tThis message should be unadorned.\n";
    warn "\tThis is a user warning";
    print "\nDIAGNOSTIC TESTER: Please enter a <CR> here: ";
    my $a, $b = scalar <STDIN>;
    print "\n";
    print $x/$y;

If you prefer to run your program first and look at its problem
afterwards, do this:

perl -w test.pl 2>test.out
    ./splain < test.out

Note that this is not in general possible in shells of more dubious heritage, 
as the theoretical

(perl -w test.pl >/dev/tty) >& test.out
    ./splain < test.out

Because you just moved the existing B<stdout> to somewhere else.

If you don't want to modify your source code, but still have on-the-fly
warnings, do this:

exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&-

Nifty, eh?

If you want to control warnings on the fly, do something like this.
Make sure you do the C<use> first, or you won't be able to get
at the enable() or disable() methods.

use diagnostics; # checks entire compilation phase 
	print "\ntime for 1st bogus diags: SQUAWKINGS\n";
	print BOGUS1 'nada';
	print "done with 1st bogus\n";

disable diagnostics; # only turns off runtime warnings
	print "\ntime for 2nd bogus: (squelched)\n";
	print BOGUS2 'nada';
	print "done with 2nd bogus\n";

enable diagnostics; # turns back on runtime warnings
	print "\ntime for 3rd bogus: SQUAWKINGS\n";
	print BOGUS3 'nada';
	print "done with 3rd bogus\n";

disable diagnostics;
	print "\ntime for 4th bogus: (squelched)\n";
	print BOGUS4 'nada';
	print "done with 4th bogus\n";

=head1 INTERNALS

Diagnostic messages derive from the F<perldiag.pod> file when available at
runtime.  Otherwise, they may be embedded in the file itself when the
splain package is built.   See the F<Makefile> for details.

If an extant $SIG{__WARN__} handler is discovered, it will continue
to be honored, but only after the diagnostics::splainthis() function 
(the module's $SIG{__WARN__} interceptor) has had its way with your
warnings.

There is a $diagnostics::DEBUG variable you may set if you're desperately
curious what sorts of things are being intercepted.

BEGIN { $diagnostics::DEBUG = 1 }

=head1 BUGS

Not being able to say "no diagnostics" is annoying, but may not be
insurmountable.

The C<-pretty> directive is called too late to affect matters.
You have to do this instead, and I<before> you load the module.

BEGIN { $diagnostics::PRETTY = 1 }

I could start up faster by delaying compilation until it should be
needed, but this gets a "panic: top_level" when using the pragma form
in Perl 5.001e.

While it's true that this documentation is somewhat subserious, if you use
a program named I<splain>, you should expect a bit of whimsy.

=head1 AUTHOR

Tom Christiansen <F<tchrist@mox.perl.com>>, 25 June 1995.

=cut

use strict;
use 5.009001;
use Carp;
$Carp::Internal{__PACKAGE__.""}++;

our $VERSION = '1.36';
our $DEBUG;
our $VERBOSE;
our $PRETTY;
our $TRACEONLY = 0;
our $WARNTRACE = 0;

use Config;
use Text::Tabs 'expand';
my $privlib = $Config{privlibexp};
if ($^O eq 'VMS') {
    require VMS::Filespec;
    $privlib = VMS::Filespec::unixify($privlib);
}
my @trypod = (
	   "$privlib/pod/perldiag.pod",
	   "$privlib/pods/perldiag.pod",
	  );
# handy for development testing of new warnings etc
unshift @trypod, "./pod/perldiag.pod" if -e "pod/perldiag.pod";
(my $PODFILE) = ((grep { -e } @trypod), $trypod[$#trypod])[0];

$DEBUG ||= 0;

local $| = 1;
local $_;
local $.;

my $standalone;
my(%HTML_2_Troff, %HTML_2_Latin_1, %HTML_2_ASCII_7);

CONFIG: {
    our $opt_p = our $opt_d = our $opt_v = our $opt_f = '';

unless (caller) {
	$standalone++;
	require Getopt::Std;
	Getopt::Std::getopts('pdvf:')
	    or die "Usage: $0 [-v] [-p] [-f splainpod]";
	$PODFILE = $opt_f if $opt_f;
	$DEBUG = 2 if $opt_d;
	$VERBOSE = $opt_v;
	$PRETTY = $opt_p;
    }

if (open(POD_DIAG, '<', $PODFILE)) {
	warn "Happy happy podfile from real $PODFILE\n" if $DEBUG;
	last CONFIG;
    }

if (caller) {
	INCPATH: {
	    for my $file ( (map { "$_/".__PACKAGE__.".pm" } @INC), $0) {
		warn "Checking $file\n" if $DEBUG;
		if (open(POD_DIAG, '<', $file)) {
		    while (<POD_DIAG>) {
			next unless
			    /^__END__\s*# wish diag dbase were more accessible/;
			print STDERR "podfile is $file\n" if $DEBUG;
			last INCPATH;
		    }
		}
	    } 
	}
    } else { 
	print STDERR "podfile is <DATA>\n" if $DEBUG;
	*POD_DIAG = *main::DATA;
    }
}
if (eof(POD_DIAG)) { 
    die "couldn't find diagnostic data in $PODFILE @INC $0";
}

%HTML_2_Troff = (
    'amp'	=>	'&',	#   ampersand
    'lt'	=>	'<',	#   left chevron, less-than
    'gt'	=>	'>',	#   right chevron, greater-than
    'quot'	=>	'"',	#   double quote

"Aacute"	=>	"A\\*'",	#   capital A, acute accent
    # etc

);

%HTML_2_Latin_1 = (
    'amp'	=>	'&',	#   ampersand
    'lt'	=>	'<',	#   left chevron, less-than
    'gt'	=>	'>',	#   right chevron, greater-than
    'quot'	=>	'"',	#   double quote

"Aacute"	=>	"\xC1"	#   capital A, acute accent

# etc
);

%HTML_2_ASCII_7 = (
    'amp'	=>	'&',	#   ampersand
    'lt'	=>	'<',	#   left chevron, less-than
    'gt'	=>	'>',	#   right chevron, greater-than
    'quot'	=>	'"',	#   double quote

"Aacute"	=>	"A"	#   capital A, acute accent
    # etc
);

our %HTML_Escapes;
*HTML_Escapes = do {
    if ($standalone) {
	$PRETTY ? \%HTML_2_Latin_1 : \%HTML_2_ASCII_7; 
    } else {
	\%HTML_2_Latin_1; 
    }
};

*THITHER = $standalone ? *STDOUT : *STDERR;

my %transfmt = (); 
my $transmo = <<EOFUNC;
sub transmo {
    #local \$^W = 0;  # recursive warnings we do NOT need!
EOFUNC

my %msg;
my $over_level = 0;     # We look only at =item lines at the first =over level
{
    print STDERR "FINISHING COMPILATION for $_\n" if $DEBUG;
    local $/ = '';
    local $_;
    my $header;
    my @headers;
    my $for_item;
    my $seen_body;
    while (<POD_DIAG>) {

sub _split_pod_link {
	    $_[0] =~ m'(?:([^|]*)\|)?([^/]*)(?:/("?)(.*)\3)?'s;
	    ($1,$2,$4);
	}

unescape();
	if ($PRETTY) {
	    sub noop   { return $_[0] }  # spensive for a noop
	    sub bold   { my $str =$_[0];  $str =~ s/(.)/$1\b$1/g; return $str; } 
	    sub italic { my $str = $_[0]; $str =~ s/(.)/_\b$1/g;  return $str; } 
	    s/C<<< (.*?) >>>|C<< (.*?) >>|[BC]<(.*?)>/bold($+)/ges;
	    s/[IF]<(.*?)>/italic($1)/ges;
	    s/L<(.*?)>/
	       my($text,$page,$sect) = _split_pod_link($1);
	       defined $text
	        ? $text
	        : defined $sect
	           ? italic($sect) . ' in ' . italic($page)
	           : italic($page)
	     /ges;
	     s/S<(.*?)>/
               $1
             /ges;
	} else {
	    s/C<<< (.*?) >>>|C<< (.*?) >>|[BC]<(.*?)>/$+/gs;
	    s/[IF]<(.*?)>/$1/gs;
	    s/L<(.*?)>/
	       my($text,$page,$sect) = _split_pod_link($1);
	       defined $text
	        ? $text
	        : defined $sect
	           ? qq '"$sect" in $page'
	           : $page
	     /ges;
	    s/S<(.*?)>/
               $1
             /ges;
	} 
	unless (/^=/) {
	    if (defined $header) { 
		if ( $header eq 'DESCRIPTION' && 
		    (   /Optional warnings are enabled/ 
		     || /Some of these messages are generic./
		    ) )
		{
		    next;
		}
		$_ = expand $_;
		s/^/    /gm;
		$msg{$header} .= $_;
		for my $h(@headers) { $msg{$h} .= $_ }
		++$seen_body;
	 	undef $for_item;	
	    }
	    next;
	}

# If we have not come across the body of the description yet, then
	# the previous header needs to share the same description.
	if ($seen_body) {
	    @headers = ();
	}
	else {
	    push @headers, $header if defined $header;
	}

if ( ! s/=item (.*?)\s*\z//s || $over_level != 1) {

if ( s/=head1\sDESCRIPTION//) {
		$msg{$header = 'DESCRIPTION'} = '';
		undef $for_item;
	    }
	    elsif( s/^=for\s+diagnostics\s*\n(.*?)\s*\z// ) {
		$for_item = $1;
	    }
	    elsif( /^=over\b/ ) {
                $over_level++;
            }
	    elsif( /^=back\b/ ) { # Stop processing body here
                $over_level--;
                if ($over_level == 0) {
                    undef $header;
                    undef $for_item;
                    $seen_body = 0;
                    next;
                }
	    }
	    next;
	}

if( $for_item ) { $header = $for_item; undef $for_item } 
	else {
	    $header = $1;

$header =~ s/\n/ /gs; # Allow multi-line headers
	}

# strip formatting directives from =item line
	$header =~ s/[A-Z]<(.*?)>/$1/g;

# Since we strip "(\.\s*)\n" when we search a warning, strip it here as well
	$header =~ s/(\.\s*)?$//;

my @toks = split( /(%l?[dxX]|%[ucp]|%(?:\.\d+)?[fs])/, $header );
	if (@toks > 1) {
            my $conlen = 0;
            for my $i (0..$#toks){
                if( $i % 2 ){
                    if(      $toks[$i] eq '%c' ){
                        $toks[$i] = '.';
                    } elsif( $toks[$i] =~ /^%(?:d|u)$/ ){
                        $toks[$i] = '\d+';
                    } elsif( $toks[$i] =~ '^%(?:s|.*f)$' ){
                        $toks[$i] = $i == $#toks ? '.*' : '.*?';
                    } elsif( $toks[$i] =~ '%.(\d+)s' ){
                        $toks[$i] = ".{$1}";
                    } elsif( $toks[$i] =~ '^%l*([pxX])$' ){
                        $toks[$i] = $1 eq 'X' ? '[\dA-F]+' : '[\da-f]+';
                    }
                } elsif( length( $toks[$i] ) ){
                    $toks[$i] = quotemeta $toks[$i];
                    $conlen += length( $toks[$i] );
                }
            }  
            my $lhs = join( '', @toks );
            $lhs =~ s/(\\\s)+/\\s+/g; # Replace lit space with multi-space match
	    $transfmt{$header}{pat} =
              "    s^\\s*$lhs\\s*\Q$header\Es\n\t&& return 1;\n";
            $transfmt{$header}{len} = $conlen;
	} else {
            my $lhs = "\Q$header\E";
            $lhs =~ s/(\\\s)+/\\s+/g; # Replace lit space with multi-space match
            $transfmt{$header}{pat} =
	      "    s^\\s*$lhs\\s*\Q$header\E\n\t && return 1;\n";
            $transfmt{$header}{len} = length( $header );
	}

print STDERR __PACKAGE__.": Duplicate entry: \"$header\"\n"
	    if $msg{$header};

$msg{$header} = '';
	$seen_body = 0;
    }

close POD_DIAG unless *main::DATA eq *POD_DIAG;

die "No diagnostics?" unless %msg;

# Apply patterns in order of decreasing sum of lengths of fixed parts
    # Seems the best way of hitting the right one.
    for my $hdr ( sort { $transfmt{$b}{len} <=> $transfmt{$a}{len} }
                  keys %transfmt ){
        $transmo .= $transfmt{$hdr}{pat};
    }
    $transmo .= "    return 0;\n}\n";
    print STDERR $transmo if $DEBUG;
    eval $transmo;
    die $@ if $@;
}

if ($standalone) {
    if (!@ARGV and -t STDIN) { print STDERR "$0: Reading from STDIN\n" } 
    while (defined (my $error = <>)) {
	splainthis($error) || print THITHER $error;
    } 
    exit;
}

my $olddie;
my $oldwarn;

sub import {
    shift;
    $^W = 1; # yup, clobbered the global variable; 
	     # tough, if you want diags, you want diags.
    return if defined $SIG{__WARN__} && ($SIG{__WARN__} eq \&warn_trap);

for (@_) {

/^-d(ebug)?$/ 	   	&& do {
				    $DEBUG++;
				    next;
				   };

/^-v(erbose)?$/ 	&& do {
				    $VERBOSE++;
				    next;
				   };

/^-p(retty)?$/ 		&& do {
				    print STDERR "$0: I'm afraid it's too late for prettiness.\n";
				    $PRETTY++;
				    next;
			       };
	# matches trace and traceonly for legacy doc mixup reasons
	/^-t(race(only)?)?$/	&& do {
				    $TRACEONLY++;
				    next;
			       };
	/^-w(arntrace)?$/ 	&& do {
				    $WARNTRACE++;
				    next;
			       };

warn "Unknown flag: $_";
    }

$oldwarn = $SIG{__WARN__};
    $olddie = $SIG{__DIE__};
    $SIG{__WARN__} = \&warn_trap;
    $SIG{__DIE__} = \&death_trap;
}

sub enable { &import }

sub disable {
    shift;
    return unless $SIG{__WARN__} eq \&warn_trap;
    $SIG{__WARN__} = $oldwarn || '';
    $SIG{__DIE__} = $olddie || '';
}

sub warn_trap {
    my $warning = $_[0];
    if (caller eq __PACKAGE__ or !splainthis($warning)) {
	if ($WARNTRACE) {
	    print STDERR Carp::longmess($warning);
	} else {
	    print STDERR $warning;
	}
    } 
    goto &$oldwarn if defined $oldwarn and $oldwarn and $oldwarn ne \&warn_trap;
};

sub death_trap {
    my $exception = $_[0];

# See if we are coming from anywhere within an eval. If so we don't
    # want to explain the exception because it's going to get caught.
    my $in_eval = 0;
    my $i = 0;
    while (my $caller = (caller($i++))[3]) {
      if ($caller eq '(eval)') {
	$in_eval = 1;
	last;
      }
    }

splainthis($exception) unless $in_eval;
    if (caller eq __PACKAGE__) {
	print STDERR "INTERNAL EXCEPTION: $exception";
    } 
    &$olddie if defined $olddie and $olddie and $olddie ne \&death_trap;

return if $in_eval;

# We don't want to unset these if we're coming from an eval because
    # then we've turned off diagnostics.

# Switch off our die/warn handlers so we don't wind up in our own
    # traps.
    $SIG{__DIE__} = $SIG{__WARN__} = '';

$exception =~ s/\n(?=.)/\n\t/gas;

die Carp::longmess("__diagnostics__")
	  =~ s/^__diagnostics__.*?line \d+\.?\n/
		  "Uncaught exception from user code:\n\t$exception"
	      /re;
	# up we go; where we stop, nobody knows, but i think we die now
	# but i'm deeply afraid of the &$olddie guy reraising and us getting
	# into an indirect recursion loop
};

my %exact_duplicate;
my %old_diag;
my $count;
my $wantspace;
sub splainthis {
  return 0 if $TRACEONLY;
  for (my $tmp = shift) {
    local $\;
    local $!;
    ### &finish_compilation unless %msg;
    s/(\.\s*)?\n+$//;
    my $orig = $_;
    # return unless defined;

# get rid of the where-are-we-in-input part
    s/, <.*?> (?:line|chunk).*$//;

# Discard 1st " at <file> line <no>" and all text beyond
    # but be aware of messages containing " at this-or-that"
    my $real = 0;
    my @secs = split( / at / );
    return unless @secs;
    $_ = $secs[0];
    for my $i ( 1..$#secs ){
        if( $secs[$i] =~ /.+? (?:line|chunk) \d+/ ){
            $real = 1;
            last;
        } else {
            $_ .= ' at ' . $secs[$i];
	}
    }

# remove parenthesis occurring at the end of some messages 
    s/^$(.*)$$/$1/;

if ($exact_duplicate{$orig}++) {
	return &transmo;
    } else {
	return 0 unless &transmo;
    }

my $short = shorten($orig);
    if ($old_diag{$_}) {
	autodescribe();
	print THITHER "$short (#$old_diag{$_})\n";
	$wantspace = 1;
    } elsif (!$msg{$_} && $orig =~ /\n./s) {
	# A multiline message, like "Attempt to reload /
	# Compilation failed"
	my $found;
	for (split /^/, $orig) {
	    splainthis($_) and $found = 1;
	}
	return $found;
    } else {
	autodescribe();
	$old_diag{$_} = ++$count;
	print THITHER "\n" if $wantspace;
	$wantspace = 0;
	print THITHER "$short (#$old_diag{$_})\n";
	if ($msg{$_}) {
	    print THITHER $msg{$_};
	} else {
	    if (0 and $standalone) { 
		print THITHER "    **** Error #$old_diag{$_} ",
			($real ? "is" : "appears to be"),
			" an unknown diagnostic message.\n\n";
	    }
	    return 0;
	} 
    }
    return 1;
  }
}

sub autodescribe {
    if ($VERBOSE and not $count) {
	print THITHER &{$PRETTY ? \&bold : \&noop}("DESCRIPTION OF DIAGNOSTICS"),
		"\n$msg{DESCRIPTION}\n";
    } 
}

sub unescape { 
    s {
            E<  
            ( [A-Za-z]+ )       
            >   
    } { 
         do {   
             exists $HTML_Escapes{$1}
                ? do { $HTML_Escapes{$1} }
                : do {
                    warn "Unknown escape: E<$1> in $_";
                    "E<$1>";
                } 
         } 
    }egx;
}

sub shorten {
    my $line = $_[0];
    if (length($line) > 79 and index($line, "\n") == -1) {
	my $space_place = rindex($line, ' ', 79);
	if ($space_place != -1) {
	    substr($line, $space_place, 1) = "\n\t";
	} 
    } 
    return $line;
}

1 unless $standalone;  # or it'll complain about itself
__END__ # wish diag dbase were more accessible

#!/usr/bin/perl eval 'exec /usr/bin/perl -S $0 ${1+"$@"}' if $running_under_some_shell; BEGIN { pop @INC if $INC[-1] eq '.' } =head1 NAME diagnostics, splain - produce verbose warning diagnostics =head1 SYNOPSIS Using the C pragma: use diagnostics; use diagnostics -verbose; enable diagnostics; disable diagnostics; Using the C standalone filter program: perl program 2>diag.out splain [-v] [-p] diag.out Using diagnostics to get stack traces from a misbehaving script: perl -Mdiagnostics=-traceonly my_script.pl =head1 DESCRIPTION =head2 The C Pragma This module extends the terse diagnostics normally emitted by both the perl compiler and the perl interpreter (from running perl with a -w switch or C), augmenting them with the more explicative and endearing descriptions found in L. Like the other pragmata, it affects the compilation phase of your program rather than merely the execution phase. To use in your program as a pragma, merely invoke use diagnostics; at the start (or near the start) of your program. (Note that this I enable perl's B<-w> flag.) Your whole compilation will then be subject(ed :-) to the enhanced diagnostics. These still go out B. Due to the interaction between runtime and compiletime issues, and because it's probably not a very good idea anyway, you may not use C to turn them off at compiletime. However, you may control their behaviour at runtime using the disable() and enable() methods to turn them off and on respectively. The B<-verbose> flag first prints out the L introduction before any other diagnostics. The $diagnostics::PRETTY variable can generate nicer escape sequences for pagers. Warnings dispatched from perl itself (or more accurately, those that match descriptions found in L) are only displayed once (no duplicate descriptions). User code generated warnings a la warn() are unaffected, allowing duplicate user messages to be displayed. This module also adds a stack trace to the error message when perl dies. This is useful for pinpointing what caused the death. The B<-traceonly> (or just B<-t>) flag turns off the explanations of warning messages leaving just the stack traces. So if your script is dieing, run it again with perl -Mdiagnostics=-traceonly my_bad_script to see the call stack at the time of death. By supplying the B<-warntrace> (or just B<-w>) flag, any warnings emitted will also come with a stack trace. =head2 The I Program While apparently a whole nuther program, I is actually nothing more than a link to the (executable) F module, as well as a link to the F documentation. The B<-v> flag is like the C directive. The B<-p> flag is like the $diagnostics::PRETTY variable. Since you're post-processing with I, there's no sense in being able to enable() or disable() processing. Output from I is directed to B, unlike the pragma. =head1 EXAMPLES The following file is certain to trigger a few errors at both runtime and compiletime: use diagnostics; print NOWHERE "nothing\n"; print STDERR "\n\tThis message should be unadorned.\n"; warn "\tThis is a user warning"; print "\nDIAGNOSTIC TESTER: Please enter a here: "; my $a, $b = scalar ; print "\n"; print $x/$y; If you prefer to run your program first and look at its problem afterwards, do this: perl -w test.pl 2>test.out ./splain < test.out Note that this is not in general possible in shells of more dubious heritage, as the theoretical (perl -w test.pl >/dev/tty) >& test.out ./splain < test.out Because you just moved the existing B to somewhere else. If you don't want to modify your source code, but still have on-the-fly warnings, do this: exec 3>&1; perl -w test.pl 2>&1 1>&3 3>&- | splain 1>&2 3>&- Nifty, eh? If you want to control warnings on the fly, do something like this. Make sure you do the C first, or you won't be able to get at the enable() or disable() methods. use diagnostics; # checks entire compilation phase print "\ntime for 1st bogus diags: SQUAWKINGS\n"; print BOGUS1 'nada'; print "done with 1st bogus\n"; disable diagnostics; # only turns off runtime warnings print "\ntime for 2nd bogus: (squelched)\n"; print BOGUS2 'nada'; print "done with 2nd bogus\n"; enable diagnostics; # turns back on runtime warnings print "\ntime for 3rd bogus: SQUAWKINGS\n"; print BOGUS3 'nada'; print "done with 3rd bogus\n"; disable diagnostics; print "\ntime for 4th bogus: (squelched)\n"; print BOGUS4 'nada'; print "done with 4th bogus\n"; =head1 INTERNALS Diagnostic messages derive from the F file when available at runtime. Otherwise, they may be embedded in the file itself when the splain package is built. See the F for details. If an extant $SIG{__WARN__} handler is discovered, it will continue to be honored, but only after the diagnostics::splainthis() function (the module's $SIG{__WARN__} interceptor) has had its way with your warnings. There is a $diagnostics::DEBUG variable you may set if you're desperately curious what sorts of things are being intercepted. BEGIN { $diagnostics::DEBUG = 1 } =head1 BUGS Not being able to say "no diagnostics" is annoying, but may not be insurmountable. The C<-pretty> directive is called too late to affect matters. You have to do this instead, and I you load the module. BEGIN { $diagnostics::PRETTY = 1 } I could start up faster by delaying compilation until it should be needed, but this gets a "panic: top_level" when using the pragma form in Perl 5.001e. While it's true that this documentation is somewhat subserious, if you use a program named I, you should expect a bit of whimsy. =head1 AUTHOR Tom Christiansen >, 25 June 1995. =cut use strict; use 5.009001; use Carp; $Carp::Internal{__PACKAGE__.""}++; our $VERSION = '1.36'; our $DEBUG; our $VERBOSE; our $PRETTY; our $TRACEONLY = 0; our $WARNTRACE = 0; use Config; use Text::Tabs 'expand'; my $privlib = $Config{privlibexp}; if ($^O eq 'VMS') { require VMS::Filespec; $privlib = VMS::Filespec::unixify($privlib); } my @trypod = ( "$privlib/pod/perldiag.pod", "$privlib/pods/perldiag.pod", ); # handy for development testing of new warnings etc unshift @trypod, "./pod/perldiag.pod" if -e "pod/perldiag.pod"; (my $PODFILE) = ((grep { -e } @trypod), $trypod[$#trypod])[0]; $DEBUG ||= 0; local $| = 1; local $_; local $.; my $standalone; my(%HTML_2_Troff, %HTML_2_Latin_1, %HTML_2_ASCII_7); CONFIG: { our $opt_p = our $opt_d = our $opt_v = our $opt_f = ''; unless (caller) { $standalone++; require Getopt::Std; Getopt::Std::getopts('pdvf:') or die "Usage: $0 [-v] [-p] [-f splainpod]"; $PODFILE = $opt_f if $opt_f; $DEBUG = 2 if $opt_d; $VERBOSE = $opt_v; $PRETTY = $opt_p; } if (open(POD_DIAG, '<', $PODFILE)) { warn "Happy happy podfile from real $PODFILE\n" if $DEBUG; last CONFIG; } if (caller) { INCPATH: { for my $file ( (map { "$_/".__PACKAGE__.".pm" } @INC), $0) { warn "Checking $file\n" if $DEBUG; if (open(POD_DIAG, '<', $file)) { while () { next unless /^__END__\s*# wish diag dbase were more accessible/; print STDERR "podfile is $file\n" if $DEBUG; last INCPATH; } } } } } else { print STDERR "podfile is \n" if $DEBUG; *POD_DIAG = *main::DATA; } } if (eof(POD_DIAG)) { die "couldn't find diagnostic data in $PODFILE @INC $0"; } %HTML_2_Troff = ( 'amp' => '&', # ampersand 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote "Aacute" => "A\\*'", # capital A, acute accent # etc ); %HTML_2_Latin_1 = ( 'amp' => '&', # ampersand 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote "Aacute" => "\xC1" # capital A, acute accent # etc ); %HTML_2_ASCII_7 = ( 'amp' => '&', # ampersand 'lt' => '<', # left chevron, less-than 'gt' => '>', # right chevron, greater-than 'quot' => '"', # double quote "Aacute" => "A" # capital A, acute accent # etc ); our %HTML_Escapes; *HTML_Escapes = do { if ($standalone) { $PRETTY ? \%HTML_2_Latin_1 : \%HTML_2_ASCII_7; } else { \%HTML_2_Latin_1; } }; *THITHER = $standalone ? *STDOUT : *STDERR; my %transfmt = (); my $transmo = <) { sub _split_pod_link { $_[0] =~ m'(?:([^|]*)\|)?([^/]*)(?:/("?)(.*)\3)?'s; ($1,$2,$4); } unescape(); if ($PRETTY) { sub noop { return $_[0] } # spensive for a noop sub bold { my $str =$_[0]; $str =~ s/(.)/$1\b$1/g; return $str; } sub italic { my $str = $_[0]; $str =~ s/(.)/_\b$1/g; return $str; } s/C<<< (.*?) >>>|C<< (.*?) >>|[BC]<(.*?)>/bold($+)/ges; s/[IF]<(.*?)>/italic($1)/ges; s/L<(.*?)>/ my($text,$page,$sect) = _split_pod_link($1); defined $text ? $text : defined $sect ? italic($sect) . ' in ' . italic($page) : italic($page) /ges; s/S<(.*?)>/ $1 /ges; } else { s/C<<< (.*?) >>>|C<< (.*?) >>|[BC]<(.*?)>/$+/gs; s/[IF]<(.*?)>/$1/gs; s/L<(.*?)>/ my($text,$page,$sect) = _split_pod_link($1); defined $text ? $text : defined $sect ? qq '"$sect" in $page' : $page /ges; s/S<(.*?)>/ $1 /ges; } unless (/^=/) { if (defined $header) { if ( $header eq 'DESCRIPTION' && ( /Optional warnings are enabled/ || /Some of these messages are generic./ ) ) { next; } $_ = expand $_; s/^/ /gm; $msg{$header} .= $_; for my $h(@headers) { $msg{$h} .= $_ } ++$seen_body; undef $for_item; } next; } # If we have not come across the body of the description yet, then # the previous header needs to share the same description. if ($seen_body) { @headers = (); } else { push @headers, $header if defined $header; } if ( ! s/=item (.*?)\s*\z//s || $over_level != 1) { if ( s/=head1\sDESCRIPTION//) { $msg{$header = 'DESCRIPTION'} = ''; undef $for_item; } elsif( s/^=for\s+diagnostics\s*\n(.*?)\s*\z// ) { $for_item = $1; } elsif( /^=over\b/ ) { $over_level++; } elsif( /^=back\b/ ) { # Stop processing body here $over_level--; if ($over_level == 0) { undef $header; undef $for_item; $seen_body = 0; next; } } next; } if( $for_item ) { $header = $for_item; undef $for_item } else { $header = $1; $header =~ s/\n/ /gs; # Allow multi-line headers } # strip formatting directives from =item line $header =~ s/[A-Z]<(.*?)>/$1/g; # Since we strip "(\.\s*)\n" when we search a warning, strip it here as well $header =~ s/(\.\s*)?$//; my @toks = split( /(%l?[dxX]|%[ucp]|%(?:\.\d+)?[fs])/, $header ); if (@toks > 1) { my $conlen = 0; for my $i (0..$#toks){ if( $i % 2 ){ if( $toks[$i] eq '%c' ){ $toks[$i] = '.'; } elsif( $toks[$i] =~ /^%(?:d|u)$/ ){ $toks[$i] = '\d+'; } elsif( $toks[$i] =~ '^%(?:s|.*f)$' ){ $toks[$i] = $i == $#toks ? '.*' : '.*?'; } elsif( $toks[$i] =~ '%.(\d+)s' ){ $toks[$i] = ".{$1}"; } elsif( $toks[$i] =~ '^%l*([pxX])$' ){ $toks[$i] = $1 eq 'X' ? '[\dA-F]+' : '[\da-f]+'; } } elsif( length( $toks[$i] ) ){ $toks[$i] = quotemeta $toks[$i]; $conlen += length( $toks[$i] ); } } my $lhs = join( '', @toks ); $lhs =~ s/(\\\s)+/\\s+/g; # Replace lit space with multi-space match $transfmt{$header}{pat} = " s^\\s*$lhs\\s*\Q$header\Es\n\t&& return 1;\n"; $transfmt{$header}{len} = $conlen; } else { my $lhs = "\Q$header\E"; $lhs =~ s/(\\\s)+/\\s+/g; # Replace lit space with multi-space match $transfmt{$header}{pat} = " s^\\s*$lhs\\s*\Q$header\E\n\t && return 1;\n"; $transfmt{$header}{len} = length( $header ); } print STDERR __PACKAGE__.": Duplicate entry: \"$header\"\n" if $msg{$header}; $msg{$header} = ''; $seen_body = 0; } close POD_DIAG unless *main::DATA eq *POD_DIAG; die "No diagnostics?" unless %msg; # Apply patterns in order of decreasing sum of lengths of fixed parts # Seems the best way of hitting the right one. for my $hdr ( sort { $transfmt{$b}{len} <=> $transfmt{$a}{len} } keys %transfmt ){ $transmo .= $transfmt{$hdr}{pat}; } $transmo .= " return 0;\n}\n"; print STDERR $transmo if $DEBUG; eval $transmo; die $@ if $@; } if ($standalone) { if (!@ARGV and -t STDIN) { print STDERR "$0: Reading from STDIN\n" } while (defined (my $error = <>)) { splainthis($error) || print THITHER $error; } exit; } my $olddie; my $oldwarn; sub import { shift; $^W = 1; # yup, clobbered the global variable; # tough, if you want diags, you want diags. return if defined $SIG{__WARN__} && ($SIG{__WARN__} eq \&warn_trap); for (@_) { /^-d(ebug)?$/ && do { $DEBUG++; next; }; /^-v(erbose)?$/ && do { $VERBOSE++; next; }; /^-p(retty)?$/ && do { print STDERR "$0: I'm afraid it's too late for prettiness.\n"; $PRETTY++; next; }; # matches trace and traceonly for legacy doc mixup reasons /^-t(race(only)?)?$/ && do { $TRACEONLY++; next; }; /^-w(arntrace)?$/ && do { $WARNTRACE++; next; }; warn "Unknown flag: $_"; } $oldwarn = $SIG{__WARN__}; $olddie = $SIG{__DIE__}; $SIG{__WARN__} = \&warn_trap; $SIG{__DIE__} = \&death_trap; } sub enable { &import } sub disable { shift; return unless $SIG{__WARN__} eq \&warn_trap; $SIG{__WARN__} = $oldwarn || ''; $SIG{__DIE__} = $olddie || ''; } sub warn_trap { my $warning = $_[0]; if (caller eq __PACKAGE__ or !splainthis($warning)) { if ($WARNTRACE) { print STDERR Carp::longmess($warning); } else { print STDERR $warning; } } goto &$oldwarn if defined $oldwarn and $oldwarn and $oldwarn ne \&warn_trap; }; sub death_trap { my $exception = $_[0]; # See if we are coming from anywhere within an eval. If so we don't # want to explain the exception because it's going to get caught. my $in_eval = 0; my $i = 0; while (my $caller = (caller($i++))[3]) { if ($caller eq '(eval)') { $in_eval = 1; last; } } splainthis($exception) unless $in_eval; if (caller eq __PACKAGE__) { print STDERR "INTERNAL EXCEPTION: $exception"; } &$olddie if defined $olddie and $olddie and $olddie ne \&death_trap; return if $in_eval; # We don't want to unset these if we're coming from an eval because # then we've turned off diagnostics. # Switch off our die/warn handlers so we don't wind up in our own # traps. $SIG{__DIE__} = $SIG{__WARN__} = ''; $exception =~ s/\n(?=.)/\n\t/gas; die Carp::longmess("__diagnostics__") =~ s/^__diagnostics__.*?line \d+\.?\n/ "Uncaught exception from user code:\n\t$exception" /re; # up we go; where we stop, nobody knows, but i think we die now # but i'm deeply afraid of the &$olddie guy reraising and us getting # into an indirect recursion loop }; my %exact_duplicate; my %old_diag; my $count; my $wantspace; sub splainthis { return 0 if $TRACEONLY; for (my $tmp = shift) { local $\; local $!; ### &finish_compilation unless %msg; s/(\.\s*)?\n+$//; my $orig = $_; # return unless defined; # get rid of the where-are-we-in-input part s/, <.*?> (?:line|chunk).*$//; # Discard 1st " at line " and all text beyond # but be aware of messages containing " at this-or-that" my $real = 0; my @secs = split( / at / ); return unless @secs; $_ = $secs[0]; for my $i ( 1..$#secs ){ if( $secs[$i] =~ /.+? (?:line|chunk) \d+/ ){ $real = 1; last; } else { $_ .= ' at ' . $secs[$i]; } } # remove parenthesis occurring at the end of some messages s/^$(.*)$$/$1/; if ($exact_duplicate{$orig}++) { return &transmo; } else { return 0 unless &transmo; } my $short = shorten($orig); if ($old_diag{$_}) { autodescribe(); print THITHER "$short (#$old_diag{$_})\n"; $wantspace = 1; } elsif (!$msg{$_} && $orig =~ /\n./s) { # A multiline message, like "Attempt to reload / # Compilation failed" my $found; for (split /^/, $orig) { splainthis($_) and $found = 1; } return $found; } else { autodescribe(); $old_diag{$_} = ++$count; print THITHER "\n" if $wantspace; $wantspace = 0; print THITHER "$short (#$old_diag{$_})\n"; if ($msg{$_}) { print THITHER $msg{$_}; } else { if (0 and $standalone) { print THITHER " **** Error #$old_diag{$_} ", ($real ? "is" : "appears to be"), " an unknown diagnostic message.\n\n"; } return 0; } } return 1; } } sub autodescribe { if ($VERBOSE and not $count) { print THITHER &{$PRETTY ? \&bold : \&noop}("DESCRIPTION OF DIAGNOSTICS"), "\n$msg{DESCRIPTION}\n"; } } sub unescape { s { E< ( [A-Za-z]+ ) > } { do { exists $HTML_Escapes{$1} ? do { $HTML_Escapes{$1} } : do { warn "Unknown escape: E<$1> in $_"; "E<$1>"; } } }egx; } sub shorten { my $line = $_[0]; if (length($line) > 79 and index($line, "\n") == -1) { my $space_place = rindex($line, ' ', 79); if ($space_place != -1) { substr($line, $space_place, 1) = "\n\t"; } } return $line; } 1 unless $standalone; # or it'll complain about itself __END__ # wish diag dbase were more accessible