1HTML::Mason::Compiler(3U)ser Contributed Perl DocumentatiHoTnML::Mason::Compiler(3)
2
3
4

NAME

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

SYNOPSIS

9         package My::Funky::Compiler;
10
11         use base qw(HTML::Mason::Compiler);
12

DESCRIPTION

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

PARAMETERS TO THE new() CONSTRUCTOR

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
26               allow_globals => [qw($DBH %session)]
27
28           In a mod_perl environment, $r (the request object) is automatically
29           added to this list.
30
31       default_escape_flags
32           Escape flags to apply to all <% %> expressions by default. The
33           current valid flags are
34
35               h - escape for HTML ('<' => '&lt;', etc.)
36               u - escape for URL (':' => '%3A', etc.)
37
38           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
42           If you want to set multiple flags as the default, this should be
43           given as a reference to an array of flags.
44
45       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
51       lexer
52           The Lexer object to associate with this Compiler. By default a new
53           object of class lexer_class will be created.
54
55       lexer_class
56           The class to use when creating a lexer. Defaults to
57           HTML::Mason::Lexer.
58
59       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
68       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
76       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
84       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

ACCESSOR METHODS

94       All of the above properties have read-only accessor methods of the same
95       name.
96
97       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

METHODS

103       There are several methods besides the compilation callbacks below that
104       a Compiler subclass needs to implement.
105
106       compile(...)
107           This method has several parameters:
108
109           •       comp_source (required)
110
111                   Either a scalar or reference to a scalar containing the
112                   component source.
113
114           •       name (required)
115
116                   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
120           •       comp_path (required)
121
122                   This should be the component's path.
123
124           •       fh (optional)
125
126                   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
130       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
135   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
140       start_component()
141           This method is called by the Lexer when it starts processing a
142           component.
143
144       end_component()
145           This method is called by the Lexer when it finishes processing a
146           component.
147
148       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
155       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
161       *_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
168           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
173       text(text => <string>)
174           Inserts the text contained in a "text" parameter into the component
175           for verbatim output.
176
177           This is called when the lexer finds plain text in a component.
178
179       variable_declaration( type => <string>, name => <string>, default =>
180       <string> )
181           Inserts a variable declaration from the "<%args>" section into the
182           component.
183
184           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
189       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
194           The "block_type" parameter will be either "flags" or "attr".
195
196       start_named_block(block_type => <string>, name => <name>)
197           Analogous to item_start_block, but starts a "named" block
198           ("<%method>" or "<%def>").
199
200       end_named_block()
201           Called by the Lexer to end a "named" block.
202
203       substitution(substitution => <string>, escape => <string>)
204           Called by the Lexer when it encounters a substitution tag ("<% ...
205           %>").
206
207           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
211       component_call(call => <string>)
212           Called by the Lexer when it encounters a component call tag without
213           embedded content ("<& ... &>").
214
215           The "call" parameter contains the entire contents of the tag.
216
217       component_content_call(call => <string>)
218           Called by the Lexer when it encounters a component call tag with
219           embedded content ("<&| ... &>").
220
221       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
227       perl_line(line => <string>)
228           Called by the Lexer when it encounters a "%"-line.
229

SUBCLASSING

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.
234
235
236
237perl v5.36.0                      2022-07-22          HTML::Mason::Compiler(3)
Impressum