*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> perl5/diagnostics (3)              


diagnostics(3)							diagnostics(3)

NAME    [Toc]    [Back]

     diagnostics - Perl	compiler pragma	to force verbose warning diagnostics

     splain - standalone program to do the same	thing

SYNOPSIS    [Toc]    [Back]

     As	a pragma:

	 use diagnostics;
	 use diagnostics -verbose;

	 enable	 diagnostics;
	 disable diagnostics;

     Aa	a program:

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

DESCRIPTION    [Toc]    [Back]

     The diagnostics Pragma

     This module extends the terse diagnostics normally	emitted	by both	the
     perl compiler and the perl	interpeter, augmenting them with the more
     explicative and endearing descriptions found in the perldiag manpage.
     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	does
     enable perl's -w flag.)  Your whole compilation will then be subject(ed
     :-) to the	enhanced diagnostics.  These still go out 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	no
     diagnostics to turn them off at compiletime.  However, you	may control
     there behaviour at	runtime	using the disable() and	enable() methods to
     turn them off and on respectively.

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

     The splain	Program

     While apparently a	whole nuther program, splain is	actually nothing more
     than a link to the	(executable) diagnostics.pm module, as well as a link
     to	the diagnostics.pod documentation.  The	-v flag	is like	the use

									Page 1

diagnostics(3)							diagnostics(3)

     diagnostics -verbose directive.  The -p flag is like the
     $diagnostics::PRETTY variable.  Since you're post-processing with splain,
     there's no	sense in being able to enable()	or disable() processing.

     Output from splain	is directed to STDOUT, unlike the pragma.

EXAMPLES    [Toc]    [Back]

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

	 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 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 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";

									Page 2

diagnostics(3)							diagnostics(3)

	 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";

INTERNALS    [Toc]    [Back]

     Diagnostic	messages derive	from the perldiag.pod file when	available at
     runtime.  Otherwise, they may be embedded in the file itself when the
     splain package is built.	See the	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 }

BUGS    [Toc]    [Back]

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

     The -pretty directive is called too late to affect	matters.  You have to
     do	this instead, and 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 splain, you should expect a bit of whimsy.

AUTHOR    [Toc]    [Back]

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

									Page 3

diagnostics(3)							diagnostics(3)

									PPPPaaaaggggeeee 4444
[ Back ]
 Similar pages
Name OS Title
splain OpenBSD produce verbose warning diagnostics
splain Linux standalone program to do the same thing
splain IRIX standalone program to do the same thing
less IRIX perl pragma to request less of something from the compiler
constant IRIX Perl pragma to declare constants
subs IRIX Perl pragma to predeclare sub names
strict IRIX Perl pragma to restrict unsafe constructs
integer IRIX Perl pragma to compute arithmetic in integer instead of double
ops IRIX Perl pragma to restrict unsafe operations when compiling
sigtrap IRIX Perl pragma to enable simple signal handling
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service