{
    "mode": "perldoc",
    "parameter": "HTML::Mason::Interp",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/HTML%3A%3AMason%3A%3AInterp/json",
    "generated": "2026-06-12T23:04:37Z",
    "synopsis": "my $i = HTML::Mason::Interp->new (datadir=>'/usr/local/mason',\ncomproot=>'/usr/local/www/htdocs/',\n...other params...);",
    "sections": {
        "NAME": {
            "content": "HTML::Mason::Interp - Mason Component Interpreter\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "my $i = HTML::Mason::Interp->new (datadir=>'/usr/local/mason',\ncomproot=>'/usr/local/www/htdocs/',\n...other params...);\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Interp is the Mason workhorse, executing components and routing their output and errors to all\nthe right places. In a modperl environment, Interp objects are handed off immediately to an\nApacheHandler object which internally calls the Interp implementation methods. In that case the\nonly user method is the new() constructor.\n\nPARAMETERS TO THE new() CONSTRUCTOR\nautohandlername\nFile name used for autohandlers. Default is \"autohandler\". If this is set to an empty string\n(\"\") then autohandlers are turned off entirely.\n\nbufferpreallocatesize\nNumber of bytes to preallocate in the output buffer for each request. Defaults to 0. Setting\nthis to, say, your maximum page size (or close to it) can reduce the number of reallocations\nPerl performs as components add to the output buffer.\n\ncodecachemaxsize\nSpecifies the maximum number of components that should be held in the in-memory code cache.\nThe default is 'unlimited', meaning no components will ever be discarded; Mason can perform\ncertain optimizations in this mode. Setting this to zero disables the code cache entirely.\nSee the code cache section of the administrator's manual for further details.\n\ncomproot\nThe component root marks the top of your component hierarchy and defines how component paths\nare translated into real file paths. For example, if your component root is\n/usr/local/httpd/docs, a component path of /products/index.html translates to the file\n/usr/local/httpd/docs/products/index.html.\n\nUnder Apache and CGI, comproot defaults to the server's document root. In standalone mode\ncomproot defaults to the current working directory.\n\nThis parameter may be either a scalar or an array reference. If it is a scalar, it should be\na filesystem path indicating the component root. If it is an array reference, it should be\nof the following form:\n\n[ [ foo => '/usr/local/foo' ],\n[ bar => '/usr/local/bar' ] ]\n\nThis is an array of two-element array references, not a hash. The \"keys\" for each path must\nbe unique and their \"values\" must be filesystem paths. These paths will be searched in the\nprovided order whenever a component path is resolved. For example, given the above component\nroots and a component path of /products/index.html, Mason would search first for\n/usr/local/foo/products/index.html, then for /usr/local/bar/products/index.html.\n\nThe keys are used in several ways. They help to distinguish component caches and object\nfiles between different component roots, and they appear in the \"title()\" of a component.\n\nWhen you specify a single path for a component root, this is actually translated into\n\n[ [ MAIN => path ] ]\n\nIf you have turned on dynamiccomproot, you may modify the component root(s) of an\ninterpreter between requests by calling \"$interp->comproot\" with a value. However, the path\nassociated with any given key may not change between requests. For example, if the initial\ncomponent root is\n\n[ [ foo => '/usr/local/foo' ],\n[ bar => '/usr/local/bar' ], ]\n\nthen it may not be changed to\n\n[ [ foo => '/usr/local/bar' ],\n[ bar => '/usr/local/baz' ],\n\nbut it may be changed to\n\n[ [ foo   => '/usr/local/foo' ],\n[ blarg => '/usr/local/blarg' ] ]\n\nIn other words, you may add or remove key/path pairs but not modify an already-used key/path\npair. The reason for this restriction is that the interpreter maintains a component cache\nper key that would become invalid if the associated paths were to change.\n\ncompiler\nThe Compiler object to associate with this Interpreter. By default a new object of class\ncompilerclass will be created.\n\ncompilerclass\nThe class to use when creating a compiler. Defaults to HTML::Mason::Compiler.\n\ndatadir\nThe data directory is a writable directory that Mason uses for various features and\noptimizations: for example, component object files and data cache files. Mason will create\nthe directory on startup, if necessary, and set its permissions according to the web server\nUser/Group.\n\nUnder Apache, datadir defaults to a directory called \"mason\" under the Apache server root.\nYou will need to change this on certain systems that assign a high-level server root such as\n/usr!\n\nIn non-Apache environments, datadir has no default. If it is left unspecified, Mason will\nnot use object files, and the default data cache class will be \"MemoryCache\" instead of\n\"FileCache\".\n\ndynamiccomproot\nTrue or false, defaults to false. Indicates whether the comproot can be modified on this\ninterpreter between requests. Mason can perform a few optimizations with a fixed component\nroot, so you should only set this to true if you actually need it.\n\nescapeflags\nA hash reference of escape flags to set for this object. See the section on the setescape\nmethod for more details.\n\nignorewarningsexpr\nRegular expression indicating which warnings to ignore when loading components. Any warning\nthat is not ignored will prevent the component from being loaded and executed. For example:\n\nignorewarningsexpr =>\n'Global symbol.*requires explicit package'\n\nIf set to undef, all warnings are heeded. If set to '.', warnings are turned off completely\nas a specially optimized case.\n\nBy default, this is set to 'Subroutine .* redefined'. This allows you to declare global\nsubroutines inside <%once> sections and not receive an error when the component is reloaded.\n\nobjectfileextension\nExtension to add to the end of object files. Default is \".obj\".\n\npreloads\nA list of component paths, optionally with glob wildcards, to load when the interpreter\ninitializes. e.g.\n\npreloads => ['/foo/index.html','/bar/*.pl']\n\nDefault is the empty list. For maximum performance, this should only be used for components\nthat are frequently viewed and rarely updated. See the preloading components section of the\nadministrator's manual for further details.\n\nAs mentioned in the developer's manual, a component's \"<%once>\" section is executed when it\nis loaded. For preloaded components, this means that this section will be executed before a\nMason or Apache request exist, so preloading a component that uses $m or $r in a \"<%once>\"\nsection will fail.\n\nrequestclass\nThe class to use when creating requests. Defaults to HTML::Mason::Request.\n\nresolver\nThe Resolver object to associate with this Compiler. By default a new object of class\nresolverclass will be created.\n\nresolverclass\nThe class to use when creating a resolver. Defaults to HTML::Mason::Resolver::File.\n\nstaticsource\nTrue or false, default is false. When false, Mason checks the timestamp of the component\nsource file each time the component is used to see if it has changed. This provides the\ninstant feedback for source changes that is expected for development. However it does entail\na file stat for each component executed.\n\nWhen true, Mason assumes that the component source tree is unchanging: it will not check\ncomponent source files to determine if the memory cache or object file has expired. This can\nsave many file stats per request. However, in order to get Mason to recognize a component\nsource change, you must flush the memory cache and remove object files. See\nstaticsourcetouchfile for one easy way to arrange this.\n\nWe recommend turning this mode on in your production sites if possible, if performance is of\nany concern.\n\nstaticsourcetouchfile\nSpecifies a filename that Mason will check once at the beginning of of every request. When\nthe file timestamp changes, Mason will (1) clear its in-memory component cache, and (2)\nremove object files if they have not already been deleted by another process.\n\nThis provides a convenient way to implement staticsource mode. All you need to do is make\nsure that a single file gets touched whenever components change. For Mason's part, checking\na single file at the beginning of a request is much cheaper than checking every component\nfile when staticsource=0.\n\nuseobjectfiles\nTrue or false, default is true. Specifies whether Mason creates object files to save the\nresults of component parsing. You may want to turn off object files for disk space reasons,\nbut otherwise this should be left alone.\n",
            "subsections": []
        },
        "ACCESSOR METHODS": {
            "content": "All of the above properties have standard accessor methods of the same name. Only comproot and\nignorewarningsexpr can be modified in an existing interpreter; the rest are read-only.\n",
            "subsections": []
        },
        "ESCAPE FLAG METHODS": {
            "content": "applyescapes ($text, $flags, [more flags...])\nThis method applies a one or more escapes to a piece of text. The escapes are specified by\ngiving their flag. Each escape is applied to the text in turn, after which the now-modified\ntext is returned.\n\nremoveescape ($name)\nGiven an escape name, this removes that escape from the interpreter's known escapes. If the\nname is not recognized, it is simply ignored.\n\nsetescape ($name => see below])\nThis method is called to add an escape flag to the list of known escapes for the\ninterpreter. The flag may only consist of the characters matching \"\\w\" and the dash (-). It\nmust start with an alpha character or an underscore ().\n\nThe right hand side may be one of several things. It can be a subroutine reference. It can\nalso be a string match \"/^\\w+$/\", in which case it is assumed to be the name of a subroutine\nin the \"HTML::Mason::Escapes\" module. Finally, if it is a string that does not match the\nabove regex, then it is assumed to be \"eval\"able code, which will return a subroutine\nreference.\n\nWhen setting these with \"PerlSetVar\" directives in an Apache configuration file, you can set\nthem like this:\n\nPerlSetVar  MasonEscapeFlags  \"h => \\&HTML::Mason::Escapes::basichtmlescape\"\nPerlSetVar  MasonEscapeFlags  \"flag  => \\&subroutine\"\nPerlSetVar  MasonEscapeFlags  \"uc    => sub { ${$[0]} = uc ${$[0]}; }\"\nPerlAddVar  MasonEscapeFlags  \"thing => otherthing\"\n",
            "subsections": []
        },
        "OTHER METHODS": {
            "content": "compexists (path)\nGiven an *absolute* component path, this method returns a boolean value indicating whether\nor not a component exists for that path.\n\nexec (comp, args...)\nCreates a new HTML::Mason::Request object for the given *comp* and *args*, and executes it.\nThe return value is the return value of *comp*, if any.\n\nThis is useful for running Mason outside of a web environment. See \"using Mason from a\nstandalone script\" in HTML::Mason::Admin for examples.\n\nThis method isn't generally useful in a modperl environment; see subrequests instead.\n\nflushcodecache\nEmpties the component cache. When using Perl 5.00503 or earlier, you should call this when\nfinished with an interpreter, in order to remove circular references that would prevent the\ninterpreter from being destroyed.\n\nload (path)\nReturns the component object corresponding to an absolute component \"path\", or undef if none\nexists. Dies with an error if the component fails to load because of a syntax error.\n\nmakecomponent (compsource => ... )\nmakecomponent (compfile => ... )\nThis method compiles Mason component source code and returns a Component object. The source\nmay be passed in as a string in \"compsource\", or as a filename in \"compfile\". When using\n\"compfile\", the filename is specified as a path on the file system, not as a path relative\nto Mason's component root (see $m->fetchcomp for that).\n\nIf Mason encounters an error during processing, an exception will be thrown.\n\nExample of usage:\n\n# Make an anonymous component\nmy $anoncomp =\neval { $interp->makecomponent\n( compsource => '<%perl>my $name = \"World\";</%perl>Hello <% $name %>!' ) };\ndie $@ if $@;\n\n$m->comp($anoncomp);\n\nmakerequest (@requestparams)\nThis method creates a Mason request object. The arguments to be passed are the same as those\nfor the \"HTML::Mason::Request->new\" constructor or its relevant subclass. This method will\nlikely only be of interest to those attempting to write new handlers or to subclass\n\"HTML::Mason::Interp\". If you want to create a *subrequest*, see subrequests instead.\n\npurgecodecache ()\nCalled during request execution in order to clear out the code cache. Mainly useful to\nsubclasses that may want to take some custom action upon clearing the cache.\n\nsetglobal ($varname, [values...])\nThis method sets a global to be used in components. \"varname\" is a variable name, optionally\npreceded with a prefix (\"$\", \"@\", or \"%\"); if the prefix is omitted then \"$\" is assumed.\n\"varname\" is followed by a value, in the case of a scalar, or by one or more values in the\ncase of a list or hash. For example:\n\n# Set a global variable $dbh containing the database handle\n$interp->setglobal(dbh => DBI->connect(...));\n\n# Set a global hash %session from a local hash\n$interp->setglobal('%session', %s);\n\nThe global is set in the package that components run in: usually \"HTML::Mason::Commands\",\nalthough this can be overridden via the inpackage parameter. The lines above, for example,\nare equivalent to:\n\n$HTML::Mason::Commands::dbh = DBI->connect(...);\n%HTML::Mason::Commands::session = %s;\n\nassuming that inpackage has not been changed.\n\nAny global that you set should also be registered with the allowglobals parameter;\notherwise you'll get warnings from \"strict\".\n",
            "subsections": []
        }
    },
    "summary": "HTML::Mason::Interp - Mason Component Interpreter",
    "flags": [],
    "examples": [],
    "see_also": []
}