1XS::Parse::Infix(3pm) User Contributed Perl DocumentationXS::Parse::Infix(3pm)
2
6 "XS::Parse::Infix" - XS functions to assist in parsing infix operators
7
9 This module provides some XS functions to assist in writing syntax
10 modules that provide new infix operators as perl syntax, primarily for
11 authors of syntax plugins. It is unlikely to be of much use to anyone
12 else; and highly unlikely to be of any use when writing perl code using
13 these. Unless you are writing a syntax plugin using XS, this module is
14 not for you.
15 This module is also currently experimental, and the design is still
17 evolving and subject to change. Later versions may break ABI
18 compatibility, requiring changes or at least a rebuild of any module
19 that depends on it.
20 In addition, the places this functionality can be used are relatively
22 small. Support for custom infix operators as added in Perl development
23 release "v5.37.7", and is therefore present in Perl "v5.38.0".
24 In addition, the various "XPK_INFIX_*" token types of
26 XS::Parse::Keyword support querying on this module, so some syntax
27 provided by other modules may be able to make use of these new infix
28 operators.
29
31 HAVE_PL_INFIX_PLUGIN
32 if( XS::Parse::Infix::HAVE_PL_INFIX_PLUGIN ) { ... }
33 This constant is true if built on a perl that supports the
35 "PL_infix_plugin" extension mechanism, meaning that custom infix
36 operators registered with this module will actually be recognised by
37 the perl parser.
38 No actual production releases of perl yet support this feature, but see
40 above for details of development versions which do.
41
43 boot_xs_parse_infix
44 void boot_xs_parse_infix(double ver);
45 Call this function from your "BOOT" section in order to initialise the
47 module and parsing hooks.
48 ver should either be 0 or a decimal number for the module version
50 requirement; e.g.
51 boot_xs_parse_infix(0.14);
53 parse_infix
55 bool parse_infix(enum XSParseInfixSelection select, struct XSParseInfixInfo **infop);
56 Since version 0.27.
58 This function attempts to parse syntax for an infix operator from the
60 current parser position. If it is successful, it fills in the variable
61 pointed to by infop with a pointer to the actual information structure
62 and returns "true". If no suitable operator is found, returns "false".
63 xs_parse_infix_new_op
65 OP *xs_parse_infix_new_op(const struct XSParseInfixInfo *info, U32 flags,
66 OP *lhs, OP *rhs);
67 This function constructs a new optree fragment to represent invoking
69 the infix operator with the given operands. It should be used much the
70 same as core perl's "newBINOP" function.
71 The "info" structure pointer would be obtained from the "infix" field
73 of the result of invoking the various "XPK_INFIX_*" token types from
74 "XS::Parse::Keyword", or by calling "parse_infix" directly.
75 register_xs_parse_infix
77 void register_xs_parse_infix(const char *opname,
78 const struct XSParseInfixHooks *hooks, void *hookdata);
79 This function installs a set of parsing hooks to be associated with the
81 given operator name. This new operator will then be available via
82 XS::Parse::Keyword by the various "XPK_INFIX_*" token types,
83 "parse_infix", or to core perl's "PL_infix_plugin" if available.
84 These tokens will all yield an info structure, with the following
86 fields:
87 struct XSParseInfixInfo {
89 const char *opname;
90 OPCODE opcode; /* for built-in operators, or OP_CUSTOM for
91 custom-registered ones */
92 struct XSParseInfixHooks *hooks;
94 void *hookdata;
95 enum XSParseInfixClassification cls; /* since version 0.28 */
97 };
98 If the operator name contains any non-ASCII characters they are
100 presumed to be in UTF-8 encoding. This will matter for deparse
101 purposes.
102
104 The "XSParseInfixHooks" structure provides the following fields which
105 are used at various stages of parsing.
106 struct XSParseInfixHooks {
108 U16 flags; /* currently ignored */
109 U8 lhs_flags;
110 U8 rhs_flags;
111 enum XSParseInfixClassification cls;
112 const char *wrapper_func_name;
114 const char *permit_hintkey;
116 bool (*permit)(pTHX_ void *hookdata);
117 OP *(*new_op)(pTHX_ U32 flags, OP *lhs, OP *rhs, SV **parsedata, void *hookdata);
119 OP *(*ppaddr)(pTHX);
120 /* optional */
122 void (*parse)(pTHX_ U32 flags, SV **parsedata, void *hookdata);
123 };
124 Flags
126 The "flags" field is currently ignored. It is defined simply to reserve
127 the space in case used in a later version. It should be set to zero.
128 The "lhs_flags" and "rhs_flags" fields give details on how to handle
130 the left- and right-hand side operands, respectively.
131 It should be set to one of the following constants, or left as zero:
133 XPI_OPERAND_TERM_LIST
135 The operand will be foced into list context, preserving the
136 "OP_PUSHMARK" at the beginning. This means that the ppfunc for this
137 infix operator will have to "POPMARK" to find that.
138 XPI_OPERAND_LIST
140 The same as above.
141 Older versions used to provide constants named "XPI_OPERAND_ARITH" and
143 "XPI_OPERAND_TERM" but they related to an older version of the core
144 perl branch. These names are now aliases for zero, and can be removed
145 from new code.
146 In addition the following extra bitflags are defined:
148 XPI_OPERAND_ONLY_LOOK
150 If set, the operator function promises that it will not mutate any
151 of its passed values, nor allow leaking of direct alias pointers to
152 them via return value or other locations.
153 This flag is optional; omitting it when applicable will not change
155 any observed behaviour. Setting it may enable certain optimisations
156 to be performed.
157 Currently, this flag simply enables an optimisation in the call-
159 checker for infix operator wrapper functions that take list-shaped
160 operands. This optimisation discards an "OP_ANONLIST" operation
161 which would create a temporary anonymous array reference for its
162 operand values, allowing a slight saving of memory use and CPU
163 time. This optimisation is only safe to perform if the operator
164 does not mutate or retain aliases of any of the arguments, as
165 otherwise the caller might see unexpected modifications or value
166 references to the values passed.
167 The Selection Stage
169 The "cls" field gives a "classification" of the operator, suggesting
170 what sort of operation it provides. This is used as a filter by the
171 various "XS::Parse::Keyword" selection macros.
172 The classification should be one of the "XPI_CLS_*" constants found and
174 described further in the main XSParseInfix.h file.
175 The "permit" Stage
177 As a shortcut for the common case, the "permit_hintkey" may point to a
178 string to look up from the hints hash. If the given key name is not
179 found in the hints hash then the keyword is not permitted. If the key
180 is present then the "permit" function is invoked as normal.
181 If not rejected by a hint key that was not found in the hints hash, the
183 function part of the stage is called next and should inspect whether
184 the keyword is permitted at this time perhaps by inspecting other
185 lexical clues, and return true only if the keyword is permitted.
186 Both the string and the function are optional. Either or both may be
188 present. If neither is present then the keyword is always permitted -
189 which is likely not what you wanted to do.
190 The "parse" Stage
192 If the optional "parse" hook function is present, it is called
193 immediately after the parser has recognised the presence of the named
194 operator itself but before it attempts to consume the right-hand side
195 term. This hook function can attempt further parsing, in order to
196 implement more complex syntax such as hyper-operators.
197 When invoked, it is passed a pointer to an "SV *"-typed storage
199 variable. It is free to use this variable it desires to store a result,
200 which will then later be made available to the "new_op" function.
201 The Op Generation Stage
203 If the infix operator is going to be used, then one of the "new_op" or
204 the "ppaddr" fields explain how to create a new optree fragment.
205 If "new_op" is defined then it will be used, and is expected to return
207 an optree fragment that consumes the LHS and RHS arguments to implement
208 the semantics of the operator. If the optional "parse" stage had been
209 present earlier, the "SV **" pointer passed here will point to the same
210 storage that "parse" had previously had access to, so it can retrieve
211 the results.
212 If "new_op" is not present, then the "ppaddr" will be used instead to
214 construct a new BINOP of the "OP_CUSTOM" type. If an earlier "parse"
215 stage had stored additional results into the "SV *" variable these will
216 be lost here.
217 The Wrapper Function
219 Additionally, if the "wrapper_func_name" field is set to a string, this
220 gives the (fully-qualified) name for a function to be generated as part
221 of registering the operator. This newly-generated function will act as
222 a wrapper for the operator.
223 For operators whose RHS is a scalar, the wrapper function is assumed to
225 take two simple scalar arguments. The result of invoking the function
226 on those arguments will be determined by using the operator code.
227 $result = $lhs OP $rhs;
229 $result = WRAPPERFUNC( $lhs, $rhs );
231 For operators whose RHS is a list, the wrapper function takes at least
233 one argument, possibly more. The first argument is the scalar on the
234 LHS, and the remaining arguments, however many there are, form the RHS:
235 $result = $lhs OP @rhs;
237 $result = WRAPPERFUNC( $lhs, @rhs );
239 For operators whose LHS and RHS is a list, the wrapper function takes
241 two arguments which must be array references containing the lists.
242 $result = @lhs OP @rhs;
244 $result = WRAPPERFUNC( \@lhs, \@rhs );
246 This creates a convenience for accessing the operator from perls that
248 do not support "PL_infix_plugin".
249 In the case of scalar infix operators, the wrapper function also
251 includes a call-checker which attempts to inline the operator directly
252 into the callsite. Thus, in simple cases where the function is called
253 directly on exactly two scalar arguments (such as in the following), no
254 "ENTERSUB" overhead will be incurred and the generated optree will be
255 identical to that which would have been generated by using infix
256 operator syntax directly:
257 WRAPPERFUNC( $lhs, $rhs );
259 WRAPPERFUNC( $lhs, CONSTANT );
260 WRAPPERFUNC( $args[0], $args[1] );
261 WRAPPERFUNC( $lhs, scalar otherfunc() );
262 The checker is very pessimistic and will only rewrite callsites where
264 it determines this can be done safely. It will not rewrite any of the
265 following forms:
266 WRAPPERFUNC( $onearg ); # not enough args
268 WRAPPERFUNC( $x, $y, $z ); # too many args
269 WRAPPERFUNC( @args[0,1] ); # not a scalar
270 WRAPPERFUNC( $lhs, otherfunc() ); # not a scalar
271 The wrapper function for infix operators which take lists on both sides
273 also has a call-checker which will attempt to inline the operator in
274 similar circumstances. In addition to the optimisations described above
275 for scalar operators, this checker will also inline an array-reference
276 operator and omit the resulting dereference behaviour. Thus, the two
277 following lines emit the same optree, without an "OP_SREFGEN" or
278 "OP_RV2AV":
279 @lhs OP @rhs;
281 WRAPPERFUNC( \@lhs, \@rhs );
282 Note that technically, this optimisation isn't strictly transparent in
284 the odd cornercase that one of the referenced arrays is also the
285 backing store for a blessed object reference, and that object class has
286 a "@{}" overload.
287 my @arr;
289 package SomeClass {
290 use overload '@{}' => sub { return ["values", "go", "here"]; };
291 }
292 bless \@arr, "SomeClass";
293 # this will not actually invoke the overload operator
295 WRAPPERFUNC( \@arr, [4, 5, 6] );
296 As this cornercase relates to taking duplicate references to the same
298 blessed object's backing store variable, it should not matter to any
299 real code; regular objects that are passed by reference into the
300 wrapper function will run their overload methods as normal.
301 The callchecker for list operands can optionally also discard an op of
303 the "OP_ANONLIST" type, which is used by anonymous array-ref
304 construction:
305 ($u, $v, $w) OP ($x, $y, $z);
307 WRAPPERFUNC( [$u, $v, $w], [$x, $y, $z] );
308 This optimisation is only performed if the operator declared it safe to
310 do so, via the "XPI_OPERAND_ONLY_LOOK" flag.
311 If a function of the given name already exists at registration time it
313 will be left undisturbed and no new wrapper will be created. This
314 permits the same infix operator to have multiple spellings of its name;
315 for example to allow both a real Unicode and a fallback ASCII
316 transliteration of the same operator. The first registration will
317 create the wrapper function; the subsequent one will skip it because it
318 would otherwise be identical.
319 Note that when generating an optree for a wrapper function call, the
321 "new_op" hook function will be invoked with a "NULL" pointer for the
322 "SV *"-typed parse data storage, as there won't be an opporunity for
323 the "parse" hook to run in this case.
324
326 This module operates with B::Deparse in order to automatically provide
327 deparse support for infix operators. Every infix operator that is
328 implemented as a custom op (and thus has the "ppaddr" hook field set)
329 will have deparse logic added. This will allow it to deparse to either
330 the named wrapper function, or to the infix operator syntax if on a
331 "PL_infix_plugin"-enabled perl and the appropriate lexical hint is
332 enabled at the callsite.
333 In order for this to work, it is important that your custom operator is
335 not registered as a custom op using the Perl_register_custom_op()
336 function. This registration will be performed by "XS::Parse::Infix"
337 itself at the time the infix operator is registered.
338
340 • Have the entersub checker for list/list operators unwrap arrayref
341 or anon-array argument forms ("WRAPPERFUNC( \@lhs, \@rhs )" or
342 "WRAPPERFUNC( [LHS], [RHS] )").
343 • Further thoughts about how infix operators with "parse" hooks will
345 work with automatic deparse, and also how to integrate them with
346 XS::Parse::Keyword's grammar piece.
347
349 Paul Evans <leonerd@leonerd.org.uk>
350perl v5.38.0 2023-08-09 XS::Parse::Infix(3pm)