Provided by: libhtml-mason-perl_1.58-1_all bug

NAME

       HTML::Mason::CGIHandler - Use Mason in a CGI environment

SYNOPSIS

       In httpd.conf or .htaccess:

           <LocationMatch "\.html$">
               Action html-mason /cgi-bin/mason_handler.cgi
               AddHandler html-mason .html
           </LocationMatch>
           <LocationMatch "^/cgi-bin/">
               RemoveHandler .html
           </LocationMatch>
           <FilesMatch "(autohandler|dhandler)$">
               Order allow,deny
               Deny from all
           </FilesMatch>

       A script at /cgi-bin/mason_handler.pl :

          #!/usr/bin/perl
          use HTML::Mason::CGIHandler;

          my $h = HTML::Mason::CGIHandler->new
           (
            data_dir  => '/home/jethro/code/mason_data',
            allow_globals => [qw(%session $u)],
           );

          $h->handle_request;

       A .html component somewhere in the web server's document root:

          <%args>
           $mood => 'satisfied'
          </%args>
          % $r->err_header_out(Location => "http://blahblahblah.com/moodring/$mood.html");
          ...

DESCRIPTION

       This module lets you execute Mason components in a CGI environment.  It lets you keep your
       top-level components in the web server's document root, using regular component syntax and
       without worrying about the particular details of invoking Mason on each request.

       If you want to use Mason components from within a regular CGI script (or any other Perl
       program, for that matter), then you don't need this module.  You can simply follow the
       directions in the Using Mason from a standalone script section of the administrator's
       manual.

       This module also provides an $r request object for use inside components, similar to the
       Apache request object under "HTML::Mason::ApacheHandler", but limited in functionality.
       Please note that we aim to replicate the "mod_perl" functionality as closely as possible -
       if you find differences, do not depend on them to stay different.  We may fix them in a
       future release.  Also, if you need some missing functionality in $r, let us know, we might
       be able to provide it.

       Finally, this module alters the "HTML::Mason::Request" object $m to provide direct access
       to the CGI query, should such access be necessary.

   "HTML::Mason::CGIHandler" Methods
       ·   new()

           Creates a new handler.  Accepts any parameter that the Interpreter accepts.

           If no "comp_root" parameter is passed to "new()", the component root will be
           $ENV{DOCUMENT_ROOT}.

       ·   handle_request()

           Handles the current request, reading input from $ENV{QUERY_STRING} or "STDIN" and
           sending headers and component output to "STDOUT".  This method doesn't accept any
           parameters.  The initial component will be the one specified in $ENV{PATH_INFO}.

       ·   handle_comp()

           Like "handle_request()", but the first (only) parameter is a component path or
           component object.  This is useful within a traditional CGI environment, in which
           you're essentially using Mason as a templating language but not an application server.

           "handle_component()" will create a CGI query object, parse the query parameters, and
           send the HTTP header and component output to STDOUT.  If you want to handle those
           parts yourself, see the Using Mason from a standalone script section of the
           administrator's manual.

       ·   handle_cgi_object()

           Also like "handle_request()", but this method takes only a CGI object as its
           parameter.  This can be quite useful if you want to use this module with CGI::Fast.

           The component path will be the value of the CGI object's "path_info()" method.

       ·   request_args()

           Given an "HTML::Mason::FakeApache" object, this method is expected to return a hash
           containing the arguments to be passed to the component.  It is a separate method in
           order to make it easily overrideable in a subclass.

       ·   interp()

           Returns the Mason Interpreter associated with this handler.  The Interpreter lasts for
           the entire lifetime of the handler.

   $r Methods
       ·   headers_in()

           This works much like the "Apache" method of the same name. In an array context, it
           will return a %hash of response headers. In a scalar context, it will return a
           reference to the case-insensitive hash blessed into the "HTML::Mason::FakeTable"
           class. The values initially populated in this hash are extracted from the CGI
           environment variables as best as possible. The pattern is to merely reverse the
           conversion from HTTP headers to CGI variables as documented here:
           <http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.

       ·   header_in()

           This works much like the "Apache" method of the same name. When passed the name of a
           header, returns the value of the given incoming header. When passed a name and a
           value, sets the value of the header. Setting the header to "undef" will actually unset
           the header (instead of setting its value to "undef"), removing it from the table of
           headers returned from future calls to "headers_in()" or "header_in()".

       ·   headers_out()

           This works much like the "Apache" method of the same name. In an array context, it
           will return a %hash of response headers. In a scalar context, it will return a
           reference to the case-insensitive hash blessed into the "HTML::Mason::FakeTable"
           class. Changes made to this hash will be made to the headers that will eventually be
           passed to the "CGI" module's "header()" method.

       ·   header_out()

           This works much like the "Apache" method of the same name.  When passed the name of a
           header, returns the value of the given outgoing header.  When passed a name and a
           value, sets the value of the header.  Setting the header to "undef" will actually
           unset the header (instead of setting its value to "undef"), removing it from the table
           of headers that will be sent to the client.

           The headers are eventually passed to the "CGI" module's "header()" method.

       ·   err_headers_out()

           This works much like the "Apache" method of the same name. In an array context, it
           will return a %hash of error response headers. In a scalar context, it will return a
           reference to the case-insensitive hash blessed into the "HTML::Mason::FakeTable"
           class. Changes made to this hash will be made to the error headers that will
           eventually be passed to the "CGI" module's "header()" method.

       ·   err_header_out()

           This works much like the "Apache" method of the same name. When passed the name of a
           header, returns the value of the given outgoing error header. When passed a name and a
           value, sets the value of the error header. Setting the header to "undef" will actually
           unset the header (instead of setting its value to "undef"), removing it from the table
           of headers that will be sent to the client.

           The headers are eventually passed to the "CGI" module's "header()" method.

           One header currently gets special treatment - if you set a "Location" header, you'll
           cause the "CGI" module's "redirect()" method to be used instead of the "header()"
           method.  This means that in order to do a redirect, all you need to do is:

            $r->err_header_out(Location => 'http://redirect.to/here');

           You may be happier using the "$m->redirect" method, though, because it hides most of
           the complexities of sending headers and getting the status code right.

       ·   content_type()

           When passed an argument, sets the content type of the current request to the value of
           the argument.  Use this method instead of setting a "Content-Type" header directly
           with "header_out()".  Like "header_out()", setting the content type to "undef" will
           remove any content type set previously.

           When called without arguments, returns the value set by a previous call to
           "content_type()".  The behavior when "content_type()" hasn't already been set is
           undefined - currently it returns "undef".

           If no content type is set during the request, the default MIME type "text/html" will
           be used.

       ·   method()

           Returns the request method used for the current request, e.g., "GET", "POST", etc.

       ·   http_header()

           This method returns the outgoing headers as a string, suitable for sending to the
           client.

       ·   send_http_header()

           Sends the outgoing headers to the client.

       ·   notes()

           This works much like the "Apache" method of the same name. When passed a $key
           argument, it returns the value of the note for that key. When passed a $value
           argument, it stores that value under the key. Keys are case-insensitive, and both the
           key and the value must be strings. When called in a scalar context with no $key
           argument, it returns a hash reference blessed into the "HTML::Mason::FakeTable" class.

       ·   pnotes()

           Like "notes()", but takes any scalar as an value, and stores the values in a case-
           sensitive hash.

       ·   subprocess_env()

           Works like the "Apache" method of the same name, but is simply populated with the
           current values of the environment. Still, it's useful, because values can be changed
           and then seen by later components, but the environment itself remains unchanged. Like
           the "Apache" method, it will reset all of its values to the current environment again
           if it's called without a $key argument.

       ·   params()

           This method returns a hash containing the parameters sent by the client.  Multiple
           parameters of the same name are represented by array references.  If both POST and
           query string arguments were submitted, these will be merged together.

   Added $m methods
       The $m object provided in components has all the functionality of the regular
       "HTML::Mason::Request" object $m, and the following:

       ·   cgi_object()

           Returns the current "CGI" request object.  This is handy for processing cookies or
           perhaps even doing HTML generation (but is that really what you want to do?).  If you
           pass an argument to this method, you can set the request object to the argument
           passed.  Use this with care, as it may affect components called after the current one
           (they may check the content length of the request, for example).

           Note that the ApacheHandler class (for using Mason under mod_perl) also provides a
           "cgi_object()" method that does the same thing as this one.  This makes it easier to
           write components that function equally well under CGIHandler and ApacheHandler.

       ·   cgi_request()

           Returns the object that is used to emulate Apache's request object.  In other words,
           this is the object that $r is set to when you use this class.

   "HTML::Mason::FakeTable" Methods
       This class emulates the behavior of the "Apache::Table" class, and is used to store manage
       the tables of values for the following attributes of <$r>:

       headers_in
       headers_out
       err_headers_out
       notes
       subprocess_env

       "HTML::Mason::FakeTable" is designed to behave exactly like "Apache::Table", and differs
       in only one respect. When a given key has multiple values in an "Apache::Table" object,
       one can fetch each of the values for that key using Perl's "each" operator:

         while (my ($k, $v) = each %{$r->headers_out}) {
             push @cookies, $v if lc $k eq 'set-cookie';
         }

       If anyone knows how Apache::Table does this, let us know! In the meantime, use "get()" or
       "do()" to get at all of the values for a given key ("get()" is much more efficient,
       anyway).

       Since the methods named for these attributes return an "HTML::Mason::FakeTable" object
       hash in a scalar reference, it seemed only fair to document its interface.

       ·   new()

           Returns a new "HTML::Mason::FakeTable" object. Any parameters passed to "new()" will
           be added to the table as initial values.

       ·   add()

           Adds a new value to the table. If the value did not previously exist under the given
           key, it will be created. Otherwise, it will be added as a new value to the key.

       ·   clear()

           Clears the table of all values.

       ·   do()

           Pass a code reference to this method to have it iterate over all of the key/value
           pairs in the table. Keys will multiple values will trigger the execution of the code
           reference multiple times for each value. The code reference should expect two
           arguments: a key and a value. Iteration terminates when the code reference returns
           false, to be sure to have it return a true value if you wan it to iterate over every
           value in the table.

       ·   get()

           Gets the value stored for a given key in the table. If a key has multiple values, all
           will be returned when "get()" is called in an array context, and only the first value
           when it is called in a scalar context.

       ·   merge()

           Merges a new value with an existing value by concatenating the new value onto the
           existing. The result is a comma-separated list of all of the values merged for a given
           key.

       ·   set()

           Takes key and value arguments and sets the value for that key. Previous values for
           that key will be discarded. The value must be a string, or "set()" will turn it into
           one. A value of "undef" will have the same behavior as "unset()".

       ·   unset()

           Takes a single key argument and deletes that key from the table, so that none of its
           values will be in the table any longer.