1Devel::CallParser(3pm)User Contributed Perl DocumentationDevel::CallParser(3pm)
2
6 Devel::CallParser - custom parsing attached to subroutines
7
9 # to generate header prior to XS compilation
10 perl -MDevel::CallParser=callparser0_h \
12 -e 'print callparser0_h' > callparser0.h
13 perl -MDevel::CallParser=callparser1_h \
14 -e 'print callparser1_h' > callparser1.h
15 # in Perl part of module
17 use Devel::CallParser;
19 /* in XS */
21 #include "callparser0.h"
23 cv_get_call_parser(cv, &psfun, &psobj);
25 static OP *my_psfun(pTHX_ GV *namegv, SV *psobj, U32 *flagsp);
26 cv_set_call_parser(cv, my_psfun, psobj);
27 #include "callparser1.h"
29 cv_get_call_parser(cv, &psfun, &psobj);
31 static OP *my_psfun(pTHX_ GV *namegv, SV *psobj, U32 *flagsp);
32 cv_set_call_parser(cv, my_psfun, psobj);
33 args = parse_args_parenthesised(&flags);
35 args = parse_args_nullary(&flags);
36 args = parse_args_unary(&flags);
37 args = parse_args_list(&flags);
38 args = parse_args_block_list(&flags);
39 args = parse_args_proto(namegv, protosv, &flags);
40 args = parse_args_proto_or_list(namegv, protosv, &flags);
41
43 This module provides a C API, for XS modules, concerned with custom
44 parsing. It is centred around the function "cv_set_call_parser", which
45 allows XS code to attach a magical annotation to a Perl subroutine,
46 resulting in resolvable calls to that subroutine having their arguments
47 parsed by arbitrary C code. (This is a more conveniently structured
48 facility than the core's "PL_keyword_plugin" API.) This module makes
49 "cv_set_call_parser" and several supporting functions available.
50 This module provides the implementation of the functions at runtime.
52 It also, at compile time, supplies the C header file and link library
53 which provide access to the functions. In normal use,
54 "callparser0_h"/"callparser1_h" and "callparser_linkable" should be
55 called at build time (not authoring time) for the module that wishes to
56 use the C functions.
57
59 callparser0_h
60 Content of a C header file, intended to be named ""callparser0.h"".
61 It is to be included in XS code, and "perl.h" must be included
62 first. When the XS module is loaded at runtime, the
63 "Devel::CallParser" module must be loaded first. This will result
64 in a limited form of the C functions "cv_get_call_parser" and
65 "cv_set_call_parser" being available to the XS code.
66 The "cv_get_call_parser" and "cv_set_call_parser" functions
68 supplied by this header are mostly as described below. However,
69 for subroutines that have default argument parsing behaviour,
70 "cv_get_call_parser" will return null pointers for the parsing
71 function and its SV argument, rather than pointing to a real
72 function that implements default parsing. Correspondingly,
73 "cv_set_call_parser" will accept such a pair of null pointers to
74 restore default argument parsing for a subroutine. The advantage
75 of these modified semantics is that this much of the functionality
76 is available on Perl versions where it is not possible to implement
77 standard argument parsing as a distinct function. This is the case
78 on all Perl versions prior to 5.13.8.
79 This header is only available on Perl versions 5.11.2 and higher.
81 callparser1_h
83 Content of a C header file, intended to be named ""callparser1.h"".
84 It is to be included in XS code, and "perl.h" must be included
85 first. When the XS module is loaded at runtime, the
86 "Devel::CallParser" module must be loaded first. This will result
87 in the C functions "cv_get_call_parser", "cv_set_call_parser",
88 "parse_args_parenthesised", "parse_args_nullary",
89 "parse_args_unary", "parse_args_list", "parse_args_block_list",
90 "parse_args_proto", and "parse_args_proto_or_list", as defined
91 below, being available to the XS code.
92 This header is only available on Perl versions 5.13.8 and higher.
94 callparser_linkable
96 List of names of files that must be used as additional objects when
97 linking an XS module that uses the C functions supplied by this
98 module. This list will be empty on many platforms.
99
101 cv_get_call_parser
102 Retrieves the function that will be used to parse the arguments for
103 a call to cv. Specifically, the function is used for a subroutine
104 call, not marked with "&", where the callee can be identified at
105 compile time as cv.
106 The C-level function pointer is returned in *psfun_p, and an SV
108 argument for it is returned in *psobj_p. The function is intended
109 to be called in this manner:
110 argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);
112 This call is to be made when the parser has just scanned and
114 accepted a bareword and determined that it begins the syntax of a
115 call to cv. namegv is a GV supplying the name that should be used
116 by the parsing function to refer to the callee if it needs to emit
117 any diagnostics, and flags is a "U32" that the parsing function can
118 write to as an additional output. It is permitted to apply the
119 parsing function in non-standard situations, such as to a call to a
120 different subroutine.
121 The parsing function's main output is an op tree describing a list
123 of argument expressions. This may be null for an empty list. The
124 argument expressions will be combined with the expression that
125 identified cv and used to build an "entersub" op describing a
126 complete subroutine call. The parsing function may also set flag
127 bits in flags for special effects. The bit "CALLPARSER_PARENS"
128 indicates that the argument list was fully parenthesised, which
129 makes a difference only in obscure situations. The bit
130 "CALLPARSER_STATEMENT" indicates that what was parsed was
131 syntactically not an expression but a statement.
132 By default, the parsing function is Perl_parse_args_proto_or_list,
134 and the SV parameter is cv itself. This implements standard
135 subroutine argument parsing. It can be changed, for a particular
136 subroutine, by "cv_set_call_parser".
137 void cv_get_call_parser(CV *cv, Perl_call_parser *psfun_p,
139 SV **psobj_p)
140 cv_set_call_parser
142 Sets the function that will be used to parse the arguments for a
143 call to cv. Specifically, the function is used for a subroutine
144 call, not marked with "&", where the callee can be identified at
145 compile time as cv.
146 The C-level function pointer is supplied in psfun, and an SV
148 argument for it is supplied in psobj. The function is intended to
149 be called in this manner:
150 argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);
152 This call is to be made when the parser has just scanned and
154 accepted a bareword and determined that it begins the syntax of a
155 call to cv. namegv is a GV supplying the name that should be used
156 by the parsing function to refer to the callee if it needs to emit
157 any diagnostics, and flags is a "U32" that the parsing function can
158 write to as an additional output. It is permitted to apply the
159 parsing function in non-standard situations, such as to a call to a
160 different subroutine.
161 The parsing function's main output is an op tree describing a list
163 of argument expressions. This may be null for an empty list. The
164 argument expressions will be combined with the expression that
165 identified cv and used to build an "entersub" op describing a
166 complete subroutine call. The parsing function may also set flag
167 bits in flags for special effects. The bit "CALLPARSER_PARENS"
168 indicates that the argument list was fully parenthesised, which
169 makes a difference only in obscure situations. The bit
170 "CALLPARSER_STATEMENT" indicates that what was parsed was
171 syntactically not an expression but a statement.
172 The current setting for a particular CV can be retrieved by
174 "cv_get_call_parser".
175 void cv_set_call_parser(CV *cv, Perl_call_parser psfun,
177 SV *psobj)
178 parse_args_parenthesised
180 Parse a parenthesised argument list for a subroutine call. The
181 argument list consists of an optional expression enclosed in
182 parentheses. This is the syntax that is used for any subroutine
183 call where the first thing following the subroutine name is an open
184 parenthesis. It is used regardless of the subroutine's prototype.
185 The op tree representing the argument list is returned. The bit
187 "CALLPARSER_PARENS" is set in *flags_p, to indicate that the
188 argument list was fully parenthesised.
189 OP *parse_args_parenthesised(U32 *flags_p)
191 parse_args_nullary
193 Parse an argument list for a call to a subroutine that is
194 syntactically a nullary function. The argument list is either
195 parenthesised or completely absent. This is the syntax that is
196 used for a call to a subroutine with a "()" prototype.
197 The op tree representing the argument list is returned. The bit
199 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
200 parenthesised.
201 OP *parse_args_nullary(U32 *flags_p)
203 parse_args_unary
205 Parse an argument list for a call to a subroutine that is
206 syntactically a unary function. The argument list is either
207 parenthesised, absent, or consists of an unparenthesised arithmetic
208 expression. This is the syntax that is used for a call to a
209 subroutine with prototype "($)", "(;$)", or certain similar
210 prototypes.
211 The op tree representing the argument list is returned. The bit
213 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
214 parenthesised.
215 OP *parse_args_unary(U32 *flags_p)
217 parse_args_list
219 Parse an argument list for a call to a subroutine that is
220 syntactically a list function. The argument list is either
221 parenthesised, absent, or consists of an unparenthesised list
222 expression. This is the syntax that is used for a call to a
223 subroutine with any prototype that does not have special handling
224 (such as "(@)" or "($$)") or with no prototype at all.
225 The op tree representing the argument list is returned. The bit
227 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
228 parenthesised.
229 OP *parse_args_list(U32 *flags_p)
231 parse_args_block_list
233 Parse an argument list for a call to a subroutine that is
234 syntactically a block-and-list function. The argument list is
235 either parenthesised, absent, an unparenthesised list expression,
236 or consists of a code block followed by an optionl list expression.
237 Where the first thing seen is an open brace, it is always
238 interpreted as a code block. This is the syntax that is used for a
239 call to a subroutine with any prototype beginning with "&", such as
240 "(&@)" or "(&$)".
241 The op tree representing the argument list is returned. The bit
243 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
244 parenthesised.
245 OP *parse_args_block_list(U32 *flags_p)
247 parse_args_proto
249 Parse a subroutine argument list based on a subroutine prototype.
250 The syntax used for the argument list will be that implemented by
251 "parse_args_nullary", "parse_args_unary", "parse_args_list", or
252 "parse_args_block_list", depending on the prototype. This is the
253 standard treatment used on a subroutine call, not marked with "&",
254 where the callee can be identified at compile time and has a
255 prototype.
256 protosv supplies the subroutine prototype to be applied to the
258 call. It may be a normal defined scalar, of which the string value
259 will be used. Alternatively, for convenience, it may be a
260 subroutine object (a "CV*" that has been cast to "SV*") which has a
261 prototype.
262 The namegv parameter would be used to refer to the callee if
264 required in any error message, but currently no message does so.
265 The op tree representing the argument list is returned. The bit
267 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
268 parenthesised.
269 OP *parse_args_proto(GV *namegv, SV *protosv, U32 *flags_p)
271 parse_args_proto_or_list
273 Parse a subroutine argument list either based on a subroutine
274 prototype or using default list-function syntax. The syntax used
275 for the argument list will be that implemented by
276 "parse_args_nullary", "parse_args_unary", "parse_args_list", or
277 "parse_args_block_list", depending on the prototype. This is the
278 standard treatment used on a subroutine call, not marked with "&",
279 where the callee can be identified at compile time.
280 protosv supplies the subroutine prototype to be applied to the
282 call, or indicates that there is no prototype. It may be a normal
283 scalar, in which case if it is defined then the string value will
284 be used as a prototype, and if it is undefined then there is no
285 prototype. Alternatively, for convenience, it may be a subroutine
286 object (a "CV*" that has been cast to "SV*"), of which the
287 prototype will be used if it has one.
288 The namegv parameter would be used to refer to the callee if
290 required in any error message, but currently no message does so.
291 The op tree representing the argument list is returned. The bit
293 "CALLPARSER_PARENS" is set in *flags_p if the argument list was
294 parenthesised.
295 OP *parse_args_proto_or_list(GV *namegv, SV *protosv,
297 U32 *flags_p)
298
300 Due to reliance on Perl core features to do anything interesting, only
301 a very limited form of custom parsing is possible prior to Perl 5.13.8,
302 and none at all prior to Perl 5.11.2.
303 The way this module determines which parsing code to use for a
305 subroutine conflicts with the expectations of some particularly tricky
306 modules that use nasty hacks to perform custom parsing without proper
307 support from the Perl core. In particular, this module is incompatible
308 with versions of Devel::Declare prior to 0.006004 and versions of
309 Data::Alias prior to 1.13. An arrangement has been reached that allows
310 later versions of those modules to coexist with this module.
311 Custom parsing code is only invoked if the subroutine to which it is
313 attached is invoked using an unqualified name. For example, the name
314 "foo" works, but the name "main::foo" will not, despite referring to
315 the same subroutine. This is an unavoidable limitation imposed by the
316 core's interim facility for custom parser plugins. This should be
317 resolved if the API provided by this module, or something similar,
318 migrates into the core in a future version of Perl.
319
321 Devel::CallChecker
322
324 Andrew Main (Zefram) <zefram@fysh.org>
325
327 Copyright (C) 2011, 2013 Andrew Main (Zefram) <zefram@fysh.org>
328
330 This module is free software; you can redistribute it and/or modify it
331 under the same terms as Perl itself.
332perl v5.38.0 2023-07-20 Devel::CallParser(3pm)