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 }
109
111 The "XSParseSublikeHooks" structure provides the following hook stages,
112 which are invoked in the given order.
113 The structure has a flags field, which controls various optional parts
115 of operation. The following flags are defined.
116 XS_PARSE_SUBLIKE_FLAG_FILTERATTRS
118 If set, the optional "filter_attr" stage will be invoked.
119 XS_PARSE_SUBLIKE_FLAG_BODY_OPTIONAL
121 If not set, the require_parts field will imply the
122 "XS_PARSE_SUBLIKE_PART_BODY" flag, making the body part required.
123 By setting this flag this will no longer happen. If all hooks
124 agree, then the body will become optional.
125 XS_PARSE_SUBLIKE_FLAG_PREFIX
127 If set, the keyword is considered to be a prefix that can be placed
128 in front of "sub" or another sub-like keyword, to add its set of
129 hooks in addition to those of the following keyword. These prefices
130 may be further stacked.
131 In addition there are two "U8" fields named require_parts and
133 skip_parts which control the behaviour of various parts of the syntax
134 which are usually optional. Any parts with bits set in require_parts
135 become non-optional, and an error if they are missing. Any parts with
136 bits set in skip_parts will skip the relevant part of the parsing
137 process.
138 When multiple sets of hooks are combined by the "xs_parse_sublike_any"
140 function, or as part of parsing prefixing keywords, these bitmasks are
141 accumulated together with inclusive or. Any part required by any set of
142 hooks will still be required; any step skipped by either will be
143 skipped entirely.
144 If the same bit is set in both fields then the relevant parsing step
146 will not be performed but it will still be an error for that section to
147 be missing. This is likely not useful.
148 Note that for skipped parts, only the actual parsing steps are skipped.
150 A hook function can still set the relevant fields in the context
151 structure anyway to force a particular value for those parts.
152 XS_PARSE_SUBLIKE_PART_NAME
154 The name of the function.
155 XS_PARSE_SUBLIKE_PART_ATTRS
157 The attributes of the function.
158 This part can be skipped, but the bit is ignored when in
160 require_parts. It is always permitted to not provide any additional
161 attributes to a function definition.
162 XS_PARSE_SUBLIKE_PART_SIGNATURE
164 The parameter signature of the function.
165 This part can be skipped, but the bit is ignored when in
167 require_parts. It is always permitted not to provide a signature
168 for a function definition, because such syntax only applies when
169 "use feature 'signatures'" is in effect, and only on supporting
170 perl versions.
171 XS_PARSE_SUBLIKE_PART_BODY
173 The actual body of the function, expressed as a brace-delimited
174 block.
175 This part cannot be skipped, but it can be made optional by
177 omitting it from the require_parts field. Instead of the block, it
178 is permitted to place a single semicolon (";") to act as a
179 statement terminator; thus giving the same syntax as a subroutine
180 forward declaration.
181 In this case, the "body" and "cv" fields of the context structure
183 will remain "NULL".
184 This flag is currently implied on the require_parts field if the
186 hook does not supply the "XS_PARSE_SUBLIKE_FLAG_BODY_OPTIONAL"
187 flag; meaning that most use-cases will make it a required part.
188 The "permit" Stage
190 const char *permit_hintkey
191 bool (*permit)(pTHX_ void *hookdata)
192 Called by the installed keyword parser hook which is used to handle
194 keywords registered by "register_xs_parse_sublike".
195 As a shortcut for the common case, the "permit_hintkey" may point to a
197 string to look up from the hints hash. If the given key name is not
198 found in the hints hash then the keyword is not permitted. If the key
199 is present then the "permit" function is invoked as normal.
200 If not rejected by a hint key that was not found in the hints hash, the
202 function part of the stage is called next and should inspect whether
203 the keyword is permitted at this time perhaps by inspecting other
204 lexical clues, and return true only if the keyword is permitted.
205 Both the string and the function are optional. Either or both may be
207 present. If neither is present then the keyword is always permitted -
208 which is likely not what you wanted to do.
209 Parse Name
211 At this point, the optional name is parsed and filled into the "name"
212 field of the context.
213 The "pre_subparse" Stage
215 void (*pre_subparse)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
216 Invoked just before "start_subparse()" is called.
218 Parse Attrs
220 At this point the optional sub attributes are parsed and filled into
221 the "attrs" field of the context, then "block_start()" is called.
222 The optional "filter_attr" Stage
224 bool (*filter_attr)(pTHX_ struct XSParseSublikeContext *ctx,
225 SV *attr, SV *val, void *hookdata);
226 If the flags field includes "XS_PARSE_SUBLIKE_FLAG_FILTERATTRS" then
228 each individual attribute is passed through this optional filter
229 function immediately as each is parsed. attr will be a string SV
230 containing the name of the attribute, and val will either be "NULL", or
231 a string SV containing the contents of the parens after its name
232 (without the parens themselves).
233 If the filter returns "true", it indicates that it has in some way
235 handled the attribute and it should not be added to the list given to
236 "newATTRSUB()". If the filter returns "false" it will be handled in
237 the usual way; equivalent to the case where the filter function did not
238 exist.
239 The "post_blockstart" Stage
241 void (*post_blockstart)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
242 Invoked after the "block_start()" function has been called. This hook
244 stage may wish to perform any alterations of "PL_compcv" or related,
245 inspect or alter the lexical pad, provide hints hash values, or any
246 other tasks before the signature and code body are parsed.
247 Parse Body
249 At this point, the main body of the function is parsed and the optree
250 is stored in the "body" field of the context. If the perl version
251 supports sub signatures and they are enabled and found, the body will
252 be prefixed with the signature ops as well.
253 The "pre_blockend" Stage
255 void (*pre_blockend)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
256 Invoked just before the "block_end()" function is invoked. The hook
258 stage may wish to inspect or alter the optree stored in the "body"
259 context field.
260 The "post_newcv" Stage
262 void (*post_newcv)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
263 Invoked just after "newATTRSUB()" has been invoked on the optree. The
265 hook stage may wish to inspect or alter the CV stored in the "cv"
266 context field.
267
269 Paul Evans <leonerd@leonerd.org.uk>
270perl v5.34.0 2021-10-29 XS::Parse::Sublike(3)