1XS::Parse::Sublike(3) User Contributed Perl DocumentationXS::Parse::Sublike(3)
2
6 "XS::Parse::Sublike" - XS functions to assist in parsing "sub"-like
7 syntax
8
10 This module provides some XS functions to assist in writing parsers for
11 "sub"-like syntax, primarily for authors of keyword plugins using the
12 "PL_keyword_plugin" hook mechanism. It is unlikely to be of much use to
13 anyone else; and highly unlikely to be any use when writing perl code
14 using these. Unless you are writing a keyword plugin using XS, this
15 module is not for you.
16 This module is also currently experimental, and the design is still
18 evolving and subject to change. Later versions may break ABI
19 compatibility, requiring changes or at least a rebuild of any module
20 that depends on it.
21
23 boot_xs_parse_sublike
24 void boot_xs_parse_sublike(double ver)
25 Call this function from your "BOOT" section in order to initialise the
27 module and parsing hooks.
28 ver should either be 0 or a decimal number for the module version
30 requirement; e.g.
31 boot_xs_parse_sublike(0.04);
33 xs_parse_sublike
35 int xs_parse_sublike(const struct XSParseSublikeHooks *hooks, void *hookdata, OP **op_ptr)
36 This function performs the actual parsing of a "sub"-like keyword. It
38 expects the lexer to be at a position just after the introduction
39 keyword has been consumed, and will proceed to parse an optional name,
40 list of attributes, signature (if enabled by "use feature
41 'signatures'"), and code body. The return value and "op_ptr" can be
42 used directly from the keyword plugin function. It is intended this
43 function be invoked from it, and the result returned directly.
44 For a more automated handling of keywords, see
46 "register_xs_parse_sublike".
47 hooks should be a structure that can provide optional function pointers
49 used to customise the parsing process at various stages. hookdata is an
50 opaque pointer which is passed through to each of the hook stage
51 functions.
52 register_xs_parse_sublike
54 void register_xs_parse_sublike(const char *keyword,
55 const struct XSParseSublikeHooks *hooks, void *hookdata)
56 This function installs a set of parsing hooks to be associated with the
58 given keyword. Such a keyword will then be handled automatically by a
59 keyword parser installed by "XS::Parse::Sublike" itself.
60 When the keyword is encountered, the hook's "permit" function is first
62 tested to see if the keyword is permitted at this point. If the
63 function returns true then the keyword is consumed and parsed as per
64 "xs_parse_sublike".
65 hookdata is an opaque pointer which is passed through to each of the
67 hook stage functions when they are invoked.
68 xs_parse_sublike_any
70 int xs_parse_sublike_any(const struct XSParseSublikeHooks *hooks, void *hookdata,
71 OP **op_ptr)
72 This function expects to consume an introduction keyword at the lexer
74 position which is either "sub" or the name of another "sub"-like
75 keyword, which has been previously registered using
76 "register_xs_parse_sublike". It then proceeds to parse the subsequent
77 syntax similar to how it would have parsed if encountered by the
78 module's own keyword parser plugin, except that the second set of hooks
79 given here also take effect.
80 If a regular "sub" is encountered, then this is parsed using the hooks
82 in a similar way to "xs_parse_sublike()".
83 If a different registered "sub"-like keyword is encountered, then
85 parsing is performed using both sets of hooks - the ones given to this
86 function as well as the ones registered with the keyword. This allows
87 their effects to combined. The hooks given by the hooks argument are
88 considered to be on the "outside" from those of the registered keyword
89 "inside". The outside ones run first for all stages, except
90 "pre_blockend" which runs them inside-out.
91 hookdata is an opaque pointer which is passed through to each of the
93 hook stage functions when they are invoked.
94 Note that this function is now vaguely discouraged, in favour of using
96 a prefixing keyword instead, by using the
97 "XS_PARSE_SUBLIKE_FLAG_PREFIX" flag.
98
100 The various hook stages all share state about the ongoing parse process
101 using various fields of the "XSParseSublikeContext" structure.
102 struct XSParseSublikeContext {
104 SV *name;
105 OP *attrs;
106 OP *body;
107 CV *cv;
108 U32 actions;
109 HV *moddata;
110 }
111 The "actions" field will contain a bitmask of action flags that control
113 the various steps that "XS::Parse::Sublike" might take inbetween
114 invoking hook stages. The initial value of this field is set after the
115 name-parsing stage, depending on whether or not a name is found. Stage
116 hook functions may modify the field to adjust the subsequent behaviour.
117 At the current ABI version, a module will have to set the
119 "XS_PARSE_SUBLIKE_COMPAT_FLAG_DYNAMIC_ACTIONS" bit of the "flags" field
120 in order to make use of the actions field. A future ABI version may
121 remove this restriction.
122 XS_PARSE_SUBLIKE_ACTION_CVf_ANON
124 If set, the "start_subparse()" call will be set up for an anonymous
125 function protosub; if not it will be set for a named function. This
126 is set by default if a name was not found.
127 XS_PARSE_SUBLIKE_ACTION_SET_CVNAME
129 If set, the newly-constructed CV will have the given name set on
130 it. This is set by default if a name was found.
131 On Perl versions 5.22 and above, this flag can be set even if
133 "XS_PARSE_SUBLIKE_ACTION_INSTALL_SYMBOL" is not. In this case, the
134 CV will not be reachable via the symbol table, even though it knows
135 its own name and pretends that it is. On earlier versions of perl
136 this flag will be ignored in that case.
137 XS_PARSE_SUBLIKE_ACTION_INSTALL_SYMBOL
139 If set, the newly-constructed CV will be installed into the symbol
140 table at its given name. Note that it is not possible to enable
141 this flag without also enabling
142 "XS_PARSE_SUBLIKE_ACTION_SET_CVNAME". This is set by default if a
143 name was found.
144 XS_PARSE_SUBLIKE_ACTION_REFGEN_ANONCODE
146 If set, the syntax will yield the "OP_REFGEN" / "OP_ANONCODE"
147 optree fragment typical of anonymous code expressions; if not it
148 will be "OP_NULL". This is set by default if a name was not found.
149 XS_PARSE_SUBLIKE_ACTION_RET_EXPR
151 If set, the syntax will parse like an expression; if not it will
152 parse like a statement. This is set by default if a name was not
153 found.
154 The moddata field will point towards an HV that modules can used to
156 store extra data between stages. As a naming convention a module should
157 prefix its keys with its own module name and a slash character,
158 "Some::Module/field". The field will point to a newly-created HV for
159 every parse invocation, and will be released when each parse is
160 complete.
161
163 The "XSParseSublikeHooks" structure provides the following hook stages,
164 which are invoked in the given order.
165 The structure has a flags field, which controls various optional parts
167 of operation. The following flags are defined.
168 XS_PARSE_SUBLIKE_FLAG_FILTERATTRS
170 If set, the optional "filter_attr" stage will be invoked.
171 XS_PARSE_SUBLIKE_FLAG_BODY_OPTIONAL
173 If not set, the require_parts field will imply the
174 "XS_PARSE_SUBLIKE_PART_BODY" flag, making the body part required.
175 By setting this flag this will no longer happen. If all hooks
176 agree, then the body will become optional.
177 XS_PARSE_SUBLIKE_FLAG_PREFIX
179 If set, the keyword is considered to be a prefix that can be placed
180 in front of "sub" or another sub-like keyword, to add its set of
181 hooks in addition to those of the following keyword. These prefices
182 may be further stacked.
183 In addition there are two "U8" fields named require_parts and
185 skip_parts which control the behaviour of various parts of the syntax
186 which are usually optional. Any parts with bits set in require_parts
187 become non-optional, and an error if they are missing. Any parts with
188 bits set in skip_parts will skip the relevant part of the parsing
189 process.
190 When multiple sets of hooks are combined by the "xs_parse_sublike_any"
192 function, or as part of parsing prefixing keywords, these bitmasks are
193 accumulated together with inclusive or. Any part required by any set of
194 hooks will still be required; any step skipped by either will be
195 skipped entirely.
196 If the same bit is set in both fields then the relevant parsing step
198 will not be performed but it will still be an error for that section to
199 be missing. This is likely not useful.
200 Note that for skipped parts, only the actual parsing steps are skipped.
202 A hook function can still set the relevant fields in the context
203 structure anyway to force a particular value for those parts.
204 XS_PARSE_SUBLIKE_PART_NAME
206 The name of the function.
207 XS_PARSE_SUBLIKE_PART_ATTRS
209 The attributes of the function.
210 This part can be skipped, but the bit is ignored when in
212 require_parts. It is always permitted to not provide any additional
213 attributes to a function definition.
214 XS_PARSE_SUBLIKE_PART_SIGNATURE
216 The parameter signature of the function.
217 This part can be skipped, but the bit is ignored when in
219 require_parts. It is always permitted not to provide a signature
220 for a function definition, because such syntax only applies when
221 "use feature 'signatures'" is in effect, and only on supporting
222 perl versions.
223 XS_PARSE_SUBLIKE_PART_BODY
225 The actual body of the function, expressed as a brace-delimited
226 block.
227 This part cannot be skipped, but it can be made optional by
229 omitting it from the require_parts field. Instead of the block, it
230 is permitted to place a single semicolon (";") to act as a
231 statement terminator; thus giving the same syntax as a subroutine
232 forward declaration.
233 In this case, the "body" and "cv" fields of the context structure
235 will remain "NULL".
236 This flag is currently implied on the require_parts field if the
238 hook does not supply the "XS_PARSE_SUBLIKE_FLAG_BODY_OPTIONAL"
239 flag; meaning that most use-cases will make it a required part.
240 The "permit" Stage
242 const char *permit_hintkey
243 bool (*permit)(pTHX_ void *hookdata)
244 Called by the installed keyword parser hook which is used to handle
246 keywords registered by "register_xs_parse_sublike".
247 As a shortcut for the common case, the "permit_hintkey" may point to a
249 string to look up from the hints hash. If the given key name is not
250 found in the hints hash then the keyword is not permitted. If the key
251 is present then the "permit" function is invoked as normal.
252 If not rejected by a hint key that was not found in the hints hash, the
254 function part of the stage is called next and should inspect whether
255 the keyword is permitted at this time perhaps by inspecting other
256 lexical clues, and return true only if the keyword is permitted.
257 Both the string and the function are optional. Either or both may be
259 present. If neither is present then the keyword is always permitted -
260 which is likely not what you wanted to do.
261 Parse Name
263 At this point, the optional name is parsed and filled into the "name"
264 field of the context.
265 The "pre_subparse" Stage
267 void (*pre_subparse)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
268 Invoked just before "start_subparse()" is called.
270 Parse Attrs
272 At this point the optional sub attributes are parsed and filled into
273 the "attrs" field of the context, then "block_start()" is called.
274 The optional "filter_attr" Stage
276 bool (*filter_attr)(pTHX_ struct XSParseSublikeContext *ctx,
277 SV *attr, SV *val, void *hookdata);
278 If the flags field includes "XS_PARSE_SUBLIKE_FLAG_FILTERATTRS" then
280 each individual attribute is passed through this optional filter
281 function immediately as each is parsed. attr will be a string SV
282 containing the name of the attribute, and val will either be "NULL", or
283 a string SV containing the contents of the parens after its name
284 (without the parens themselves).
285 If the filter returns "true", it indicates that it has in some way
287 handled the attribute and it should not be added to the list given to
288 "newATTRSUB()". If the filter returns "false" it will be handled in
289 the usual way; equivalent to the case where the filter function did not
290 exist.
291 The "post_blockstart" Stage
293 void (*post_blockstart)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
294 Invoked after the "block_start()" function has been called. This hook
296 stage may wish to perform any alterations of "PL_compcv" or related,
297 inspect or alter the lexical pad, provide hints hash values, or any
298 other tasks before the signature and code body are parsed.
299 Parse Body
301 At this point, the main body of the function is parsed and the optree
302 is stored in the "body" field of the context. If the perl version
303 supports sub signatures and they are enabled and found, the body will
304 be prefixed with the signature ops as well.
305 The "pre_blockend" Stage
307 void (*pre_blockend)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
308 Invoked just before the "block_end()" function is invoked. The hook
310 stage may wish to inspect or alter the optree stored in the "body"
311 context field.
312 The "post_newcv" Stage
314 void (*post_newcv)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
315 Invoked just after "newATTRSUB()" has been invoked on the optree. The
317 hook stage may wish to inspect or alter the CV stored in the "cv"
318 context field.
319
321 Paul Evans <leonerd@leonerd.org.uk>
322perl v5.34.0 2022-01-21 XS::Parse::Sublike(3)