/ 
Cant-1.01
River stage zero No dependents
/ Cant

NAME

Cant - Perl extension for easy error messages

SYNOPSIS

use Cant;

open(FOO, "foo")		or cant "open 'foo'";
$pid = fork();
defined $pid			or cant "fork";
! system("some command")	or wcant "run 'some command'";

print "Prepping system...";
!system("foo")		or cant "\nrun foo";

DESCRIPTION

The Cant module provides easy shorthands for warning and dieing of system or library errors. The messages generated by cant and wcant always begin with the program name (from $0), a colon, and then "Unable to" and the first argument to cant or wcant. As a result, you can usually write your cant invocations so as be sensical when read in the script and get sensical errors message out.

The exact message generated depends on the values of the $! and $? variables. The first match is choosen from the following possibilities:

  • If the last argument to cant or wcant ends with a newline, nothing will be used.

  • If $! is not empty/zero, the value ": $!" is used.

  • If the exit status found in $? is a normal exit of zero, nothing is will be used.

  • If a non-zero normal exit status is found in $?, the text ": program returned" and the actual exitcode will be used.

  • If a 'stopped by signal' exit status is found in $?, the text ": program stopped with signal " and the signal number will be used. Note that you'll normally only see such exit statuses if you pass the WUNTRACED flag to waitpid().

  • If a 'death by signal' exit status is found in $?, the text ": program died with signal " and the signal number will be used. If the process codedumped in the process, the text ", coredumped" will the added to that.

The text from the above will be put after all other arguments to cant or wcant, unless the first argument contains a newline anywhere but at the very beginnning. If there is such a non-leading newline, the text will be inserted immeadiately after that newline.

Finally, the text " at filename line line\n" will be added at the very end containing the actual filename and line number of the call to cant or wcant.

If the first argument starts with a newline, that newline will be suppressed from its apparent place in the message and instead a newline will be put at the start of the message, before anything else. This allows you to force a leading newline when you think the message will be generated while they're already on the current line, as in the last example in the SYNOPSIS.

BUGS

The formatting rules are too complicated.

HISTORY

1.00

Finally gave Cant.pm the wrapping of a module. The earliest version of cant() was simply sub cant { die "$0: Unable to", @_, ": $!" }

It evolved from there first to add handling of program errors ($?), then newline formatting singals, and finally the "trailing newline means no extra message". You've come a long way, baby...

1.01

If cant() or wcant() appears to be called from a package besides main they'll now invoke croak/carp instead of die/warn.

AUTHOR

Philip Guenther, guenther@gac.edu

COPYING

Copyright (C) 1998-2000, Philip Guenther. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perlfunc(1).