RT#62783: improve, document, fatalsTo Browsers, eval, mod_perl 2 inte…

…ractions.

    I modified the original patch to change $CGI::Carp::ToBrowser to
    $CGI::Carp::TO_BROWSER.
    This is consistent with other global variables names in $CGI::Carp and CGI.pm.

Changes

@@ -1,7 +1,11 @@
+  - A new option to set $CGI::Carp::TO_BROWSER = 0, allows you to explicitly  
+    exclude a particular scope from triggering printing to the browser when
+    fatatlsToBrowser is set. (RT#62783, Thanks to papowell) 
 
   [DOCUMENTATION]
   - quit referring to the <link> tag as being "rarely used".  (Victor Sanders)
   - typo and whitespace fixes (RT#62785, thanks to  scop@cpan.org) 
+  - CGI::Carp doc are updated to reflect that it can work with mod_perl 2.0. 
 
   [INTERNALS]
   - Re-fixing https test in http.t. (RT#54768, thanks to SPROUT)

lib/CGI/Carp.pm

@@ -116,7 +116,7 @@ occur in the early compile phase will be seen.
 Nonfatal errors will still be directed to the log file only (unless redirected
 with carpout).
 
-Note that fatalsToBrowser does B<not> work with mod_perl version 2.0
+Note that fatalsToBrowser may B<not> work well with mod_perl version 2.0
 and higher.
 
 =head2 Changing the default message
@@ -183,6 +183,28 @@ attempting to set SIG{__DIE__} yourself, you may interfere with
 this module's functionality, or this module may interfere with 
 your module's functionality.
 
+=head2 SUPPRESSING PERL ERRORS APPEARING IN THE BROWSER WINDOW
+
+A problem sometimes encountered when using fatalsToBrowser is
+when a C<die()> is done inside an C<eval> body or expression.
+Even though the
+fatalsToBrower support takes precautions to avoid this,
+you still may get the error message printed to STDOUT.
+This may have some undesireable effects when the purpose of doing the
+eval is to determine which of several algorithms is to be used.
+
+By setting C<$CGI::Carp::TO_BROWSER> to 0 you can suppress printing the C<die> messages
+but without all of the complexity of using C<set_die_handler>.
+You can localize this effect to inside C<eval> bodies if this is desireable:
+For example:
+
+ eval {
+   local $CGI::Carp::TO_BROWSER = 0;
+   die "Fatal error messages not sent browser"
+ }
+ # $@ will contain error message
+
+
 =head1 MAKING WARNINGS APPEAR AS HTML COMMENTS
 
 It is now also possible to make non-fatal errors appear as HTML
@@ -245,6 +267,8 @@ non-overridden program name
   
 =head1 CHANGE LOG
 
+3.51 Added $CGI::Carp::TO_BROWSER
+
 1.29 Patch from Peter Whaite to fix the unfixable problem of CGI::Carp
      not behaving correctly in an eval() context.
 
@@ -321,9 +345,10 @@ use File::Spec;
 
 $main::SIG{__WARN__}=\&CGI::Carp::warn;
 
-$CGI::Carp::VERSION     = '3.45';
+$CGI::Carp::VERSION     = '3.51';
 $CGI::Carp::CUSTOM_MSG  = undef;
 $CGI::Carp::DIE_HANDLER = undef;
+$CGI::Carp::TO_BROWSER  = 1;
 
 
 # fancy import routine detects and handles 'errorWrap' specially.
@@ -437,7 +462,7 @@ sub die {
   $arg .= " at $file line $line.\n" unless ref $arg or $arg=~/\n$/;
 
   realdie $arg           if ineval();
-  &fatalsToBrowser($arg) if $WRAP;
+  &fatalsToBrowser($arg) if ($WRAP and $CGI::Carp::TO_BROWSER);
 
   $arg=~s/^/ stamp() /gme if $arg =~ /\n$/ or not exists $ENV{MOD_PERL};
 

t/carp.t

@@ -3,10 +3,10 @@
 
 use strict;
 
-use Test::More tests => 59;
+use Test::More tests => 61;
 use IO::Handle;
 
-BEGIN { use_ok('CGI::Carp') };
+use CGI::Carp;
 
 #-----------------------------------------------------------------------------
 # Test id
@@ -371,3 +371,20 @@ ok(!defined buffer("WIBBLE"),      '"WIBBLE" doesn\'t returns proper filehandle'
         return bless {}, shift;
     }
 }
+
+
+@result = ();
+tie *STDOUT, 'StoreStuff' or die "Can't tie STDOUT";
+ {
+ 	eval {
+ 		$CGI::Carp::TO_BROWSER = 0;
+ 		die 'Message ToBrowser = 0';
+	};
+ 	$result[0] = $@;
+ 	$result[1] .= $_ while (<STDOUT>);
+ }
+untie *STDOUT;
+
+ like $result[0] => qr/Message ToBrowser/, 'die message for ToBrowser = 0 is OK';
+ ok !$result[1], 'No output for ToBrowser = 0';
+