{
    "content": [
        {
            "type": "text",
            "text": "# HTML::Mason::CGIHandler (info)\n\n## NAME\n\nHTML::Mason::CGIHandler - Use Mason in a CGI environment\n\n## SYNOPSIS\n\nIn httpd.conf or .htaccess:\n<LocationMatch \"\\.html$\">\nAction html-mason /cgi-bin/masonhandler.cgi\nAddHandler html-mason .html\n</LocationMatch>\n<LocationMatch \"^/cgi-bin/\">\nRemoveHandler .html\n</LocationMatch>\n<FilesMatch \"(autohandler|dhandler)$\">\nOrder allow,deny\nDeny from all\n</FilesMatch>\nA script at /cgi-bin/masonhandler.pl :\n#!/usr/bin/perl\nuse HTML::Mason::CGIHandler;\nmy $h = HTML::Mason::CGIHandler->new\n(\ndatadir  => '/home/jethro/code/masondata',\nallowglobals => [qw(%session $u)],\n);\n$h->handlerequest;\nA .html component somewhere in the web server's document root:\n<%args>\n$mood => 'satisfied'\n</%args>\n% $r->errheaderout(Location => \"http://blahblahblah.com/moodring/$mood.html\");\n...\n\n## DESCRIPTION\n\nThis module lets you execute Mason components in a CGI environment.  It\nlets you keep your top-level components in the web server's document\nroot, using regular component syntax and without worrying about the\nparticular details of invoking Mason on each request.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "HTML::Mason::CGIHandler",
        "section": "",
        "mode": "info",
        "summary": "HTML::Mason::CGIHandler - Use Mason in a CGI environment",
        "synopsis": "In httpd.conf or .htaccess:\n<LocationMatch \"\\.html$\">\nAction html-mason /cgi-bin/masonhandler.cgi\nAddHandler html-mason .html\n</LocationMatch>\n<LocationMatch \"^/cgi-bin/\">\nRemoveHandler .html\n</LocationMatch>\n<FilesMatch \"(autohandler|dhandler)$\">\nOrder allow,deny\nDeny from all\n</FilesMatch>\nA script at /cgi-bin/masonhandler.pl :\n#!/usr/bin/perl\nuse HTML::Mason::CGIHandler;\nmy $h = HTML::Mason::CGIHandler->new\n(\ndatadir  => '/home/jethro/code/masondata',\nallowglobals => [qw(%session $u)],\n);\n$h->handlerequest;\nA .html component somewhere in the web server's document root:\n<%args>\n$mood => 'satisfied'\n</%args>\n% $r->errheaderout(Location => \"http://blahblahblah.com/moodring/$mood.html\");\n...",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 35,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 315,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "HTML::Mason::CGIHandler - Use Mason in a CGI environment\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "In httpd.conf or .htaccess:\n\n<LocationMatch \"\\.html$\">\nAction html-mason /cgi-bin/masonhandler.cgi\nAddHandler html-mason .html\n</LocationMatch>\n<LocationMatch \"^/cgi-bin/\">\nRemoveHandler .html\n</LocationMatch>\n<FilesMatch \"(autohandler|dhandler)$\">\nOrder allow,deny\nDeny from all\n</FilesMatch>\n\nA script at /cgi-bin/masonhandler.pl :\n\n#!/usr/bin/perl\nuse HTML::Mason::CGIHandler;\n\nmy $h = HTML::Mason::CGIHandler->new\n(\ndatadir  => '/home/jethro/code/masondata',\nallowglobals => [qw(%session $u)],\n);\n\n$h->handlerequest;\n\nA .html component somewhere in the web server's document root:\n\n<%args>\n$mood => 'satisfied'\n</%args>\n% $r->errheaderout(Location => \"http://blahblahblah.com/moodring/$mood.html\");\n...\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module lets you execute Mason components in a CGI environment.  It\nlets you keep your top-level components in the web server's document\nroot, using regular component syntax and without worrying about the\nparticular details of invoking Mason on each request.\n\nIf you want to use Mason components from within a regular CGI script\n(or any other Perl program, for that matter), then you don't need this\nmodule.  You can simply follow the directions in the Using Mason from a\nstandalone script section of the administrator's manual.\n\nThis module also provides an $r request object for use inside\ncomponents, similar to the Apache request object under\n\"HTML::Mason::ApacheHandler\", but limited in functionality.  Please\nnote that we aim to replicate the \"modperl\" functionality as closely\nas possible - if you find differences, do not depend on them to stay\ndifferent.  We may fix them in a future release.  Also, if you need\nsome missing functionality in $r, let us know, we might be able to\nprovide it.\n\nFinally, this module alters the \"HTML::Mason::Request\" object $m to\nprovide direct access to the CGI query, should such access be\nnecessary.\n\n\"HTML::Mason::CGIHandler\" Methods\no   new()\n\nCreates a new handler.  Accepts any parameter that the Interpreter\naccepts.\n\nIf no \"comproot\" parameter is passed to \"new()\", the component\nroot will be $ENV{DOCUMENTROOT}.\n\no   handlerequest()\n\nHandles the current request, reading input from $ENV{QUERYSTRING}\nor \"STDIN\" and sending headers and component output to \"STDOUT\".\nThis method doesn't accept any parameters.  The initial component\nwill be the one specified in $ENV{PATHINFO}.\n\no   handlecomp()\n\nLike \"handlerequest()\", but the first (only) parameter is a\ncomponent path or component object.  This is useful within a\ntraditional CGI environment, in which you're essentially using\nMason as a templating language but not an application server.\n\n\"handlecomponent()\" will create a CGI query object, parse the\nquery parameters, and send the HTTP header and component output to\nSTDOUT.  If you want to handle those parts yourself, see the Using\nMason from a standalone script section of the administrator's\nmanual.\n\no   handlecgiobject()\n\nAlso like \"handlerequest()\", but this method takes only a CGI\nobject as its parameter.  This can be quite useful if you want to\nuse this module with CGI::Fast.\n\nThe component path will be the value of the CGI object's\n\"pathinfo()\" method.\n\no   requestargs()\n\nGiven an \"HTML::Mason::FakeApache\" object, this method is expected\nto return a hash containing the arguments to be passed to the\ncomponent.  It is a separate method in order to make it easily\noverrideable in a subclass.\n\no   interp()\n\nReturns the Mason Interpreter associated with this handler.  The\nInterpreter lasts for the entire lifetime of the handler.\n\n$r Methods\no   headersin()\n\nThis works much like the \"Apache\" method of the same name. In an\narray context, it will return a %hash of response headers. In a\nscalar context, it will return a reference to the case-insensitive\nhash blessed into the \"HTML::Mason::FakeTable\" class. The values\ninitially populated in this hash are extracted from the CGI\nenvironment variables as best as possible. The pattern is to merely\nreverse the conversion from HTTP headers to CGI variables as\ndocumented here:\n<http://cgi-spec.golux.com/draft-coar-cgi-v11-03-clean.html#6.1>.\n\no   headerin()\n\nThis works much like the \"Apache\" method of the same name. When\npassed the name of a header, returns the value of the given\nincoming header. When passed a name and a value, sets the value of\nthe header. Setting the header to \"undef\" will actually unset the\nheader (instead of setting its value to \"undef\"), removing it from\nthe table of headers returned from future calls to \"headersin()\"\nor \"headerin()\".\n\no   headersout()\n\nThis works much like the \"Apache\" method of the same name. In an\narray context, it will return a %hash of response headers. In a\nscalar context, it will return a reference to the case-insensitive\nhash blessed into the \"HTML::Mason::FakeTable\" class. Changes made\nto this hash will be made to the headers that will eventually be\npassed to the \"CGI\" module's \"header()\" method.\n\no   headerout()\n\nThis works much like the \"Apache\" method of the same name.  When\npassed the name of a header, returns the value of the given\noutgoing header.  When passed a name and a value, sets the value of\nthe header.  Setting the header to \"undef\" will actually unset the\nheader (instead of setting its value to \"undef\"), removing it from\nthe table of headers that will be sent to the client.\n\nThe headers are eventually passed to the \"CGI\" module's \"header()\"\nmethod.\n\no   errheadersout()\n\nThis works much like the \"Apache\" method of the same name. In an\narray context, it will return a %hash of error response headers. In\na scalar context, it will return a reference to the case-\ninsensitive hash blessed into the \"HTML::Mason::FakeTable\" class.\nChanges made to this hash will be made to the error headers that\nwill eventually be passed to the \"CGI\" module's \"header()\" method.\n\no   errheaderout()\n\nThis works much like the \"Apache\" method of the same name. When\npassed the name of a header, returns the value of the given\noutgoing error header. When passed a name and a value, sets the\nvalue of the error header. Setting the header to \"undef\" will\nactually unset the header (instead of setting its value to\n\"undef\"), removing it from the table of headers that will be sent\nto the client.\n\nThe headers are eventually passed to the \"CGI\" module's \"header()\"\nmethod.\n\nOne header currently gets special treatment - if you set a\n\"Location\" header, you'll cause the \"CGI\" module's \"redirect()\"\nmethod to be used instead of the \"header()\" method.  This means\nthat in order to do a redirect, all you need to do is:\n\n$r->errheaderout(Location => 'http://redirect.to/here');\n\nYou may be happier using the \"$m->redirect\" method, though, because\nit hides most of the complexities of sending headers and getting\nthe status code right.\n\no   contenttype()\n\nWhen passed an argument, sets the content type of the current\nrequest to the value of the argument.  Use this method instead of\nsetting a \"Content-Type\" header directly with \"headerout()\".  Like\n\"headerout()\", setting the content type to \"undef\" will remove any\ncontent type set previously.\n\nWhen called without arguments, returns the value set by a previous\ncall to \"contenttype()\".  The behavior when \"contenttype()\"\nhasn't already been set is undefined - currently it returns\n\"undef\".\n\nIf no content type is set during the request, the default MIME type\n\"text/html\" will be used.\n\no   method()\n\nReturns the request method used for the current request, e.g.,\n\"GET\", \"POST\", etc.\n\no   httpheader()\n\nThis method returns the outgoing headers as a string, suitable for\nsending to the client.\n\no   sendhttpheader()\n\nSends the outgoing headers to the client.\n\no   notes()\n\nThis works much like the \"Apache\" method of the same name. When\npassed a $key argument, it returns the value of the note for that\nkey. When passed a $value argument, it stores that value under the\nkey. Keys are case-insensitive, and both the key and the value must\nbe strings. When called in a scalar context with no $key argument,\nit returns a hash reference blessed into the\n\"HTML::Mason::FakeTable\" class.\n\no   pnotes()\n\nLike \"notes()\", but takes any scalar as an value, and stores the\nvalues in a case-sensitive hash.\n\no   subprocessenv()\n\nWorks like the \"Apache\" method of the same name, but is simply\npopulated with the current values of the environment. Still, it's\nuseful, because values can be changed and then seen by later\ncomponents, but the environment itself remains unchanged. Like the\n\"Apache\" method, it will reset all of its values to the current\nenvironment again if it's called without a $key argument.\n\no   params()\n\nThis method returns a hash containing the parameters sent by the\nclient.  Multiple parameters of the same name are represented by\narray references.  If both POST and query string arguments were\nsubmitted, these will be merged together.\n\nAdded $m methods\nThe $m object provided in components has all the functionality of the\nregular \"HTML::Mason::Request\" object $m, and the following:\n\no   cgiobject()\n\nReturns the current \"CGI\" request object.  This is handy for\nprocessing cookies or perhaps even doing HTML generation (but is\nthat really what you want to do?).  If you pass an argument to this\nmethod, you can set the request object to the argument passed.  Use\nthis with care, as it may affect components called after the\ncurrent one (they may check the content length of the request, for\nexample).\n\nNote that the ApacheHandler class (for using Mason under modperl)\nalso provides a \"cgiobject()\" method that does the same thing as\nthis one.  This makes it easier to write components that function\nequally well under CGIHandler and ApacheHandler.\n\no   cgirequest()\n\nReturns the object that is used to emulate Apache's request object.\nIn other words, this is the object that $r is set to when you use\nthis class.\n\n\"HTML::Mason::FakeTable\" Methods\nThis class emulates the behavior of the \"Apache::Table\" class, and is\nused to store manage the tables of values for the following attributes\nof <$r>:\n\nheadersin\nheadersout\nerrheadersout\nnotes\nsubprocessenv\n\n\"HTML::Mason::FakeTable\" is designed to behave exactly like\n\"Apache::Table\", and differs in only one respect. When a given key has\nmultiple values in an \"Apache::Table\" object, one can fetch each of the\nvalues for that key using Perl's \"each\" operator:\n\nwhile (my ($k, $v) = each %{$r->headersout}) {\npush @cookies, $v if lc $k eq 'set-cookie';\n}\n\nIf anyone knows how Apache::Table does this, let us know! In the\nmeantime, use \"get()\" or \"do()\" to get at all of the values for a given\nkey (\"get()\" is much more efficient, anyway).\n\nSince the methods named for these attributes return an\n\"HTML::Mason::FakeTable\" object hash in a scalar reference, it seemed\nonly fair to document its interface.\n\no   new()\n\nReturns a new \"HTML::Mason::FakeTable\" object. Any parameters\npassed to \"new()\" will be added to the table as initial values.\n\no   add()\n\nAdds a new value to the table. If the value did not previously\nexist under the given key, it will be created. Otherwise, it will\nbe added as a new value to the key.\n\no   clear()\n\nClears the table of all values.\n\no   do()\n\nPass a code reference to this method to have it iterate over all of\nthe key/value pairs in the table. Keys will multiple values will\ntrigger the execution of the code reference multiple times for each\nvalue. The code reference should expect two arguments: a key and a\nvalue. Iteration terminates when the code reference returns false,\nto be sure to have it return a true value if you wan it to iterate\nover every value in the table.\n\no   get()\n\nGets the value stored for a given key in the table. If a key has\nmultiple values, all will be returned when \"get()\" is called in an\narray context, and only the first value when it is called in a\nscalar context.\n\no   merge()\n\nMerges a new value with an existing value by concatenating the new\nvalue onto the existing. The result is a comma-separated list of\nall of the values merged for a given key.\n\no   set()\n\nTakes key and value arguments and sets the value for that key.\nPrevious values for that key will be discarded. The value must be a\nstring, or \"set()\" will turn it into one. A value of \"undef\" will\nhave the same behavior as \"unset()\".\n\no   unset()\n\nTakes a single key argument and deletes that key from the table, so\nthat none of its values will be in the table any longer.\n\nperl v5.30.2                      2020-05-22      HTML::Mason::CGIHandler(3pm)",
                "subsections": []
            }
        }
    }
}