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
33 current 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
40 manual.
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
65 flexible way is to subclass the Lexer or Compiler class. See also
66 postprocess_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
71 subroutine form. The sub is called with a single parameter, a
72 scalar 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
79 subroutine form. The sub is called with a single parameter, a
80 scalar 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
91 sessions.
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(...)
107 This method has several parameters:
108 · comp_source (required)
110 Either a scalar or reference to a scalar containing the
112 component source.
113 · name (required)
115 The name of the component. This should be the filename of
117 the component if it is file-based, or some other clear
118 identifier of the component source.
119 · comp_path (required)
121 This should be the component's path.
123 · fh (optional)
125 If this is given then the output of the compiler will be
127 sent directly to this handle, rather than being buffered in
128 memory. This is an optimization to avoid memory usage.
129 object_id
131 This method should return a unique id for the given compiler
132 object. This is used by the interpreter when determining the
133 object directory, for example.
134 Compilation Callbacks
136 These are methods called by the Lexer while processing a component
137 source. You may wish to override some of these methods if you're
138 implementing your own custom Compiler class.
139 start_component()
141 This method is called by the Lexer when it starts processing a
142 component.
143 end_component()
145 This method is called by the Lexer when it finishes processing a
146 component.
147 start_block(block_type => <string>)
149 This method is called by the Lexer when it encounters an opening
150 Mason block tag like "<%perl>" or "<%args>". Its main purpose is
151 to keep track of the nesting of different kinds of blocks within
152 each other. The type of block ("init", "once", etc.) is passed via
153 the "block_type" parameter.
154 end_block(block_type => <string>)
156 This method is called by the Lexer when it encounters a closing
157 Mason block tag like "</%perl>" or "</%args>". Like
158 "start_block()", its main purpose is to help maintain syntactic
159 integrity.
160 *_block(block => <string>, [ block_type => <string> ])
162 Several compiler methods like "doc_block()", "text_block()", and
163 "raw_block()" are called by the Lexer after "start_block()" when it
164 encounters blocks of certain types. These methods actually do the
165 work of putting the body of a block into the compiled data
166 structure.
167 The methods that follow this pattern are "init_block()",
169 "perl_block()", "doc_block()", "text_block()", and "raw_block()".
170 The last method is called for all "<%once>", "<%cleanup>",
171 "<%filter>", "<%init>", "<%perl>", and "<%shared>" blocks.
172 text(text => <string>)
174 Inserts the text contained in a "text" parameter into the component
175 for verbatim output.
176 This is called when the lexer finds plain text in a component.
178 variable_declaration( type => <string>, name => <string>, default =>
180 <string> )
181 Inserts a variable declaration from the "<%args>" section into the
182 component.
183 The type will be either "$", "@", or "%", indicating a scalar,
185 array, or hash. The name is the variable name without the leading
186 sigil. The default is everything found after the first "=>" on an
187 "<%args>" block line, and may include a comment.
188 key_value_pair(block_type => <string>, key => <string>, value =>
190 <string>)
191 Inserts a key-value pair from a "<%flags>" or "<%attr>" section
192 into the component.
193 The "block_type" parameter will be either "flags" or "attr".
195 start_named_block(block_type => <string>, name => <name>)
197 Analogous to item_start_block, but starts a "named" block
198 ("<%method>" or "<%def>").
199 end_named_block()
201 Called by the Lexer to end a "named" block.
202 substitution(substitution => <string>, escape => <string>)
204 Called by the Lexer when it encounters a substitution tag ("<% ...
205 %>").
206 The value of the "escape" parameter will be everything found after
208 the pipe (|) in the substitution tag, and may be more than one
209 character such as "nh".
210 component_call(call => <string>)
212 Called by the Lexer when it encounters a component call tag without
213 embedded content ("<& ... &>").
214 The "call" parameter contains the entire contents of the tag.
216 component_content_call(call => <string>)
218 Called by the Lexer when it encounters a component call tag with
219 embedded content ("<&| ... &>").
220 component_content_call_end()
222 Called by the Lexer when it encounters an ending tag for a
223 component call with content ("</&>"). Note that there is no
224 corresponding "component_call_end()" method for component calls
225 without content, because these calls don't have ending tags.
226 perl_line(line => <string>)
228 Called by the Lexer when it encounters a "%"-line.
229
231 We recommend that any parameters you add to Compiler be read-only,
232 because the compiler object_id is only computed once on creation and
233 would not reflect any changes to Lexer parameters.
234perl v5.28.1 2017-10-29 HTML::Mason::Compiler(3)