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
96 The various hook stages all share state about the ongoing parse process
97 using various fields of the "XSParseSublikeContext" structure.
98 struct XSParseSublikeContext {
100 SV *name;
101 OP *attrs;
102 OP *body;
103 CV *cv;
104 }
105
107 The "XSParseSublikeHooks" structure provides the following hook stages,
108 which are invoked in the given order.
109 The structure has a flags field, which controls various optional parts
111 of operation. The following flags are defined.
112 XS_PARSE_SUBLIKE_FLAG_FILTERATTRS
114 If set, the optional "filter_attr" stage will be invoked.
115 In addition there are two "U8" fields named require_parts and
117 skip_parts which control the behaviour of various parts of the syntax
118 which are usually optional. Any parts with bits set in require_parts
119 become non-optional, and an error if they are missing. Any parts with
120 bits set in skip_parts will skip the relevant part of the parsing
121 process.
122 When two sets of hooks are combined by the "xs_parse_sublike_any"
124 function, these bitmasks are accumulated together with inclusive or.
125 Any part required by either set of hooks will still be required; any
126 step skipped by either will be skipped entirely.
127 If the same bit is set in both fields then the relevant parsing step
129 will not be performed but it will still be an error for that section to
130 be missing. This is likely not useful.
131 Note that for skipped parts, only the actual parsing steps are skipped.
133 A hook function can still set the relevant fields in the context
134 structure anyway to force a particular value for those parts.
135 XS_PARSE_SUBLIKE_PART_NAME
137 The name of the function.
138 XS_PARSE_SUBLIKE_PART_ATTRS
140 The attributes of the function.
141 This part can be skipped, but the bit is ignored when in
143 require_parts. It is always permitted to not provide any additional
144 attributes to a function definition.
145 XS_PARSE_SUBLIKE_PART_SIGNATURE
147 The parameter signature of the function.
148 This part can be skipped, but the bit is ignored when in
150 require_parts. It is always permitted not to provide a signature
151 for a function definition, because such syntax only applies when
152 "use feature 'signatures'" is in effect, and only on supporting
153 perl versions.
154 The "permit" Stage
156 bool (*permit)(pTHX_ void *hookdata)
157 Called by the installed keyword parser hook which is used to handle
159 keywords registered by "register_xs_parse_sublike". This hook stage
160 should inspect whether the keyword is permitted at this time (typically
161 by inspecting the hints hash "GvHV(PL_hintgv)" for some imported key)
162 and return true only if the keyword is permitted.
163 Parse Name
165 At this point, the optional name is parsed and filled into the "name"
166 field of the context.
167 The "pre_subparse" Stage
169 void (*pre_subparse)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
170 Invoked just before "start_subparse()" is called.
172 Parse Attrs
174 At this point the optional sub attributes are parsed and filled into
175 the "attrs" field of the context, then "block_start()" is called.
176 The optional "filter_attr" Stage
178 bool (*filter_attr)(pTHX_ struct XSParseSublikeContext *ctx,
179 SV *attr, SV *val, void *hookdata);
180 If the flags field includes "XS_PARSE_SUBLIKE_FLAG_FILTERATTRS" then
182 each individual attribute is passed through this optional filter
183 function immediately as each is parsed. attr will be a string SV
184 containing the name of the attribute, and val will either be "NULL", or
185 a string SV containing the contents of the parens after its name
186 (without the parens themselves).
187 If the filter returns "true", it indicates that it has in some way
189 handled the attribute and it should not be added to the list given to
190 "newATTRSUB()". If the filter returns "false" it will be handled in
191 the usual way; equivalent to the case where the filter function did not
192 exist.
193 The "post_blockstart" Stage
195 void (*post_blockstart)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
196 Invoked after the "block_start()" function has been called. This hook
198 stage may wish to perform any alterations of "PL_compcv" or related,
199 inspect or alter the lexical pad, provide hints hash values, or any
200 other tasks before the signature and code body are parsed.
201 Parse Body
203 At this point, the main body of the function is parsed and the optree
204 is stored in the "body" field of the context. If the perl version
205 supports sub signatures and they are enabled and found, the body will
206 be prefixed with the signature ops as well.
207 The "pre_blockend" Stage
209 void (*pre_blockend)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
210 Invoked just before the "block_end()" function is invoked. The hook
212 stage may wish to inspect or alter the optree stored in the "body"
213 context field.
214 The "post_newcv" Stage
216 void (*post_newcv)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
217 Invoked just after "newATTRSUB()" has been invoked on the optree. The
219 hook stage may wish to inspect or alter the CV stored in the "cv"
220 context field.
221
223 Paul Evans <leonerd@leonerd.org.uk>
224perl v5.32.0 2021-01-21 XS::Parse::Sublike(3)