O'Reilly logo

Embedding Perl in HTML with Mason by Ken Williams, Dave Rolsky

Stay ahead with the world's most comprehensive technology and business learning platform.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, tutorials, and more.

Start Free Trial

No credit card required

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...>])
allow_globals([undef])

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.

With Safari, you learn the way you learn best. Get unlimited access to videos, live online training, learning paths, books, interactive tutorials, and more.

Start Free Trial

No credit card required