Provided by: libhtml-mason-perl_1.60-2_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" Methodsnew()

           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 Methodsheaders_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.

perl v5.38.2                                       2024-03-05                       HTML::Mason::CGIHandler(3pm)