The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Carp-Throw-0.04
River stage zero No dependents
++
/ CGI::Carp::Throw

NAME

CGI::Carp::Throw - CGI::Carp exceptions that don't look like errors.

SYNOPSIS

  use strict;
  use CGI qw/:standard/;
  use CGI::Carp::Throw qw/:carp_browser/;

  print header, start_html(-title => 'Throw test'),
    p('expecting parameter: "need_this".');

  if (my $need_this = param('need_this')) {
    if ($need_this =~ /^[\s\w.]+$/ and -e $need_this) {
        print h1('Thank you for providing parameter "need_this"'), end_html;
    }
    else {
        croak 'Invalid or non-existent file name: ', $need_this;
    }
  }
  else {
    throw_browser '***  Please provide parameter: need_this!  ***';
  }

  -- OR --

  use strict;
  use CGI qw/:standard/;
  use CGI::Carp::Throw qw/:carp_browser throw_format_sub/;
  use HTML::Template;

  my $t = HTML::Template->new(filehandle => *DATA);

  #####################################################################
  sub neaterThrowMsg {
    my $throw_msg = shift;
    $t->param(throw_msg => $throw_msg);
    return $t->output;
  }
  throw_format_sub(\&neaterThrowMsg);

  #####################################################################
  print header, start_html(-title => 'Throw test'),
    p('expecting parameter: "need_this".');

  if (my $need_this = param('need_this')) {
    if ($need_this =~ /^[\s\w.]+$/ and -e $need_this) {
        print h1('Thank you for providing parameter "need_this"'), end_html;
    }
    else {
        croak 'Invalid or non-existent file name: ', $need_this;
    }
  }
  else {
    throw_browser '***  Please provide parameter: need_this!  ***';
  }

  __DATA__
  <html>
  <head><title>A Template</title></head>
  <body>
  <p style="color: red; font-style: italic"><TMPL_VAR NAME=THROW_MSG></p>
  </body>
  </html>

DESCRIPTION

Extend CGI::Carp, without breaking CGI::Carp's functionality, to allow die and croak calls to be selectively changed to throw_browser exceptions that are displayed in the user's browser as application messages rather than errors with trace information. CGI::Carp has somewhat similar, but less flexible, capabilities that allow for reformatting of all croak, die etc. exception requests. Trace information remains available in HTML comments, by default, but may be left out entirely with the throw_browser_cloaked call.

With some reluctance, it was decided that CGI::Carp::Throw would not default to invoking fatalsToBrowser or warningsToBrowser to better conform to the default behavior of CGI::Carp. The import tag :carp_browser was created as an alternative that has the effect of requesting the import of both "ToBrowser" methods/keywords.

Methods

class method throw_browser 'browser message ', 'message param' ...

Throw an exception by "die"ing and send passed strings to the browser with clean formatting that does not imply any kind of programmatic error. Tracing data still included in HTML comment on page.

class method throw_browser_cloaked 'browser message ', 'message param' ...

Nearly the same as throw_browser but tracing data NOT automatically included anywhere on page.

class method throw_format_sub \&message_format_sub

Allow for custom formatting of exception message intended to include formatting with template technology. Custom formatting is done by user supplied routine passed as parameter to this method. Thrown exception is passed to the user provided routine as list from throw_browser call and return values are forwarded to browser as they would be from throw_browser.

EXPORT

throw_browser by default.

SEE ALSO

CGI::Carp, Carp

AUTHOR

Ronald Schmidt, <ronaldxs at software-path.com>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by The Software Path

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.