Table of Contents | Foreword | Preface
Chapters: 1 2 3 4 5 6 7 8 9 10 11 12
Appendices: A B C D
Glossary | Colophon | Copyright

Appendix A: The Mason API

To provide a convenient reference to the main elements of the Mason class hierarchy, we've collected the APIs of the Interpreter, Resolver, Compiler, Lexer, ApacheHandler, CGIHandler, Component, and Request classes. The parameters to each class's new() method are listed in Appendix B. Many of these parameters also correspond to simple accessor methods for getting/setting their values; those methods are not listed here, so see Appendix B for a complete list.

We have attempted to show the arguments taken by each method. Replaceable text is shown in angle brackets (<>). indicating a value you must specify. An ellipsis (...) indicates a list of values. Optional arguments are indicated by square brackets ([]). An optional list of arguments doesn't get both kinds of brackets, because we figure that's just a list with no elements in it. If alternate sets of parameters can be given (such as comp_source versus comp_file for the Interpreter's make_component() method), we sometimes indicate this by separate listings.

We intend this appendix to be a quick reference; in many cases the official Mason documentation will provide more detail.

Interpreter

The Interpreter is the main entry point for

Mason and coordinates the efforts of several other classes. The default Interpreter class is HTML::Mason::Interp .

Object Properties

Directories

Runtime Methods

Request

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.

Object Properties

Altering the Request Flow

Caching

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

Introspection

Content and Output

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.

Subrequests

Component

This class represents a Mason component. It may be a file-based component on disk, a component created on the fly, or a method or subcomponent. The default Component class is HTML::Mason::Component::FileBased.

Object Properties

Component Relationships

Inheritance

Resolver

The Resolver is responsible for handling the interactions between the Interpreter and the storage medium of component source files. The default resolver class is HTML::Mason::Resolver::File.

ApacheHandler

The HTML::Mason::ApacheHandler class provides the necessary glue between the Mason Interpreter and the Apache web server's mod_perl module. Its main task is to accept an incoming Apache request and invoke the Interpreter with the proper parameters for handling that request.

The ApacheHandler class makes the Apache request object available inside components as the global variable $r . This may be an object blessed into the Apache::Request class or the Apache class, depending on whether the Mason administrator has configured the ApacheHandler to use the mod_perlargs_method.

ApacheHandler also turns $m, the Request object, into an HTML::Mason::Request::ApacheHandler object by subclassing HTML::Mason::Request.

CGIHandler

The HTML::Mason::CGIHandler class is similar to ApacheHandler but runs under the CGI paradigm instead of the mod_perl paradigm. Its task is to accept an incoming CGI request and invoke the Mason Interpreter with the proper parameters for handling that request.

CGIHandler also turns $r, normally the Apache request object, into an HTML::Mason::FakeApache object. It provides the following methods for compatibility with a mod_perl-based setup:

Compiler

The Compiler is

responsible for turning a hierarchical component structure, as fed to it by the Lexer, into a usable form. The default Compiler is HTML::Mason::Compiler::ToObject, which creates a Component object.

Object Properties

Compilation Callbacks

These are methods called by the Lexer while processing a component source. You may wish to override some of these methods if you're implementing your own custom Compiler class.

Lexer

The Mason Lexer has a very limited API, because it is mostly subservient to (and hidden by) the Compiler. The Compiler calls the Lexer's new() and lex() methods, then the Lexer calls various Compiler methods to generate the component. The Lexer has more methods than are listed here, but they're internal methods and should not be considered part of its formal API. The default Lexer class is HTML::Mason::Lexer.