CGI::WebOut - Perl extension to handle CGI output.

- NAME
- SYNOPSIS
- DESCRIPTION

- New features in version 2.0
- EXPORT

- EXAMPLES
- DESCRIPTION
- AUTHOR
- SEE ALSO

# 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

# SEE ALSO

`CGI::WebIn`, `Carp`.