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

- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- Compilation Callbacks

- SEE ALSO

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

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

  - 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