Chapter 4: APIs- P1
Mason is more than just a templating system. It provides a framework for
translating requests into output.
1
This framework has a number of
class/object APIs worth knowing about. You certainly won't need to use
most of these methods very often, but you will probably want to use at least
some of them in many of your Mason-based projects. This chapter
documents those APIs. For a more concise reference to these methods, see
Appendix B
.
Request Class and Object API
The request object in Mason represents the context of the current request
process. For example, it knows where in the component wrapping chain it is,
what arguments have been passed to various component calls, if you've been
bad or good, and so on. It also allows you to change that context in various
ways, such as by calling another component or aborting the request.
The request API provides access to some of the most frequently used Mason
features, particularly those relating to component calls, autohandlers, and
aborting in the middle of a request.
Recall, as first mentioned in Chapter 2
, that the Mason request object is
available in all components as $m.
The request class has only two class methods. The first,
HTML::Mason::Request->new() , is intended for use by other Mason
objects and is not documented for external use. If you want to make a new
request object, use the make_subrequest() method provided by the
request object, which is covered as part of the discussion of Mason's
subrequest mechanism in Chapter 5
.
The second class method, HTML::Mason::Request->instance() ,

This may be brief , text , line , or html . These produce an
error message with no trace, a multiline error with trace information, a
single-line error with tab-separated fields (suitable for writing to a
log), and a fancy HTML format.
Each of these methods corresponds to a method in the
HTML::Mason::Exception class, such as as_text() or
as_line(). You can create your own method in the
HTML::Mason::Exception namespace, such as
as_you_wish(), in which case you could set this parameter to
"you_wish." This method will receive a single argument, the
exception object, and is expected to return a string containing the
formatted error message.
In a mod_perl or CGI environment, this defaults to html format.
Otherwise, the default is text .
•
error_mode
This may be either fatal or output . In fatal mode, errors are
thrown as exceptions. In output mode, the exception is converted to a
text representation and sent to the same output stream as normal
content.
In a mod_perl or CGI environment, the default is output , which
means that errors go the client. In any other environment, the default
is fatal . If you set this to fatal in a web environment, errors will
end up in your web server's logs. If you wish to implement your own
exception-handling mechanism around Mason, set this to fatal and
catch the exceptions yourself.
•
max_recurse
This can be used to set the maximum stack size for component calls
and subrequests. It defaults to 32, which is likely to be more than

used to modify the way the component call is processed. Right now,
only one parameter -- store -- is accepted for this hash reference.
The value of the store key should be a reference to a scalar, into
which Mason will place the output for the component. For example:
$m->comp( { store => \$content },
'Hello.comp', to => 'World' );
The output of Hello.comp would be available in the $content
variable. This functionality is fundamentally the same as that provided
by the scomp() method except that it allows you to capture the
component's return value in addition to its output.
•
scomp(component, arguments)
This is exactly like the comp() method except that the called
component's output is returned as a string instead of being sent to the
output stream. This is analogous to the use of sprintf() instead of
printf() in C. Components called via this method go through all
of the normal steps of component execution.
If you have a component that generates output and has a return value
and you want to capture that output in a scalar, you should use the
store component call modifier.
•
content
This method is relevant only inside a component called with content, a
feature we saw briefly in Chapter 2
but will cover more completely in
Chapter 5
.
This method returns the block of content wrapped by the component
call. This will make more sense once you've read "Calling
Components with Content Blocks" in Chapter 5.

aborted_value
When aborted() is true, this method returns whatever value was
passed to the abort() call.
If you are using eval blocks for exception handling in your components, it is
important to propagate exceptions generated from a call to abort(). Here
is one way do this:
eval { $m->call_next(%ARGS) };
if ($@) {
if ($m->aborted) {
# pass this up to a higher level
die $@;
} else {
# something else that's bad happened
$m->comp( 'exception_handler', exception =>
$@ );
}
}

The Wrapping Chain
These are methods related to the wrapping chain, which was discussed in
Chapter 3
.
•
call_next(arguments)
When the currently executing component is part of a wrapping chain,
this method will call the next component in the chain, passing it the
current component's arguments and any arguments specified in the
call to call_next().
If there is no next component to call, it will throw an exception.
•

Miscellaneous Methods
The request object also has some general-use methods:
•
file(filename)
Given a file path, Mason will look for this file and return its contents
as a string.