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 start_block(),
158           its main purpose is to help maintain syntactic integrity.
159
160       *_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
167           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
172       text(text => <string>)
173           Inserts the text contained in a "text" parameter into the component
174           for verbatim output.
175
176           This is called when the lexer finds plain text in a component.
177
178       variable_declaration( type => <string>, name => <string>, default =>
179       <string> )
180           Inserts a variable declaration from the "<%args>" section into the
181           component.
182
183           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
188       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
193           The "block_type" parameter will be either "flags" or "attr".
194
195       start_named_block(block_type => <string>, name => <name>)
196           Analogous to item_start_block, but starts a "named" block
197           ("<%method>" or "<%def>").
198
199       end_named_block()
200           Called by the Lexer to end a "named" block.
201
202       substitution(substitution => <string>, escape => <string>)
203           Called by the Lexer when it encounters a substitution tag ("<% ...
204           %>").
205
206           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
210       component_call(call => <string>)
211           Called by the Lexer when it encounters a component call tag without
212           embedded content ("<& ... &>").
213
214           The "call" parameter contains the entire contents of the tag.
215
216       component_content_call(call => <string>)
217           Called by the Lexer when it encounters a component call tag with
218           embedded content ("<&| ... &>").
219
220       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
226       perl_line(line => <string>)
227           Called by the Lexer when it encounters a "%"-line.
228

SUBCLASSING

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.
233
234
235
236perl v5.38.0                      2023-07-20          HTML::Mason::Compiler(3)
Impressum