O'Reilly logo

Embedding Perl in HTML with Mason by Ken Williams, Dave Rolsky

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required


The Request class represents a chain of components executing in a particular context. A request is begun by invoking the Interpreter’s exec( ) method. The current Request object is available by default in components as the variable $m.


Creates a new Request object. See Appendix B for a list of parameters accepted. Typically a Request is not created directly, but rather by invoking the Interpreter’s exec( ) method. The default Request class is HTML::Mason::Request , though it is different when using ApacheHandler or CGIHandler.

instance( )

Returns the Request currently running. This can be called as a class method (i.e., HTML::Mason::Interp->instance( )) from code in which $m is unavailable. In a subrequest, the subrequest object, not the main request, will be returned.

Object Properties

interp( )

Returns the Interpreter object associated with this Request.

count( )

Returns the Interpreter’s counter value for this Request.

error_mode([<'fatal’ or ‘output'>])

Returns the string fatal or output, depending on whether error conditions should trigger an exception (fatal) or display an error message in the regular output channel (output). The mode can be set with an optional argument.


Returns a string indicating how error messages will be formatted. The currently available choices are brief, text, line, and html. An optional argument sets the format.

out_method([<subroutine_reference or scalar_reference>])

Returns the current value of the out_method parameter or optionally sets it if you pass a subroutine reference or a scalar reference as an argument.

cgi_object( )

This method is not present in the regular HTML::Mason::Request class, but it is added as a way to access the CGI.pm request object when using HTML::Mason::CGIHandler. It is also added when using HTML::Mason::ApacheHandler with the CGI args_method.


Only available when using HTML::Mason::ApacheHandler, in which case the Apache Handler object is returned.


Only available when using HTML::Mason::ApacheHandler, in which case the mod_perl request object $r is returned.

Altering the Request Flow


Terminates the current Request. You may optionally specify a value to be returned by the Interpreter’s exec( ) method. In a web environment this value will ultimately become the HTTP response code. Accepts an optional exception argument to examine, otherwise $@ will be examined.

aborted( )

Returns true if the current request was aborted (and caught by an eval block), or false otherwise. Accepts an exception argument to examine, otherwise $@ will be examined.

aborted_value( )

If the current request was aborted, this returns the value passed to the abort method.

decline( )

Stops the execution of the current component and passes control to the next applicable dhandler. Any output already generated will be discarded. If no dhandler exists to handle this request, an exception will be thrown.

dhandler_arg( )

If the current request is being handled by a dhandler, this method will return the remainder of the request path with the dhandler’s directory removed. If no dhandler is executing, this method will return undef.


See Chapter 4 for more information on the data cache and how to use it.


Returns the Cache::Cache object that manages this component’s data cache.


Facilitates automatic caching of the current component’s output and return value. The arguments to cache_self( ) specify how long the cached data should persist, whether it should be associated with a particular key, and the details of how the data should be cached.


caller( )

Returns the component that invoked the currently executing component or undef if this is the topmost component executing.


When called with no arguments, returns a list of all components currently executing. This is known as the ‘component stack.’ When called with an integer argument n, returns the component n levels up the execution stack. For instance, $m->callers(1) is equivalent to $m->caller.


Given an integer argument n, returns an array (if called in list context) or a hash reference (if called in scalar context) of the arguments passed to the component n levels up the execution stack.

depth( )

Returns the current depth of the component stack. For instance, with components /autohandler, /dir/autohandler, and /dir/component.html in the default setup, the depth will be 1 when queried in /autohandler, 2 in /dir/autohandler, and 3 in /dir/component.html. If /dir/component.html calls another component, the depth will be 4 inside that component.

Content and Output


A synonym for print( ). This method will output the content of any arguments. In recent versions of Mason you may also print to Perl’s STDOUT filehandle, as this is tied to Mason’s buffers.

clear_buffer( )

Discards the contents of Mason’s output buffers.

flush_buffer( )

Sends the contents of Mason’s output buffers to their destination.

content( )

Returns the content block passed to the current component or undef if this component was called without a content block. The content block will be evaluated in the lexical context of the calling component. See Section in Chapter 2 for more details.


Given a file path, Mason will look for this file and return its contents as a string.

An absolute path refers to a file on the filesystem. If a relative path is given, Mason will prepend the current component’s directory, if it has one. Otherwise Mason will simply make the path absolute by prepending the system’s root directory to the path.

Fetching/Running Components

These methods deal with fetching and running components. Some of the methods (in particular comp( ) and scomp( )) let you specify the component by path or by supplying a component object, while other methods (fetch_comp( ) and comp_exists( )) allow only a path. For any of these four methods, if a relative pathname is given, it is considered relative to the dir_path of the current component.


Given a string argument specifying a component path, returns the component at that path or undef if no such component exists.

fetch_next( )

Fetches the next component in the content-wrapping chain. This is the same component that will be invoked by the call_next( ) method.

fetch_next_all( )

Fetches all remaining components in the content-wrapping chain and returns them as a list. This is usually called from an autohandler and will return multiple components when multiple autohandlers are in use.

comp(<component>, <arguments...>)

Calls a Mason component. The component is specified by the first argument, which should be either the name of the component to call or a component object. Any remaining arguments to comp( ) are fed to the called component, either as key/value pairs declared in the component’s <%args> section, the special %ARGS variable, or the Perl argument array @_. Any component output will be sent to the current component’s output stream, and the component’s return value will become the return value of comp( ).

scomp(<component>, <arguments...>)

Identical to the comp( ) method, but instead of sending the called component’s output to the output stream, is returned as a string. Any return value from the component will be discarded.


Given a string argument, returns true if a component exists with that path or false otherwise.


Calls the next component in the component execution stack. Typically this is used by an autohandler to call the component it is wrapping around. Mason will pass any current component arguments (the %ARGS hash) to the next component, as well as any additional arguments passed to the call_next( ) method.

current_comp( )

Returns an object representing the currently executing component.

request_comp( )

Returns an object representing the component that was originally requested in the Interpreter’s exec( ) method.

base_comp( )

Returns the current base component for methods and attributes. The base component is initially set to the request_comp( ). Calling a component method will set the base component to the component used in the method call. Calling a regular (nonmethod) component will set the base component to the called component.

request_args( )

Returns the arguments passed to the originally requested component. If called in a list context, the arguments will be returned as a list. If called in a scalar context, the arguments will be returned as a hash reference.


make_subrequest(comp => <path>, args => [...], <parameters...>)

Returns a new Request object with the given parameters. Other parameters will be inherited from the current request.

exec( )

Sets the new request in motion with the given arguments passed to the given component. This should be used only when the request was created with the make_subrequest( ) method, since exec( ) can happen only once for each request. In particular, it is illegal to call $m->exec(...) inside a component.

subexec(<component>, <arguments...>)

Combines the make_subrequest and exec methods into one step. Any arguments are passed to the given component, and the subrequest created will inherit all inheritable properties from the current request.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required