NAME

CGI::WebOut - Perl extension to handle CGI output (in PHP-style).

SYNOPSIS

  # Simple CGI script (no 500 Apache error!)
  use CGI::WebOut;
  print "Hello world!"; # wow, we may NOT output Content-type!
  # Handle output for {}-block
  my $str=grab {
    print "Hi there!\n";
  };
  $str=~s/\n/<br>/sg;
  print $str;

DESCRIPTION

This module is used to make CGI programmer's work more comfortable. The main idea is to handle output stream (STDOUT) to avoid any data to be sent to browser without Content-type header. Of cource, you may also send your own headers to browser using Header(). Any errors or warnings in your script will be printed at the bottom of the page ``in PHP-style''. You may also use Carp module together with CGI::WebOut.

You may also handle any program block's output (using print etc.) and place it to the variable using grab {...} subroutine. It is a very useful feature for lots of CGI-programmers.

The last thing - support of try-catch ``instruction''. WARNING: they are not real instructions, like map {...}, grep {...} etc.! Be careful with return instruction in try-catch blocks.

Note: you may use CGI::WebOut outside the field of CGI scripting. In ``non-CGI'' script headers are NOT output, and warnings are shown as plain-text. grab {...}, try-catch etc. work as usual.

New features in version 2.0

Since version 2.0 module if fully tie-safe. That means the code:

  tie(*STDOUT, "T");
  eval "use CGI::WebOut";
  print "OK!";
  untie(*STDOUT);

generates exactly the same sequense of T method calls as:

  tie(*STDOUT, "T");
  print "OK!";
  untie(*STDOUT);

So you can use CGI::WebOut with, for example, FastCGI module.

EXPORT

All the useful functions. Larry says it is not a good idea, but Rasmus does not think so.

EXAMPLES

  # Using Header()
  use CGI::WebOut;
  NoAutoflush();
  print "Hello world!"
  Header("X-Powered-by: dklab");

  # Handle output buffer
  use CGI::WebOut;
  my $str=grab {
    print "Hi there!\n";
        # Nested grab!
        my $s=grab {
                print "This string will be redirect to variable!";
        }
  }
  $str=~s/\n/<br>/sg;

  # Exception/warnings handle
  use CGI::WebOut;
  try {
    DoSomeDangerousStuff();
  } catch {
    print "An error occured: $_";
        throw "Error";
  } warnings {
    print "Wanning & error messages:".join("\n",@_);
  };

DESCRIPTION

use CGI::WebOut [($forgotAboutHeaders)]

Handles the STDOUT to avoid document output without Content-type header in ``PHP-style''. If $forgotAboutHeaders is true, following ``print'' will produse output of all HTTP headers. Use this options only in FastCGI environment.

string grab { ... }

Handles output stream. Usage:

    $grabbed = grab { 
        print 'Hello!' 
    } catch { 
        die "An error occurred while grabbing the output: $@"; 
    };

or simply

    $grabbed = grab { print 'Hello!' };

bool try {...} catch {...} warnings {...}

Try-catch preudo-instruction. Usage:

    try { 
       some dangeorus code, which may call die() or
       any other bad function (or throw "instruction")
    } catch {
       use $_ to get the exception or error message
    } warnings {
       use @_ to get all the warning messages
    }

Note: catch and warnings blocks are optional and called in order of their appearance.

void throw($exception_object)

Throws an exception.

int ErrorReporting([int $level])

Sets the error handling mode. $level may be:

    ER_NoErr       - no error reporting;
    ER_Err2Browser - errors are printed to browser;
    ER_Err2Comment - errors are printed to browser inside <!-- ... -->;
    ER_Err2Plain   - plain-text warnings.

Returns the previous error reporting mode.

void Header(string $header)

Sets document responce header. If autoflush mode is not set, this function may be used just before the first output.

int SetAutoflush([bool $mode])

Sets the autoflush mode ($mode!=0) or disables if ($mode=0). Returns the previous status of autoflush mode.

int NoAutoflush()

Equivalents to SetAutoflush(0).

int UseAutoflush()

Equivalents to SetAutoflush(1).

void Flush()

Flushes the main output buffer to browser. If autoflush mode is set, this function is called automatically after each print call.

void Redirect(string $URL)

Sends Location: $URL header to redirect the browser to $URL. Also finishes the script with exit() call.

void ExternRedirect(string $URL)

The same as Redirect(), but first translates $URL to absolute format: ``http://host/url''.

void NoCache()

Disables browser document caching.

AUTHOR

Dmitry Koteroff <koteroff@cpan.org>, http://dklab.ru/chicken/4.html