1HTML::Mason::Compiler(3U)ser Contributed Perl DocumentatiHoTnML::Mason::Compiler(3)
2
6 HTML::Mason::Compiler - Compile Mason component source
7
9 package My::Funky::Compiler;
10 use base qw(HTML::Mason::Compiler);
12
14 The compiler starts the compilation process by calling its lexer's
15 "lex" method and passing itself as the "compiler" parameter. The lexer
16 then calls various methods in the compiler as it parses the component
17 source.
18
20 allow_globals
21 List of variable names, complete with prefix ("$@%"), that you
22 intend to use as globals in components. Normally global variables
23 are forbidden by "strict", but any variable mentioned in this list
24 is granted a reprieve via a "use vars" statement. For example:
25 allow_globals => [qw($DBH %session)]
27 In a mod_perl environment, $r (the request object) is automatically
29 added to this list.
30 default_escape_flags
32 Escape flags to apply to all <% %> expressions by default. The cur‐
33 rent valid flags are
34 h - escape for HTML ('<' => '<', etc.)
36 u - escape for URL (':' => '%3A', etc.)
37 The developer can override default escape flags on a per-expression
39 basis; see the escaping expressions section of the developer's man‐
40 ual.
41 If you want to set multiple flags as the default, this should be
43 given as a reference to an array of flags.
44 enable_autoflush
46 True or false, default is true. Indicates whether components are
47 compiled with support for autoflush. The component can be compiled
48 to a more efficient form if it does not have to check for autoflush
49 mode, so you should set this to 0 if you can.
50 lexer
52 The Lexer object to associate with this Compiler. By default a new
53 object of class lexer_class will be created.
54 lexer_class
56 The class to use when creating a lexer. Defaults to
57 HTML::Mason::Lexer.
58 preprocess
60 Sub reference that is called to preprocess each component before
61 the compiler does it's magic. The sub is called with a single
62 parameter, a scalar reference to the script. The sub is expected
63 to process the script in-place. This is one way to extend the
64 HTML::Mason syntax with new tags, etc., although a much more flexi‐
65 ble way is to subclass the Lexer or Compiler class. See also post‐
66 process_text and postprocess_perl.
67 postprocess_text
69 Sub reference that is called to postprocess the text portion of a
70 compiled component, just before it is assembled into its final sub‐
71 routine form. The sub is called with a single parameter, a scalar
72 reference to the text portion of the component. The sub is
73 expected to process the string in-place. See also preprocess and
74 postprocess_perl.
75 postprocess_perl
77 Sub reference that is called to postprocess the Perl portion of a
78 compiled component, just before it is assembled into its final sub‐
79 routine form. The sub is called with a single parameter, a scalar
80 reference to the Perl portion of the component. The sub is
81 expected to process the string in-place. See also preprocess and
82 postprocess_text.
83 use_source_line_numbers
85 True or false, default is true. Indicates whether component line
86 numbers that appear in error messages, stack traces, etc. are in
87 terms of the source file instead of the object file. Mason does
88 this by inserting '#line' directives into compiled components.
89 While source line numbers are more immediately helpful, object file
90 line numbers may be more appropriate for in-depth debugging ses‐
91 sions.
92
94 All of the above properties have read-only accessor methods of the same
95 name.
96 You cannot change any property of a compiler after it has been created
98 - among other things, this would potentially invalidate any existing
99 cached component objects or object files. Your best bet is to create
100 different compiler objects and load them into different interpreters.
101
103 There are several methods besides the compilation callbacks below that
104 a Compiler subclass needs to implement.
105 compile(comp_source => <string>, name => <string>, comp_class =>
107 <string>)
108 The "comp_class" parameter may be ignored by the compiler.
109 object_id
111 This method should return a unique id for the given compiler
112 object. This is used by the interpreter when determining the
113 object directory, for example.
114 Compilation Callbacks
116 These are methods called by the Lexer while processing a component
118 source. You may wish to override some of these methods if you're
119 implementing your own custom Compiler class.
120 start_component()
122 This method is called by the Lexer when it starts processing a com‐
123 ponent.
124 end_component()
126 This method is called by the Lexer when it finishes processing a
127 component.
128 start_block(block_type => <string>)
130 This method is called by the Lexer when it encounters an opening
131 Mason block tag like "<%perl>" or "<%args>". Its main purpose is
132 to keep track of the nesting of different kinds of blocks within
133 each other. The type of block ("init", "once", etc.) is passed via
134 the "block_type" parameter.
135 end_block(block_type => <string>)
137 This method is called by the Lexer when it encounters a closing
138 Mason block tag like "</%perl>" or "</%args>". Like
139 "start_block()", its main purpose is to help maintain syntactic
140 integrity.
141 *_block(block => <string>, [ block_type => <string> ])
143 Several compiler methods like "doc_block()", "text_block()", and
144 "raw_block()" are called by the Lexer after "start_block()" when it
145 encounters blocks of certain types. These methods actually do the
146 work of putting the body of a block into the compiled data struc‐
147 ture.
148 The methods that follow this pattern are "init_block()",
150 "perl_block()", "doc_block()", "text_block()", and "raw_block()".
151 The last method is called for all "<%once>", "<%cleanup>", "<%fil‐
152 ter>", "<%init>", "<%perl>", and "<%shared>" blocks.
153 text(text => <string>)
155 Inserts the text contained in a "text" parameter into the component
156 for verbatim output.
157 This is called when the lexer finds plain text in a component.
159 variable_declaration( type => <string>, name => <string>, default =>
161 <string> )
162 Inserts a variable declaration from the "<%args>" section into the
163 component.
164 The type will be either "$", "@", or "%", indicating a scalar,
166 array, or hash. The name is the variable name without the leading
167 sigil. The default is everything found after the first "=>" on an
168 "<%args>" block line, and may include a comment.
169 key_value_pair(block_type => <string>, key => <string>, value =>
171 <string>)
172 Inserts a key-value pair from a "<%flags>" or "<%attr>" section
173 into the component.
174 The "block_type" parameter will be either "flags" or "attr".
176 start_named_block(block_type => <string>, name => <name>)
178 Analogous to item_start_block, but starts a "named" block
179 ("<%method>" or "<%def>").
180 end_named_block()
182 Called by the Lexer to end a "named" block.
183 substitution(substitution => <string>, escape => <string>)
185 Called by the Lexer when it encounters a substitution tag ("<% ...
186 %>").
187 The value of the "escape" parameter will be everything found after
189 the pipe (⎪) in the substitution tag, and may be more than one
190 character such as "nh".
191 component_call(call => <string>)
193 Called by the Lexer when it encounters a component call tag without
194 embedded content ("<& ... &>").
195 The "call" parameter contains the entire contents of the tag.
197 component_content_call(call => <string>)
199 Called by the Lexer when it encounters a component call tag with
200 embedded content ("<&⎪ ... &>").
201 component_content_call_end()
203 Called by the Lexer when it encounters an ending tag for a compo‐
204 nent call with content ("</&>"). Note that there is no correspond‐
205 ing "component_call_end()" method for component calls without con‐
206 tent, because these calls don't have ending tags.
207 perl_line(line => <string>)
209 Called by the Lexer when it encounters a "%"-line.
210
212 We recommend that any parameters you add to Compiler be read-only,
213 because the compiler object_id is only computed once on creation and
214 would not reflect any changes to Lexer parameters.
215
217 HTML::Mason, HTML::Mason::Admin, HTML::Mason::Interp
218perl v5.8.8 2007-04-17 HTML::Mason::Compiler(3)