/ 
Win32GUICarp-1.01
River stage zero No dependents
/ Win32::GUI::Carp

NAME

Win32::GUI::Carp - Redirect warnings and errors to Win32::GUI MessageBoxes

SYNOPSIS

use Win32::GUI::Carp qw/cluck/;

croak "Ribbit!";
confess "It was me: $!";
carp "How could you do that?";
warn "Duck!";
die "There's no hope...";
cluck "Don't do it.";

use Win32::GUI::Carp qw/warningsToDialog/;
warn "Warnings will be displayed in a pop-up dialog.";

use Win32::GUI::Carp qw/fatalsToDialog/;
die "Fatal error messages will be displayed in a pop-up dialog.";

use Win32::GUI::Carp qw/winwarn windie/;
winwarn "Warning in dialog.";
windie  "Death in dialog.";

DESCRIPTION

When Perl programs are run in a GUI environment, it is often desirable to have them run with no console attached. Unfortunately, this causes any warnings or errors to be lost. Worse, fatal errors can cause your program to silently disappear, forcing you to restart the program, attached to a console, and hope you can reproduce the error.

This module makes it easy to see any errors or warnings your console-less program might produce by catching any errors and/or warnings and displaying them in a pop-up dialog box using Win32::GUI. It is similar in spirit to CGI::Carp's fatalsToBrowser and warningsToBrowser special import directives.

To cause errors or warnings to be displayed in a dialog, simply specify one or more of the following options on the use line, as shown in the SYNOPSIS.

IMPORT OPTIONS

warningsToDialog

Show any warnings in a pop-up dialog box.

This option will cause a dialog box to be displayed containing the text of the warnings. The type and style of the dialog box can be configured (see "CONFIGURATION"). Note that warnings are still sent to STDERR as well.

This option can also be activated or deactivated by setting $Win32::GUI::Carp::WarningsToDialog to true or false, respectively.

fatalsToDialog

Show any fatal errors in a pop-up dialog box.

This option will cause a dialog box to be displayed containing the text of the fatal error. The type and style of the dialog box can be configured (see "CONFIGURATION"). Note that errors are still sent to STDERR as well.

This option can also be activated or deactivated by setting $Win32::GUI::Carp::FatalsToDialog to true or false, respectively.

immediateWarnings

This option controls whether all errors and warnings are displayed in a single dialog box or each get their own.

By default, warnings are buffered and not shown until just before the program terminates. At that point, any warnings and errors are shown together in a single dialog box. This is to cut down on the number of dialogs that have to be clicked through, although it means that you can't tell when a particular warning occurred.

If this option is specified, each warning and error message will get its own dialog box which will be displayed as soon as the warning or error occurs. Note that warnings are always printed to STDERR as soon as they occur, regardless of the state of this option.

Care should be taken when setting this option as it can cause a large number of dialog boxes to be created.

This option can also be activated or deactivated by setting $Win32::GUI::Carp::ImmediateWarnings to true or false, respectively.

FUNCTIONS

winwarn

Raises a warning, using a dialog. This function ignores the state of warningsToDialog, although all other options are observed (including ImmediateWarnings).

windie

Raises a fatal error, using a dialog. This function ignores the state of fatalsToDialog, although all other options are observed.

syscarp

Executes a system command, just like system, but passes its its STDERR through any warn filters. In other words, if the command displays anything on STDERR, it will show up as a warning in the calling program, and thus display in a dialog (respecting warningsToDialog).

Note: The name of this function is subject to change, as I think it is somewhat misleading.

syscroak

Does the same thing as "syscarp" but dies if anything is sent to STDERR. It includes a message with the return value of the process.

Note: The name of this function is subject to change, as I think it is somewhat misleading.

CONFIGURATION

The following variables control the style and type of dialog box used.

$Win32::GUI::Carp::DialogTitle

A string that will be used as the title of the dialog box. This defaults to "Warning" when displaying warnings, and "Error" when displaying fatal errors.

$Win32::GUI::Carp::FatalFilter

Set this to a reference to a subroutine that should be called whenever a fatal error is about to be shown in a dialog. The routine receives the error message in @_, and if it returns a true value the error will be sent to the dialog as normal, otherwise the dialog will not be shown (though the error still propagates as normal).

$Win32::GUI::Carp::WarningFilter

Set this to a reference to a subroutine that should be called whenever a warning is about to be shown in a dialog. The routine receives the warning message in @_, and if it returns a true value the warning will be sent to the dialog as normal, otherwise the dialog will not be shown (though the warning still propagates as normal).

DEPENDANCIES

This module relies on the following other modules to be installed:

Win32::GUI
Carp
IPC::Open3 (for "syscarp" and "syscroak")

BUGS

  • This module installs a signal handler for both __DIE__ and __WARN__. While it does save any previous handlers and chain them properly, any new handler that is installed will effectively disable the fatalsToDialog and warningsToDialog options, respectively. Note that, as this module's handlers are installed at compile time, it is probable that any other handlers will be "new."

    Especially if these changes aren't properly localized, this can cause us to miss many errors. There is a work-around, but it's a bit of an ugly hack, and involves tying %SIG, which seems dangerous. I may include it as an option in the future.

  • By default, carp(), croak() and confess() are exported from Carp. If nothing is specified in the import list (including the special *ToDialog and immediateWarnings options), then Win32::GUI::Carp also exports those functions. As soon as anything is given in the import list, however, Exporter stops exporting the things in @EXPORT (meaning the aforementioned functions don't get exported).

  • There seems to be a bug on some versions of Win32 affecting "syscarp" and, moreso, "syscroak" where $? is always set to 0, instead of the correct return value of the called program.

AUTHOR

Copyright 2002, Cory Johns.

This module is free software; you can redistribute and/or modify it under the same terms as Perl itself.

Address bug reports and comments to: Cory Johns <johnsca@cpan.org>

SEE ALSO

Carp, CGI::Carp, Win32::GUI