{
    "mode": "info",
    "parameter": "HTML::Mason::Request",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/HTML%3A%3AMason%3A%3ARequest/json",
    "generated": "2026-07-05T13:35:30Z",
    "synopsis": "$m->abort (...)\n$m->comp (...)\netc.",
    "sections": {
        "NAME": {
            "content": "HTML::Mason::Request - Mason Request Class\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "$m->abort (...)\n$m->comp (...)\netc.\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "The Request API is your gateway to all Mason features not provided by\nsyntactic tags. Mason creates a new Request object for every web\nrequest. Inside a component you access the current request object via\nthe global $m.  Outside of a component, you can use the class method\n\"instance\".\n",
            "subsections": []
        },
        "COMPONENT PATHS": {
            "content": "The methods Request->comp, Request->compexists, and\nRequest->fetchcomp take a component path argument.  Component paths\nare like URL paths, and always use a forward slash (/) as the\nseparator, regardless of what your operating system uses.\n\no   If the path is absolute (starting with a '/'), then the component\nis found relative to the component root.\n\no   If the path is relative (no leading '/'), then the component is\nfound relative to the current component directory.\n\no   If the path matches both a subcomponent and file-based component,\nthe subcomponent takes precedence.\n\nPARAMETERS TO THE new() CONSTRUCTOR\nautoflush\nTrue or false, default is false. Indicates whether to flush the\noutput buffer (\"$m->flushbuffer\") after every string is output.\nTurn on autoflush if you need to send partial output to the client,\nfor example in a progress meter.\n\nAs of Mason 1.3, autoflush will only work if enableautoflush has\nbeen set.  Components can be compiled more efficiently if they\ndon't have to check for autoflush. Before using autoflush you might\nconsider whether a few manual \"$m->flushbuffer\" calls would work\nnearly as well.\n\ndatacacheapi\nThe \"$m->cache\" API to use:\n\no   '1.1', the default, indicates a \"Cache::Cache\" based API.\n\no   'chi' indicates a \"CHI\" based API.\n\no   '1.0' indicates the custom cache API used in Mason 1.0x and\nearlier. This compatibility layer is provided as a convenience\nfor users upgrading from older versions of Mason, but will not\nbe supported indefinitely.\n\ndatacachedefaults\nA hash reference of default options to use for the \"$m->cache\"\ncommand.  For example, to use Cache::Cache's \"MemoryCache\"\nimplementation by default:\n\ndatacachedefaults => {cacheclass => 'MemoryCache'}\n\nTo use the CHI \"FastMmap\" driver by default:\n\ndatacacheapi      => 'CHI',\ndatacachedefaults => {driver => 'FastMmap'},\n\nThese settings are overridden by options given to particular\n\"$m->cache\" calls.\n\ndhandlername\nFile name used for dhandlers. Default is \"dhandler\".  If this is\nset to an empty string (\"\") then dhandlers are turned off entirely.\n\nerrorformat\nIndicates how errors are formatted. The built-in choices are\n\no   brief - just the error message with no trace information\n\no   text - a multi-line text format\n\no   line - a single-line text format, with different pieces of\ninformation separated by tabs (useful for log files)\n\no   html - a fancy html format\n\nThe default format under Apache and CGI is either line or html\ndepending on whether the error mode is fatal or output,\nrespectively. The default for standalone mode is text.\n\nThe formats correspond to \"HTML::Mason::Exception\" methods named\nasformat. You can define your own format by creating an\nappropriately named method; for example, to define an \"xml\" format,\ncreate a method \"HTML::Mason::Exception::asxml\" patterned after\none of the built-in methods.\n\nerrormode\nIndicates how errors are returned to the caller.  The choices are\nfatal, meaning die with the error, and output, meaning output the\nerror just like regular output.\n\nThe default under Apache and CGI is output, causing the error to be\ndisplayed in the browser.  The default for standalone mode is\nfatal.\n\ncomponenterrorhandler\nA code reference used to handle errors thrown during component\ncompilation or runtime. By default, this is a subroutine that turns\nnon-exception object errors in components into exceptions. If this\nparameter is set to a false value, these errors are simply rethrown\nas-is.\n\nTurning exceptions into objects can be expensive, since this will\ncause the generation of a stack trace for each error. If you are\nusing strings or unblessed references as exceptions in your code,\nyou may want to turn this off as a performance boost.\n\nmaxrecurse\nThe maximum recursion depth for the component stack, for the\nrequest stack, and for the inheritance stack. An error is signalled\nif the maximum is exceeded.  Default is 32.\n\noutmethod\nIndicates where to send output. If outmethod is a reference to a\nscalar, output is appended to the scalar.  If outmethod is a\nreference to a subroutine, the subroutine is called with each\noutput string. For example, to send output to a file called\n\"mason.out\":\n\nmy $fh = new IO::File \">mason.out\";\n...\noutmethod => sub { $fh->print($[0]) }\n\nBy default, outmethod prints to standard output. Under Apache,\nstandard output is redirected to \"$r->print\".\n\nplugins\nAn array of plugins that will be called at various stages of\nrequest processing.  Please see HTML::Mason::Plugin for details.\n",
            "subsections": []
        },
        "ACCESSOR METHODS": {
            "content": "All of the above properties have standard accessor methods of the same\nname. In general, no arguments retrieves the value, and one argument\nsets and returns the value.  For example:\n\nmy $maxrecurselevel = $m->maxrecurse;\n$m->autoflush(1);\n",
            "subsections": []
        },
        "OTHER METHODS": {
            "content": "abort ([return value])\nEnds the current request, finishing the page without returning\nthrough components. The optional argument specifies the return\nvalue from \"Interp::exec\"; in a web environment, this ultimately\nbecomes the HTTP status code.\n\n\"abort\" is implemented by throwing an HTML::Mason::Exception::Abort\nobject and can thus be caught by eval(). The \"aborted\" method is a\nshortcut for determining whether a caught error was generated by\n\"abort\".\n\nIf \"abort\" is called from a component that has a \"<%filter>\", than\nany output generated up to that point is filtered, unless \"abort\"\nis called from a \"<%shared>\" block.\n\nclearandabort ([return value])\nThis method is syntactic sugar for calling \"clearbuffer()\" and\nthen \"abort()\".  If you are aborting the request because of an\nerror, you will often want to clear the buffer first so that any\noutput generated up to that point is not sent to the client.\n\naborted ([$err])\nReturns true or undef indicating whether the specified $err was\ngenerated by \"abort\". If no $err was passed, uses $@.\n\nIn this code, we catch and process fatal errors while letting\n\"abort\" exceptions pass through:\n\neval { codethatmayfailorabort() };\nif ($@) {\ndie $@ if $m->aborted;\n\n# handle fatal errors...\n\n$@ can lose its value quickly, so if you are planning to call\n$m->aborted more than a few lines after the eval, you should save\n$@ to a temporary variable.\n\nbasecomp\nReturns the current base component.\n\nHere are the rules that determine basecomp as you move from\ncomponent to component.\n\no   At the beginning of a request, the base component is\ninitialized to the requested component (\"$m->requestcomp()\").\n\no   When you call a regular component via a path, the base\ncomponent changes to the called component.\n\no   When you call a component method via a path (/foo/bar:baz), the\nbase component changes to the method's owner.\n\no   The base component does not change when:\n\no   a component call is made to a component object\n\no   a component call is made to SELF:x or PARENT:x or REQUEST:x\n\no   a component call is made to a subcomponent (<%def>)\n\nThis may return nothing if the base component is not yet known, for\nexample inside a plugin's \"startrequesthook()\" method, where we\nhave created a request but it does not yet know anything about the\ncomponent being called.\n\ncache\n\"$m->cache\" returns a new cache object with a namespace specific to\nthis component. The parameters to and return value from \"$m->cache\"\ndiffer depending on which datacacheapi you are using.\n\nIf datacacheapi = 1.1 (default)\ncacheclass specifies the class of cache object to create. It\ndefaults to \"FileCache\" in most cases, or \"MemoryCache\" if the\ninterpreter has no data directory, and must be a backend\nsubclass of \"Cache::Cache\". The prefix \"Cache::\" need not be\nincluded.  See the \"Cache::Cache\" package for a full list of\nbackend subclasses.\n\nBeyond that, cacheoptions may include any valid options to the\nnew() method of the cache class. e.g. for \"FileCache\", valid\noptions include \"defaultexpiresin\" and \"cachedepth\".\n\nSee HTML::Mason::Cache::BaseCache for information about the\nobject returned from \"$m->cache\".\n\nIf datacacheapi = CHI\nchirootclass specifies the factory class that will be called\nto create cache objects. The default is 'CHI'.\n\ndriver specifies the driver to use, for example \"Memory\" or\n\"FastMmap\".  The default is \"File\" in most cases, or \"Memory\"\nif the interpreter has no data directory.\n\nBeyond that, cacheoptions may include any valid options to the\nnew() method of the driver. e.g. for the \"File\" driver, valid\noptions include \"expiresin\" and \"depth\".\n\ncacheself ([expiresin => '...'], [key => '...'], [getoptions],\n[cacheoptions])\n\"$m->cacheself\" caches the entire output and return result of a\ncomponent.\n\n\"cacheself\" either returns undef, or a list containing the return\nvalue of the component followed by '1'. You should return\nimmediately upon getting the latter result, as this indicates that\nyou are inside the second invocation of the component.\n\n\"cacheself\" takes any of parameters to \"$m->cache\" (e.g.\ncachedepth), any of the optional parameters to \"$cache->get\"\n(expireif, busylock), and two additional options:\n\no   expirein or expiresin: Indicates when the cache expires - it\nis passed as the third argument to \"$cache->set\". e.g. '10\nsec', '5 min', '2 hours'.\n\no   key: An identifier used to uniquely identify the cache results\n- it is passed as the first argument to \"$cache->get\" and\n\"$cache->set\".  The default key is 'masoncacheself'.\n\nTo cache the component's output:\n\n<%init>\nreturn if $m->cacheself(expirein => '10 sec'[, key => 'fookey']);\n... <rest of init> ...\n</%init>\n\nTo cache the component's scalar return value:\n\n<%init>\nmy ($result, $cached) = $m->cacheself(expirein => '5 min'[, key => 'fookey']);\n\nreturn $result if $cached;\n... <rest of init> ...\n</%init>\n\nTo cache the component's list return value:\n\n<%init>\nmy (@retval) = $m->cacheself(expirein => '3 hours'[, key => 'fookey']);\n\nreturn @retval if pop @retval;\n... <rest of init> ...\n</%init>\n\nWe call \"pop\" on @retval to remove the mandatory '1' at the end of\nthe list.\n\nIf a component has a \"<%filter>\" block, then the filtered output is\ncached.\n\nNote: users upgrading from 1.0x and earlier can continue to use the\nold \"$m->cacheself\" API by setting datacacheapi to '1.0'.  This\nsupport will be removed at a later date.\n\nSee the the DATA CACHING section of the developer's manual section\nfor more details on how to exercise finer control over caching.\n\ncallerargs\nReturns the arguments passed by the component at the specified\nstack level. Use a positive argument to count from the current\ncomponent and a negative argument to count from the component at\nthe bottom of the stack. e.g.\n\n$m->callerargs(0)   # arguments passed to current component\n$m->callerargs(1)   # arguments passed to component that called us\n$m->callerargs(-1)  # arguments passed to first component executed\n\nWhen called in scalar context, a hash reference is returned.  When\ncalled in list context, a list of arguments (which may be assigned\nto a hash) is returned.  Returns undef or an empty list, depending\non context, if the specified stack level does not exist.\n\ncallers\nWith no arguments, returns the current component stack as a list of\ncomponent objects, starting with the current component and ending\nwith the top-level component. With one numeric argument, returns\nthe component object at that index in the list. Use a positive\nargument to count from the current component and a negative\nargument to count from the component at the bottom of the stack.\ne.g.\n\nmy @comps = $m->callers   # all components\n$m->callers(0)            # current component\n$m->callers(1)            # component that called us\n$m->callers(-1)           # first component executed\n\nReturns undef or an empty list, depending on context, if the\nspecified stack level does not exist.\n\ncaller\nA synonym for \"$m->callers(1)\", i.e. the component that called the\ncurrently executing component.\n\ncallnext ([args...])\nCalls the next component in the content wrapping chain; usually\ncalled from an autohandler. With no arguments, the original\narguments are passed to the component.  Any arguments specified\nhere serve to augment and override (in case of conflict) the\noriginal arguments. Works like \"$m->comp\" in terms of return value\nand scalar/list context.  See the autohandlers section of the\ndeveloper's manual for examples.\n\ncallself (output, return, error, tag)\nThis method allows a component to call itself so that it can filter\nboth its output and return values.  It is fairly advanced; for most\npurposes the \"<%filter>\" tag will be sufficient and simpler.\n\n\"$m->callself\" takes four arguments, all of them optional.\n\noutput - scalar reference that will be populated with the component\noutput.\nreturn - scalar reference that will be populated with the component\nreturn value.\nerror - scalar reference that will be populated with the error\nthrown by the component, if any. If this parameter is not defined,\nthen callself will not catch errors.\ntag - a name for this callself invocation; can almost always be\nomitted.\n\n\"$m->callself\" acts like a \"fork()\" in the sense that it will\nreturn twice with different values.  When it returns 0, you allow\ncontrol to pass through to the rest of your component.  When it\nreturns 1, that means the component has finished and you can\nexamine the output, return value and error. (Don't worry, it\ndoesn't really do a fork! See next section for explanation.)\n\nThe following examples would generally appear at the top of a\n\"<%init>\" section.  Here is a no-op \"$m->callself\" that leaves the\noutput and return value untouched:\n\n<%init>\nmy ($output, $retval);\nif ($m->callself(\\$output, \\$retval)) {\n$m->print($output);\nreturn $retval;\n}\n...\n\nHere is a simple output filter that makes the output all uppercase.\nNote that we ignore both the original and the final return value.\n\n<%init>\nmy ($output, $error);\nif ($m->callself(\\$output, undef)) {\n$m->print(uc $output);\nreturn;\n}\n...\n\nHere is a piece of code that traps all errors occurring anywhere in\na component or its children, e.g. for the purpose of handling\napplication-specific exceptions. This is difficult to do with a\nmanual \"eval\" because it would have to span multiple code sections\nand the main component body.\n\n<%init>\nmy ($output, undef, $error);\nif ($m->callself(\\$output, undef, \\$error)) {\nif ($error) {\n# check $error and do something with it\n}\n$m->print($output);\nreturn;\n}\n...\n\nclearbuffer\nClears the Mason output buffer. Any output sent before this line is\ndiscarded. Useful for handling error conditions that can only be\ndetected in the middle of a request.\n\nclearbuffer is, of course, thwarted by \"flushbuffer\".\n\ncomp (comp, args...)\nCalls the component designated by comp with the specified\noption/value pairs. comp may be a component path or a component\nobject.\n\nComponents work exactly like Perl subroutines in terms of return\nvalues and context. A component can return any type of value, which\nis then returned from the \"$m->comp\" call.\n\nThe <& &> tag provides a convenient shortcut for \"$m->comp\".\n\nAs of 1.10, component calls can accept an initial hash reference of\nmodifiers.  The only currently supported modifier is \"store\", which\nstores the component's output in a scalar reference. For example:\n\nmy $buf;\nmy $return = $m->comp( { store => \\$buf }, '/some/comp', type => 'big' );\n\nThis mostly duplicates the behavior of scomp, but can be useful in\nrare cases where you need to capture both a component's output and\nreturn value.\n\nThis modifier can be used with the <& &> tag as well, for example:\n\n<& { store => \\$buf }, '/some/comp', size => 'medium' &>\n\ncompexists (comppath)\nReturns 1 if comppath is the path of an existing component, 0\notherwise.  comppath may be any path accepted by comp or\nfetchcomp, including method or subcomponent paths.\n\nDepending on implementation, <compexists> may try to load the\ncomponent referred to by the path, and may throw an error if the\ncomponent contains a syntax error.\n\ncontent\nEvaluates the content (passed between <&| comp &> and </&> tags) of\nthe current component, and returns the resulting text.\n\nReturns undef if there is no content.\n\nhascontent\nReturns true if the component was called with content (i.e. with\n<&| comp &> and </&> tags instead of a single <& comp &> tag). This\nis generally better than checking the defined'ness of \"$m->content\"\nbecause it will not try to evaluate the content.\n\ncount\nReturns the number of this request, which is unique for a given\nrequest and interpreter.\n\ncurrentargs\nReturns the arguments passed to the current component. When called\nin scalar context, a hash reference is returned.  When called in\nlist context, a list of arguments (which may be assigned to a hash)\nis returned.\n\ncurrentcomp\nReturns the current component object.\n\ndecline\nUsed from a top-level component or dhandler, this method clears the\noutput buffer, aborts the current request and restarts with the\nnext applicable dhandler up the tree. If no dhandler is available,\na not-found error occurs.\n\nThis method bears no relation to the Apache DECLINED status except\nin name.\n\ndeclined ([$err])\nReturns true or undef indicating whether the specified $err was\ngenerated by \"decline\". If no $err was passed, uses $@.\n\ndepth\nReturns the current size of the component stack.  The lowest\npossible value is 1, which indicates we are in the top-level\ncomponent.\n\ndhandlerarg\nIf the request has been handled by a dhandler, this method returns\nthe remainder of the URI or \"Interp::exec\" path when the dhandler\ndirectory is removed. Otherwise returns undef.\n\n\"dhandlerarg\" may be called from any component in the request, not\njust the dhandler.\n\nexec (comp, args...)\nStarts the request by executing the top-level component and\narguments. This is normally called for you on the main request, but\nyou can use it to execute subrequests.\n\nA request can only be executed once; e.g. it is an error to call\nthis recursively on the same request.\n\nfetchcomp (comppath)\nGiven a comppath, returns the corresponding component object or\nundef if no such component exists.\n\nfetchnext\nReturns the next component in the content wrapping chain, or undef\nif there is no next component. Usually called from an autohandler.\nSee the autohandlers section of the developer's manual for usage\nand examples.\n\nfetchnextall\nReturns a list of the remaining components in the content wrapping\nchain. Usually called from an autohandler.  See the autohandlers\nsection of the developer's manual for usage and examples.\n\nfile (filename)\nReturns the contents of filename as a string. If filename is a\nrelative path, Mason prepends the current component directory.\n\nflushbuffer\nFlushes the Mason output buffer. Under modperl, also sends HTTP\nheaders if they haven't been sent and calls \"$r->rflush\" to flush\nthe Apache buffer. Flushing the initial bytes of output can make\nyour servers appear more responsive.\n\nAttempts to flush the buffers are ignored within the context of a\ncall to \"$m->scomp\" or when output is being stored in a scalar\nreference, as with the \" { store => \\$out } \" component call\nmodifier.\n\n\"<%filter>\" blocks will process the output whenever the buffers are\nflushed.  If \"autoflush\" is on, your data may be filtered in small\npieces.\n\ninstance\nThis class method returns the \"HTML::Mason::Request\" currently in\nuse.  If called when no Mason request is active it will return\n\"undef\".\n\nIf called inside a subrequest, it returns the subrequest object.\n\ninterp\nReturns the Interp object associated with this request.\n\nmakesubrequest (comp => path, args => arrayref, other parameters)\nThis method creates a new Request object which inherits its\nparent's settable properties, such as autoflush and outmethod.\nThese values may be overridden by passing parameters to this\nmethod.\n\nThe \"comp\" parameter is required, while all other parameters are\noptional.  It may be specified as an absolute path or as a path\nrelative to the current component.\n\nSee the subrequests section of the developer's manual for more\ninformation about subrequests.\n\nlog Returns a \"Log::Any\" logger with a log category specific to the\ncurrent component.  The category for a component \"/foo/bar\" would\nbe \"HTML::Mason::Component::foo::bar\".\n\nnotes (key, value)\nThe \"notes()\" method provides a place to store application data,\ngiving developers a way to share data among multiple components.\nAny data stored here persists for the duration of the request, i.e.\nthe same lifetime as the Request object.\n\nConceptually, \"notes()\" contains a hash of key-value pairs.\n\"notes($key, $value)\" stores a new entry in this hash.\n\"notes($key)\" returns a previously stored value.  \"notes()\" without\nany arguments returns a reference to the entire hash of key-value\npairs.\n\n\"notes()\" is similar to the modperl method \"$r->pnotes()\".  The\nmain differences are that this \"notes()\" can be used in a\nnon-modperl environment, and that its lifetime is tied to the\nMason request object, not the Apache request object.  In\nparticular, a Mason subrequest has its own \"notes()\" structure, but\nwould access the same \"$r->pnotes()\" structure.\n\nout (string)\nA synonym for \"$m->print\".\n\nprint (string)\nPrint the given string. Rarely needed, since normally all text is\njust placed in the component body and output implicitly.\n\"$m->print\" is useful if you need to output something in the middle\nof a Perl block.\n\nIn 1.1 and on, \"print\" and \"$r->print\" are remapped to \"$m->print\",\nso they may be used interchangeably. Before 1.1, one should only\nuse \"$m->print\".\n\nrequestargs\nReturns the arguments originally passed to the top level component\n(see requestcomp for definition).  When called in scalar context,\na hash reference is returned. When called in list context, a list\nof arguments (which may be assigned to a hash) is returned.\n\nrequestcomp\nReturns the component originally called in the request. Without\nautohandlers, this is the same as the first component executed.\nWith autohandlers, this is the component at the end of the\n\"$m->callnext\" chain.\n\nrequestdepth\nReturns the current size of the request/subrequest stack.  The\nlowest possible value is 1, which indicates we are in the top-level\nrequest.  A value of 2 indicates we are inside a subrequest of the\ntop-level request, and so on.\n\nscomp (comp, args...)\nLike comp, but returns the component output as a string instead of\nprinting it. (Think sprintf versus printf.) The component's return\nvalue is discarded.\n\nsubexec (comp, args...)\nThis method creates a new subrequest with the specified top-level\ncomponent and arguments, and executes it. This is most often used\nto perform an \"internal redirect\" to a new component such that\nautohandlers and dhandlers take effect.\n\ntime\nReturns the interpreter's notion of the current time (deprecated).\n",
            "subsections": []
        },
        "APACHE-ONLY METHODS": {
            "content": "These additional methods are available when running Mason with modperl\nand the ApacheHandler.\n\nah  Returns the ApacheHandler object associated with this request.\n\napachereq\nReturns the Apache request object.  This is also available in the\nglobal $r.\n\nautosendheaders\nTrue or false, default is true.  Indicates whether Mason should\nautomatically send HTTP headers before sending content back to the\nclient. If you set to false, you should call \"$r->sendhttpheader\"\nmanually.\n\nSee the sending HTTP headers section of the developer's manual for\nmore details about the automatic header feature.\n\nNOTE: This parameter has no effect under modperl-2, since calling\n\"$r->sendhttpheader\" is no longer needed.\n",
            "subsections": []
        },
        "CGI-ONLY METHODS": {
            "content": "This additional method is available when running Mason with the\nCGIHandler module.\n\ncgirequest\nReturns the Apache request emulation object, which is available as\n$r inside components.\n\nSee the CGIHandler docs for more details.\n",
            "subsections": []
        },
        "APACHE- OR CGI-ONLY METHODS": {
            "content": "This method is available when Mason is running under either the\nApacheHandler or CGIHandler modules.\n\ncgiobject\nReturns the CGI object used to parse any CGI parameters submitted\nto the component, assuming that you have not changed the default\nvalue of the ApacheHandler argsmethod parameter.  If you are using\nthe 'modperl' args method, then calling this method is a fatal\nerror.  See the ApacheHandler and CGIHandler documentation for more\ndetails.\n\nredirect ($url, [$status])\nGiven a url, this generates a proper HTTP redirect for that URL. It\nuses \"$m->clearandabort\" to clear out any previous output, and\nabort the request.  By default, the status code used is 302, but\nthis can be overridden by the user.\n\nSince this is implemented using \"$m->abort\", it will be trapped by\nan \" eval {} \" block.  If you are using an \" eval {} \" block in\nyour code to trap errors, you need to make sure to rethrow these\nexceptions, like this:\n\neval {\n...\n};\n\ndie $@ if $m->aborted;\n\n# handle other exceptions\n\nperl v5.30.2                      2020-05-22         HTML::Mason::Request(3pm)",
            "subsections": []
        }
    },
    "summary": "HTML::Mason::Request - Mason Request Class",
    "flags": [],
    "examples": [],
    "see_also": []
}