Embedding Perl in HTML with Mason: Appendix A

# 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` .

- new(<parameters...>)

  Creates a new Mason Interpreter and returns it. See Appendix B for a list of parameters accepted.

### Object Properties

- compiler()

  Returns the Compiler object associated with this Interpreter.

- resolver()

  Returns the Resolver object associated with this Interpreter.

- static_source()

  Returns true or false, depending on whether the `static_source` parameter is currently set for this Interpreter.

- autoflush([<true or false>])

  Returns true or false, depending on whether the output buffers will be flushed immediately upon receiving output or not. An optional argument sets the value.

- autohandler_name()

  Returns the name of the file to be used for Mason's autohandler mechanism (i.e., `"autohandler"`).

- dhandler_name([<name>])

  Returns the name of the file to be used for Mason's dhandler mechanism (i.e., `"dhandler"`). An optional argument sets the value.

- code_cache_max_size([<size>])

  Returns the number of bytes allowed for caching of compiled component code. An optional argument sets the value.

- ignore_warnings_expr([<regex>])

  Returns a regular expression indicating warnings to ignore when calling or compiling components. An optional argument sets the value.

- data_cache_defaults([<hash reference>])

  Returns a hash reference of parameters that will be passed to the caching methods by default. An optional hash reference argument sets the value.

- max_recurse([<integer>])

  Returns an integer indicating the level of nesting allowed in component calls, as a deterrent to infinite component call loops. An optional argument sets the value.

- use_object_files()

  Returns true or false, depending on whether the Interpreter will cache compiled components to disk as object files.

- preloads()

  Returns reference to an array of glob-like patterns specifying components to be loaded when the Interpreter is created.

- files_written()

  Returns a list of all files created by the Interpreter. This may be useful if you want to enforce certain file permissions or ownership.

### Directories

- comp_root()

  A pass-through method to the Resolver method of the same name.

- object_dir()

  Returns a string containing the name of the directory in which Mason's component objects will be cached.

- data_dir()

  Returns the current value of the `data_dir` parameter.

### Runtime Methods

- exec(<component>, <args...>)

  Initiates a new Mason request. The first argument should be the component to execute, specified either as an absolute pathname or as a component object. Any additional arguments will be passed to the component.

- load(<absolute component path>)

  Returns the component at the path specified by the argument. Throws an exception if no such component exists.

- comp_exists(<absolute component path>)

  Returns true or false, depending on whether a component exists at the path specified by the argument.

- make_component(comp_file => <path> [, name => <string> ])

  Creates a component object and returns it. The text of the component may be specified as a string in the `comp_source` parameter or as a filename in the `comp_file` parameter. You may also provide a `name` parameter to associate with this component. If no name is provided, the name will default to a string like `"<anonymous component>"`.

- set_global(<name> => <value>)

  Sets the value of a Perl global variable so that it will be available to components at runtime. The first argument names the variable in a string (i.e., '$user'), including the leading `$`, `@`, or `%` character. The remaining arguments specify the value to assign. The name of the variable should not be fully package-qualified with `:`: characters; the variable will be created in the same package in which components execute.

## 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`.

- new(<parameters...>)

  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.

- error_format([<format>])

  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`.

- ah()

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

- apache_req()

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

### Altering the Request Flow

- abort([<value>])

  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`.

### Caching

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

- cache(<arguments...>)

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

- cache_self(<arguments...>)

  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.

### Introspection

- caller()

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

- callers([<n>])

  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`.

- caller_args(<n>)

  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

- print(<strings...>)

  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 "Components called with content" in Chapter 2 for more details.

- file(<path>)

  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.

- fetch_comp(<path>)

  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.

- comp_exists(<path>)

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

- call_next(<arguments...>)

  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.

### Subrequests

- 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.

## 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`.

- new(<parameters...>)

  Creates a new component. See Appendix B for a list of parameters that affect the component behavior.

  The `new()` method is `not` the proper way to create a component from scratch, since components must be associated with an Interpreter. See the `make_component()` Interpreter method if you wish to create a component from scratch.

### Object Properties

- title()

  Returns a unique string identifying this component.

- name()

  Returns a short string identifying this component. There may be more than one component with the same name.

- path()

  Returns the path of this component relative to the source root.

- dir_path()

  Returns the component's notion of a current directory, relative to the component root.

- source_dir()

  Returns the component's enclosing directory if it is a file-based component. Note that Mason does not actually `chdir()` to a component's directory before executing it, so you may need to use `source_dir` to establish context.

- object_file()

  Returns the full pathname of the object file associated with this component or `undef` if this component is not associated with any object file.

- load_time()

  Returns the time this component object (not its source file) was created, in number of seconds since the epoch.

- declared_args()

  Returns a hash reference indicating the variables declared in this component's `<%args>` section. Each key in this hash reference is the name of a Perl variable (including the initial sigil, `$`, `@`, or `%`), and the value is a hash reference containing (at least) a `default` key. Its value, in turn, contains Perl code to be evaluated to get the default value for this component argument.

- flag(<name>)

  Given a string argument, returns the value of the Mason flag by that name for this component, as declared in a `<%flags>` section. Throws an exception if the argument is not the name of a valid Mason flag. Currently, there is only one flag allowed in `<%flags>` sections, the `inherit` flag that specifies a parent component.

  Note that flag values do not inherit from parent components.

- is_subcomp()

  Returns true if the component is a subcomponent or method or false otherwise.

- is_file_based()

  Returns true if the component was loaded from a source or object file or false otherwise.

### Component Relationships

- subcomps()

  Returns a reference to a hash containing all subcomponents declared by this component, with names as keys and component objects as values. If you provide a string argument, returns only the subcomponent with that name or `undef` if no such subcomponent exists.

- methods()

  Returns a reference to a hash containing all methods declared by this component, with names as keys and component objects as values. If you provide a string argument, returns only the method with that name or `undef` if no such subcomponent exists.

  Note that this does `not` search for methods in any parent components. See the `method_exists` and `call_method` entries in the next section if you wish to perform such a search.

- parent()

  Returns the parent component of this component or `undef` if this component has no parent.

- owner()

  If this component is a subcomponent or method, returns the component object in which it was declared.

### Inheritance

- attr(<name>)

  Given a string argument, returns the value of the attribute (declared in an `<%attr>` block) by that name in this component or its parents. If no such attribute exists, an exception will be thrown.

- attr_exists(<name>)

  Given a string argument, returns true if an attribute by that name exists in this component or its parents or false otherwise.

- attr_if_exists([<name>])

  Given a string argument, returns the value of the attribute by that name in this component or its parents. If no such attribute exists, returns `undef`.

- call_method(<name> [, <arguments...>])

  Given a string argument, searches for a method by that name in this component or its parents and executes it. If no such method exists, a fatal exception will be thrown.

- scall_method(<name> [, <arguments...>])

  Just like `call_method` , but returns the component's output as a string instead of outputting it. Any return value will be discarded.

- method_exists(<name>)

  Given a string argument, returns true if a method by that name exists in this component or its parents or false otherwise.

## 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`.

- new(<parameters...>)

  Returns a new Resolver object. See Appendix B for a list of parameters accepted by the

  `new()` method.

- get_info(<path> )

  Given a component path, returns an `HTML::Mason::ComponentSource` object that may be queried to get information about the component source.

- comp_root([<new_root>])

  Returns the current value of the component root. The value returned may be a string or a reference to an array of arrays, depending on whether you're using one or several component roots. Optionally sets the value of the component root if you provide an argument, whose form is the same.

- comp_root_array()

  Like `comp_root()`, but in a list context always returns a list of arrays, one per component root. If there is only one root and its name is unspecified, it will be given the name `MAIN`. In a scalar context, returns the number of component roots.

- glob_path(<pattern> )

  Given a "glob"-style pattern, returns a list of paths of all components that match that pattern in the component root.

- apache_request_to_comp_path(<Apache request object>)

  Given an Apache request object, this method is expected to return a component path, or `undef` if the request cannot be translated to a component path.

## 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_perl` `args_method`.

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

- new(<parameters...>)

  Creates a new ApacheHandler object. See Appendix B for a listing of the parameters accepted.

- interp([<interpreter>])

  Returns the current Interpreter associated with this ApacheHandler. An optional argument sets the value to a new Interpreter.

- handle_request($r)

  Initiates a Mason request, processing any incoming arguments to the web server and calling the appropriate component.

- handler($r)

  A wrapper around `handle_request()` suitable for using as a `mod_perl` "handler." You must enable `PERL_METHOD_HANDLERS` when compiling `mod_perl` in order to use this handler.

- prepare_request($r)

  Returns a new Mason Request object for the given Apache Request or an HTTP status code if an error was encountered.

- apache_status_title([<string>])

  Returns the title of the Mason status page generated by `Apache::Status`. An optional argument sets the title.

- args_method()

  Returns the current `args_method` setting, which can be either `mod_perl` or `CGI` depending on whether you're using `Apache::Request` or `CGI.pm` for HTTP argument processing.

- decline_dirs([true or false])

  Returns true or false, depending on whether requests for directories will be declined or accepted. An optional argument sets the value. If a request for a directory is accepted, it should usually be caught by using a dhandler mechanism, so Mason has a component to execute.

## 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.

- new(<parameters...>)

  Creates a new CGIHandler object. See Appendix B for a listing of the parameters accepted.

- handle_request()

  Initiates a Mason request, processing any incoming arguments to the web server and calling the appropriate component. The initial component will be the one specified in `$ENV{PATH_INFO}`.

- handle_comp(<component>)

  Like `handle_request()`, but explicitly specifies the component as an argument, either as a component path or a component object.

- handle_cgi_object(<CGI object>)

  Also like `handle_request()`, but takes component path from the given CGI object's `path_info` method. Additionally, this CGI object is available to the called components.

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:

- header_out(<header> => <value>)

  Adds an outgoing header to the HTTP response.

- content_type()

  Sets the content type of the response to the argument given. If you don't set the content type, the type will be set to `text/html` by default.

## 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.

- new(<parameters...>)

  Creates a new Compiler object and returns it. Called by the Interpreter object. See Appendix B for a list of parameters accepted.

### Object Properties

- allow_globals([<variables...>])

  Returns a list of variable names (including the initial `$`, `@`, or `%` type-identifying sigil) that have been declared as allowable globals within components or the number of such variables in a scalar context. The list of allowed globals can optionally be set by passing the variable names (again, including the initial sigils) as arguments. This replaces any previously set globals. To clear the list of allowed globals, pass an argument list containing the single element `undef`.

        my @allowed = $compiler->allow_globals;      # Get list of globals
        $compiler->allow_globals('$dbh','%session'); # Set list of globals
        $compiler->allow_globals(undef);             # Clear list of globals

- add_allowed_globals(<variables...>)

  Adds one or more variable names (including the initial `$`, `@`, or `%` type-identifying sigil) to the list of globals allowed within components. Returns a list of variable names (again, including the initial sigils) in a list context or the number of such variables in a scalar context.

- object_id()

  Returns a string identifier that uniquely identifies this compiler and its current settings. This identifier is used mainly to make sure that components compiled under a different compiler, or under the same compiler with different settings, are declared stale.

- compile(comp_source => <string>, name => <string>)

  Compiles a component from source text and returns the compiled component. The source text is passed in a `comp_source` parameter, and a unique identifier for this component is passed in a mandatory `name` parameter. The compiled component may take any of several forms, but the default `HTML::Mason::Compiler::ToObject` class returns a bunch of Perl code in a string.

### 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.

- start_component()

  Called by the Lexer when it starts processing a component.

- end_component()

  Called by the Lexer when it finishes processing a component.

- start_block(block_type => <string>)

  Called by the Lexer when it encounters an opening Mason block tag like `<%perl>` or `<%args>`. Its main purpose is to keep track of the nesting of different kinds of blocks within each other. The type of block ( `init` , `once` , etc.) is passed via the `block_type` parameter.

- end_block(block_type => <string>)

  Called by the Lexer when it encounters a closing Mason block tag like `</%perl>` or `</%args>`. Like `start_block()`, its main purpose is to help maintain syntactic integrity.

- *_block(block => <string>, [ block_type => <string> ])

  Several compiler methods like `doc_block()` , `text_block()` , and `raw_block()` are called by the Lexer after `start_block()` when it encounters blocks of certain types. These methods actually do the work of putting the body of a block into the compiled data structure.

  The methods that follow this pattern are `init_block()` , `perl_block()` , `doc_block()`, `text_block()`, and `raw_block()`. The last method is called for all `<%once>`, `<%cleanup>`, `<%filter>`, `<%init>`, `<%perl>`, and `<%shared>` blocks.

- text(text => <string>)

  Inserts the text contained in a `text` parameter into the component for verbatim output.

  This is called when the Lexer finds plain text in a component.

- variable_declaration( type => <string>, name => <string>, default => <string> )

  Inserts a variable declaration from the `<%args>` section into the component.

  The type will be either `$` , `@` , or `%` , indicating a scalar, array, or hash. The name is the variable name without the leading sigil. The default is everything found after the first `=>` on an `<%args>` block line and may include a comment.

- key_value_pair(block_type => <string>, key => <string>, value => <string>)

  Inserts a key/value pair from a `<%flags>` or `<%attr>` section into the component.

  The `block_type` parameter will be either `flags` or `attr` .

- start_named_block(block_type => <string>, name => <name>)

  Analogous to `start_block` , earlier in this section, but starts a "named" block (`<%method>` or `<%def>`).

- end_named_block()

  Called by the Lexer to end a "named" block.

- substitution(substitution => <string>, escape => <string>)

  Called by the Lexer when it encounters a substitution tag (`<% ... %>`).

  The value of the `escape` parameter will be everything found after the pipe (|) in the substitution tag and may be more than one character such as `nh` .

- component_call(call => <string>)

  Called by the Lexer when it encounters a component call tag without embedded content (`<& ... &>`).

  The `call` parameter contains the entire contents of the tag.

- component_content_call(call => <string>)

  Called by the Lexer when it encounters a component call tag with embedded content (`<&| ... &>`).

- component_content_call_end()

  Called by the Lexer when it encounters an end tag for a component call with content (`</&>`). Note that there is no corresponding `component_call_end()` method for component calls without content, because these calls don't have end tags.

- perl_line(line => <string>)

  Called by the Lexer when it encounters a `%`-line.

## 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`.

- new(<parameters...>)

  Creates a new Lexer object and returns it. In the current version of Mason, the `new()` method doesn't accept any parameters.

- lex(name => <string>, compiler => <compiler>, comp_source => string)

  Begins the process of lexing a component. The `name` parameter specifies a unique name for this component. For a file-based component, this is its full path relative to the component root. The `compiler` parameter supplies the compiler object to use when processing this component. The `comp_source` parameter supplies the source to process.

  The `lex()` method has no return value. If it encounters an error during processing, it will throw an exception.

- line_number()

  Returns the Lexer's current line number in the component being processed.

- name(),

  Returns the name of the component currently being processed (i.e., the value of the `name` parameter passed to the `lex()` method).

- throw_syntax_error(<error>)

  Throws an `HTML::Mason::Exception::Syntax` error with the given error message as well as additional information about the component source.