NAME
HTML::Mason::Commands - Mason command reference
DESCRIPTION
The following commands may be used within Mason components. See HTML::Mason::Components (the Mason Developer's Guide), for usage examples.
COMMAND REFERENCE
- mc_abort ([return value])
-
Ends the current execution, finishing the page without returning through components. In a web environment, the optional return value is used as the HTTP status code.
- mc_cache ([action=>'retrieve'], [key=>name],
-
[keep_in_memory=>0|1], [expire_if=>sub])
- mc_cache (action=>'store', [key=>name], value=>data, [keep_in_memory=>0|1],
-
[expire_at=>time | expire_next=>'hour'|'day' | expire_in=>delta])
- mc_cache_self ([key=>name], [keep_in_memory=>0|1],
-
[expire_if=>sub | expire_at=>time | expire_next=>'hour'|'day' | expire_in=>delta])
mc_cache() and mc_cache_self() let you store and retrieve the results of computation for improved performance. Each component has its own data cache for storing one or more key/value pairs. The cache is implemented as a DBM database.
The argument to action is one of 'retrieve' or 'store'. Default is 'retrieve'.
The retrieve action returns the cache value if successful, or
undefif there was no value or if it has expired.The store action stores a new cache value, under the given key. The default key is 'main'.
value defines what to store. It can be a scalar or a reference to an arbitrary data structure. The allowable size depends on your DBM implementation.
keep_in_memory indicates whether to save the value in memory once it is retrieved. Default is 0, meaning that the value will be retrieved from the cache file each time. If 1, each child server that retrieves this value will save its own copy, which can result in substantial memory usage for larger values. Use sparingly.
The various expiration options are described and demonstrated in HTML::Mason::Components.
- mc_caller ()
-
Returns the full path of the component that called this component, or undef if this is the top-level component. This is the second element of mc_comp_stack.
- mc_comp (compPath, option=>value, ...[, STORE=>ref])
-
Calls the component designated by compPath with the specified option/value pairs. If the component path is absolute (starting with a '/'), then the component is found relative to the component root. Relative component paths (no leading '/') are relative to the current component directory.
Components work exactly like Perl subroutines in terms of return values and context. A component can return any type of value, which is then returned from the mc_comp call.
If you want to capture the output of a component in a string, send a scalar reference with the STORE option. The output will be placed in the scalar instead of being sent to the default output stream.
- mc_comp_exists (compPath)
-
Returns 1 if compPath is a valid component path, 0 otherwise.
- mc_comp_stack ()
-
Returns the list of components in the call stack, starting with the current component and ending with the top-level component.
- mc_date (format)
-
Returns the interpreter's notion of the current time or date in the specified format. This works like UnixDate in the Date::Manip package (see Date::Manip for valid formats).
To allow time-of-day adjustments in the Previewer, components should use mc_date() and mc_time() rather than Perl's built-in time function.
mc_date() works faster than UnixDate for some formats by caching results.
- mc_file (filename)
-
Returns the contents of filename as a string. filename may be an absolute filesystem path (starting with a '/') or relative (no leading '/'); if relative, the static file root is prepended.
Developers are encouraged to use relative paths whenever possible. This eliminates the need for component updates when data files are moved (the administrator just updates the static file root).
- mc_file_root ()
-
Returns the static file root, used by mc_file() to resolve relative filenames.
- mc_out (string)
-
Print the given string. Rarely needed, since normally all HTML is just placed in the component body and output implicitly. mc_out is useful if you need to output something in the middle of a Perl block.
mc_out() should be favored over the lower-level
$r->print, since mc_out() may be redirected or buffered, depending on the current state of the interpreter. - mc_time ()
-
Returns the interpreter's notion of the current time in Perl style format (number of seconds since 1/1/70).
Web-only Commands
The following commands are only available when Mason is running in a Web environment.
- mc_dhandler_arg ()
-
For use in dhandlers. Returns the path_info CGI argument, stripped of its leading slash.
- mc_suppress_http_header (0|1)
-
Mason normally emits any pending HTTP headers just before entering the primary section of a component. To prevent this, call mc_suppress_http_headers(1) somewhere in the
<%perl_init%>block. You can call mc_suppress_http_headers(0) to cancel.
AUTHOR
Jonathan Swartz, swartz@transbay.net