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 start_block(),
158 its main purpose is to help maintain syntactic integrity.
159 *_block(block => <string>, [ block_type => <string> ])
161 Several compiler methods like doc_block(), text_block(), and
162 raw_block() are called by the Lexer after start_block() when it
163 encounters blocks of certain types. These methods actually do the
164 work of putting the body of a block into the compiled data
165 structure.
166 The methods that follow this pattern are init_block(),
168 perl_block(), doc_block(), text_block(), and raw_block(). The last
169 method is called for all "<%once>", "<%cleanup>", "<%filter>",
170 "<%init>", "<%perl>", and "<%shared>" blocks.
171 text(text => <string>)
173 Inserts the text contained in a "text" parameter into the component
174 for verbatim output.
175 This is called when the lexer finds plain text in a component.
177 variable_declaration( type => <string>, name => <string>, default =>
179 <string> )
180 Inserts a variable declaration from the "<%args>" section into the
181 component.
182 The type will be either "$", "@", or "%", indicating a scalar,
184 array, or hash. The name is the variable name without the leading
185 sigil. The default is everything found after the first "=>" on an
186 "<%args>" block line, and may include a comment.
187 key_value_pair(block_type => <string>, key => <string>, value =>
189 <string>)
190 Inserts a key-value pair from a "<%flags>" or "<%attr>" section
191 into the component.
192 The "block_type" parameter will be either "flags" or "attr".
194 start_named_block(block_type => <string>, name => <name>)
196 Analogous to item_start_block, but starts a "named" block
197 ("<%method>" or "<%def>").
198 end_named_block()
200 Called by the Lexer to end a "named" block.
201 substitution(substitution => <string>, escape => <string>)
203 Called by the Lexer when it encounters a substitution tag ("<% ...
204 %>").
205 The value of the "escape" parameter will be everything found after
207 the pipe (|) in the substitution tag, and may be more than one
208 character such as "nh".
209 component_call(call => <string>)
211 Called by the Lexer when it encounters a component call tag without
212 embedded content ("<& ... &>").
213 The "call" parameter contains the entire contents of the tag.
215 component_content_call(call => <string>)
217 Called by the Lexer when it encounters a component call tag with
218 embedded content ("<&| ... &>").
219 component_content_call_end()
221 Called by the Lexer when it encounters an ending tag for a
222 component call with content ("</&>"). Note that there is no
223 corresponding component_call_end() method for component calls
224 without content, because these calls don't have ending tags.
225 perl_line(line => <string>)
227 Called by the Lexer when it encounters a "%"-line.
228
230 We recommend that any parameters you add to Compiler be read-only,
231 because the compiler object_id is only computed once on creation and
232 would not reflect any changes to Lexer parameters.
233perl v5.38.0 2023-07-20 HTML::Mason::Compiler(3)