NAME

HTML::Mason::Compiler - Compile Mason component source

SYNOPSIS

  package My::Funky::Compiler;

  use base qw(HTML::Mason::Compiler);

DESCRIPTION

The compiler starts the compilation process by calling its lexer's lex method and passing itself as the compiler parameter. The lexer then calls various methods in the compiler as it parses the component source.

METHODS

There are several methods besides the compilation callbacks below that a Compiler subclass needs to implement.

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

The "comp_class" parameter may be ignored by the compiler.

object_id

This method should return a unique id for the given compiler object. This is used by the interpreter when loading previously compiled objects in order to determine whether or not the object should be re-compiled.

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()

This method is called by the Lexer when it starts processing a component.

end_component()

This method is called by the Lexer when it finishes processing a component.

start_block(block_type => <string>)

This method is 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.

start_block(block_type => <string>)

This method is 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()", 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 ending 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 ending tags.

perl_line(line => <string>)

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

SEE ALSO

HTML::Mason, HTML::Mason::Admin, HTML::Mason::Interp