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

PARSE CONTEXT

96       The various hook stages all share state about the ongoing parse process
97       using various fields of the "XSParseSublikeContext" structure.
98
99          struct XSParseSublikeContext {
100             SV *name;
101             OP *attrs;
102             OP *body;
103             CV *cv;
104          }
105

PARSE HOOKS

107       The "XSParseSublikeHooks" structure provides the following hook stages,
108       which are invoked in the given order.
109
110       The structure has a flags field, which controls various optional parts
111       of operation. The following flags are defined.
112
113       XS_PARSE_SUBLIKE_FLAG_FILTERATTRS
114           If set, the optional "filter_attr" stage will be invoked.
115
116       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
123       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
128       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
132       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
136       XS_PARSE_SUBLIKE_PART_NAME
137           The name of the function.
138
139       XS_PARSE_SUBLIKE_PART_ATTRS
140           The attributes of the function.
141
142           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
146       XS_PARSE_SUBLIKE_PART_SIGNATURE
147           The parameter signature of the function.
148
149           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
155   The "permit" Stage
156          bool (*permit)(pTHX_ void *hookdata)
157
158       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
164   Parse Name
165       At this point, the optional name is parsed and filled into the "name"
166       field of the context.
167
168   The "pre_subparse" Stage
169          void (*pre_subparse)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
170
171       Invoked just before "start_subparse()" is called.
172
173   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
177   The optional "filter_attr" Stage
178          bool (*filter_attr)(pTHX_ struct XSParseSublikeContext *ctx,
179             SV *attr, SV *val, void *hookdata);
180
181       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
188       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
194   The "post_blockstart" Stage
195          void (*post_blockstart)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
196
197       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
202   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
208   The "pre_blockend" Stage
209          void (*pre_blockend)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
210
211       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
215   The "post_newcv" Stage
216          void (*post_newcv)(pTHX_ struct XSParseSublikeContext *ctx, void *hookdata)
217
218       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

AUTHOR

223       Paul Evans <leonerd@leonerd.org.uk>
224
225
226
227perl v5.32.1                      2021-01-27             XS::Parse::Sublike(3)
Impressum