1Devel::CallParser(3)  User Contributed Perl Documentation Devel::CallParser(3)
2
3
4

NAME

6       Devel::CallParser - custom parsing attached to subroutines
7

SYNOPSIS

9               # to generate header prior to XS compilation
10
11               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
16               # in Perl part of module
17
18               use Devel::CallParser;
19
20               /* in XS */
21
22               #include "callparser0.h"
23
24               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
28               #include "callparser1.h"
29
30               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
34               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

DESCRIPTION

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

CONSTANTS

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
67           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
80           This header is only available on Perl versions 5.11.2 and higher.
81
82       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
93           This header is only available on Perl versions 5.13.8 and higher.
94
95       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

C FUNCTIONS

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
107           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
111               argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);
112
113           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
122           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
133           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
138                   void cv_get_call_parser(CV *cv, Perl_call_parser *psfun_p,
139                           SV **psobj_p)
140
141       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
147           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
151               argsop = (*psfun_p)(aTHX_ namegv, (*psobj_p), &flags);
152
153           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
162           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
173           The current setting for a particular CV can be retrieved by
174           "cv_get_call_parser".
175
176                   void cv_set_call_parser(CV *cv, Perl_call_parser psfun,
177                           SV *psobj)
178
179       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
186           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
190                   OP *parse_args_parenthesised(U32 *flags_p)
191
192       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
198           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
202                   OP *parse_args_nullary(U32 *flags_p)
203
204       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
212           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
216                   OP *parse_args_unary(U32 *flags_p)
217
218       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
226           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
230                   OP *parse_args_list(U32 *flags_p)
231
232       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
242           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
246                   OP *parse_args_block_list(U32 *flags_p)
247
248       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
257           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
263           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
266           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
270                   OP *parse_args_proto(GV *namegv, SV *protosv, U32 *flags_p)
271
272       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
281           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
289           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
292           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
296                   OP *parse_args_proto_or_list(GV *namegv, SV *protosv,
297                           U32 *flags_p)
298

BUGS

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
304       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
312       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

SEE ALSO

321       Devel::CallChecker
322

AUTHOR

324       Andrew Main (Zefram) <zefram@fysh.org>
325
327       Copyright (C) 2011, 2013 Andrew Main (Zefram) <zefram@fysh.org>
328

LICENSE

330       This module is free software; you can redistribute it and/or modify it
331       under the same terms as Perl itself.
332
333
334
335perl v5.32.1                      2021-01-27              Devel::CallParser(3)
Impressum