1XS::Parse::Sublike(3) User Contributed Perl DocumentationXS::Parse::Sublike(3)
2
3
4

NAME

6       "XS::Parse::Sublike" - XS functions to assist in parsing "sub"-like
7       syntax
8

DESCRIPTION

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
17       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

XS FUNCTIONS

23   boot_xs_parse_sublike
24         void boot_xs_parse_sublike(double ver)
25
26       Call this function from your "BOOT" section in order to initialise the
27       module and parsing hooks.
28
29       ver should either be 0 or a decimal number for the module version
30       requirement; e.g.
31
32          boot_xs_parse_sublike(0.04);
33
34   xs_parse_sublike
35          int xs_parse_sublike(const struct XSParseSublikeHooks *hooks, void *hookdata, OP **op_ptr)
36
37       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
45       For a more automated handling of keywords, see
46       "register_xs_parse_sublike".
47
48       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
53   register_xs_parse_sublike
54          void register_xs_parse_sublike(const char *keyword,
55            const struct XSParseSublikeHooks *hooks, void *hookdata)
56
57       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
61       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
66       hookdata is an opaque pointer which is passed through to each of the
67       hook stage functions when they are invoked.
68
69   xs_parse_sublike_any
70          int xs_parse_sublike_any(const struct XSParseSublikeHooks *hooks, void *hookdata,
71            OP **op_ptr)
72
73       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
81       If a regular "sub" is encountered, then this is parsed using the hooks
82       in a similar way to xs_parse_sublike().
83
84       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
92       hookdata is an opaque pointer which is passed through to each of the
93       hook stage functions when they are invoked.
94
95       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

PARSE CONTEXT

100       The various hook stages all share state about the ongoing parse process
101       using various fields of the "XSParseSublikeContext" structure.
102
103          struct XSParseSublikeContext {
104             SV *name;
105             OP *attrs;
106             OP *body;
107             CV *cv;
108             U32 actions;
109             HV *moddata;
110          }
111
112       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
118       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
123       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
128       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
132           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
138       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
145       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
150       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
155       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

PARSE HOOKS

163       The "XSParseSublikeHooks" structure provides the following hook stages,
164       which are invoked in the given order.
165
166       The structure has a flags field, which controls various optional parts
167       of operation. The following flags are defined.
168
169       XS_PARSE_SUBLIKE_FLAG_FILTERATTRS
170           If set, the optional "filter_attr" stage will be invoked.
171
172       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
178       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
184       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
191       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
197       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
201       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
205       XS_PARSE_SUBLIKE_PART_NAME
206           The name of the function.
207
208       XS_PARSE_SUBLIKE_PART_ATTRS
209           The attributes of the function.
210
211           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
215       XS_PARSE_SUBLIKE_PART_SIGNATURE
216           The parameter signature of the function.
217
218           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
224       XS_PARSE_SUBLIKE_PART_BODY
225           The actual body of the function, expressed as a brace-delimited
226           block.
227
228           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
234           In this case, the "body" and "cv" fields of the context structure
235           will remain "NULL".
236
237           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
241   The "permit" Stage
242          const char *permit_hintkey
243          bool (*permit)(pTHX_ void *hookdata)
244
245       Called by the installed keyword parser hook which is used to handle
246       keywords registered by "register_xs_parse_sublike".
247
248       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
253       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
258       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
262   Parse Name
263       At this point, the optional name is parsed and filled into the "name"
264       field of the context.
265
266   The "pre_subparse" Stage
267          void (*pre_subparse)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
268
269       Invoked just before start_subparse() is called.
270
271   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
275   The optional "filter_attr" Stage
276          bool (*filter_attr)(pTHX_ struct XSParseSublikeContext *ctx,
277             SV *attr, SV *val, void *hookdata);
278
279       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
286       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 the
289       usual way; equivalent to the case where the filter function did not
290       exist.
291
292   The "post_blockstart" Stage
293          void (*post_blockstart)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
294
295       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
300   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
306   The "pre_blockend" Stage
307          void (*pre_blockend)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
308
309       Invoked just before the block_end() function is invoked. The hook stage
310       may wish to inspect or alter the optree stored in the "body" context
311       field.
312
313   The "post_newcv" Stage
314          void (*post_newcv)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
315
316       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

AUTHOR

321       Paul Evans <leonerd@leonerd.org.uk>
322
323
324
325perl v5.36.1                      2023-06-15             XS::Parse::Sublike(3)
Impressum