blib/lib/XS/Parse/Keyword.pm

filter: Statementstmt 100% 8 / 8 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 2 / 2 Podpod n/a totaltotal 100% 10 / 10 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« t/infix.xs ↑ Summary hax/make_argcheck_aux.c.inc »
1 # You may distribute under the terms of either the GNU General Public License
2 # or the Artistic License (the same terms as Perl itself)
3 #
4 # (C) Paul Evans, 2021-2023 -- leonerd@leonerd.org.uk
5  
6 package XS::Parse::Keyword 0.51;
7  
8 24 ▶use v5.14;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 24 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 24 require XSLoader;
12 24 XSLoader::load( __PACKAGE__, our $VERSION );
13  
14 =head1 NAME
15  
16 C<XS::Parse::Keyword> - XS functions to assist in parsing keyword syntax
17  
18 =head1 DESCRIPTION
19  
20 This module provides some XS functions to assist in writing syntax modules
21 that provide new perl-visible syntax, primarily for authors of keyword plugins
22 using the C<PL_keyword_plugin> hook mechanism. It is unlikely to be of much
23 use to anyone else; and highly unlikely to be any use when writing perl code
24 using these. Unless you are writing a keyword plugin using XS, this module is
25 not for you.
26  
27 This module is also currently experimental, and the design is still evolving
28 and subject to change. Later versions may break ABI compatibility, requiring
29 changes or at least a rebuild of any module that depends on it.
30  
31 =cut
32  
33 =head1 XS FUNCTIONS
34  
35 =for highlighter language=c
36  
37 =head2 boot_xs_parse_keyword
38  
39 void boot_xs_parse_keyword(double ver);
40  
41 Call this function from your C<BOOT> section in order to initialise the module
42 and parsing hooks.
43  
44 I<ver> should either be 0 or a decimal number for the module version
45 requirement; e.g.
46  
47 boot_xs_parse_keyword(0.14);
48  
49 =head2 register_xs_parse_keyword
50  
51 void register_xs_parse_keyword(const char *keyword,
52 const struct XSParseKeywordHooks *hooks, void *hookdata);
53  
54 This function installs a set of parsing hooks to be associated with the given
55 keyword. Such a keyword will then be handled automatically by a keyword parser
56 installed by C<XS::Parse::Keyword> itself.
57  
58 =cut
59  
60 =head1 PARSE HOOKS
61  
62 The C<XSParseKeywordHooks> structure provides the following hook stages, which
63 are invoked in the given order.
64  
65 =head2 flags
66  
67 The following flags are defined:
68  
69 =over 4
70  
71 =item C<XPK_FLAG_EXPR>
72  
73 The parse or build function is expected to return C<KEYWORD_PLUGIN_EXPR>.
74  
75 =item C<XPK_FLAG_STMT>
76  
77 The parse or build function is expected to return C<KEYWORD_PLUGIN_STMT>.
78  
79 These two flags are largely for the benefit of giving static information at
80 registration time to assist static parsing or other related tasks to know what
81 kind of grammatical element this keyword will produce.
82  
83 =item C<XPK_FLAG_AUTOSEMI>
84  
85 The syntax forms a complete statement, which should be followed by a statement
86 separator semicolon (C<;>). This semicolon is optional at the end of a block.
87  
88 The semicolon, if present, will be consumed automatically.
89  
90 =item C<XPK_FLAG_BLOCKSCOPE>
91  
92 The entire parse and build process will be wrapped in a pair of
93 C<block_start()> and C<block_end()> calls. This ensures that, for example, any
94 newly-introduced lexical variables do not escape from the scope of the syntax
95 created by the keyword.
96  
97 =item C<XPK_FLAG_PERMIT_LEXICAL>
98  
99 The keyword permits a prefixed C<my>, for the author to indicate that it
100 should have lexical effect. Typically this would only make sense for keywords
101 that declare some new named entity, where normally that keyword's entity is
102 named in the symbol table instead.
103  
104 At C<parse> and C<build> time, this fact will be indicated by
105 C<< PL_parser->in_my >> being set to the C<< KEY_my >> value, rather than its
106 usual zero.
107  
108 This flag is silently ignored on versions of Perl before 5.16, because on
109 earlier versions the C<my> prefix-detecting workaround causes
110 seemingly-unrelated parse failures in F<utf8.pm>.
111  
112 =back
113  
114 =head2 The C<permit> Stage
115  
116 const char *permit_hintkey;
117 bool (*permit) (pTHX_ void *hookdata);
118  
119 Called by the installed keyword parser hook which is used to handle keywords
120 registered by L</register_xs_parse_keyword>.
121  
122 As a shortcut for the common case, the C<permit_hintkey> may point to a string
123 to look up from the hints hash. If the given key name is not found in the
124 hints hash then the keyword is not permitted. If the key is present then the
125 C<permit> function is invoked as normal.
126  
127 If not rejected by a hint key that was not found in the hints hash, the
128 function part of the stage is called next and should inspect whether the
129 keyword is permitted at this time perhaps by inspecting other lexical clues,
130 and return true only if the keyword is permitted.
131  
132 Both the string and the function are optional. Either or both may be present.
133 If neither is present then the keyword is always permitted - which is likely
134 not what you wanted to do.
135  
136 =head2 The C<check> Stage
137  
138 void (*check)(pTHX_ void *hookdata);
139  
140 Invoked once the keyword has been permitted. If present, this hook function
141 can check the surrounding lexical context, state, or other information and
142 throw an exception if it is unhappy that the keyword should apply in this
143 position.
144  
145 =head2 The C<parse> Stage
146  
147 This stage is invoked once the keyword has been checked, and actually
148 parses the incoming text into an optree. It is implemented by calling the
149 B<first> of the following function pointers which is not NULL. The invoked
150 function may optionally build an optree to represent the parsed syntax, and
151 place it into the variable addressed by C<out>. If it does not, then a simple
152 C<OP_NULL> will be constructed in its place.
153  
154 C<lex_read_space()> is called both before and after this stage is invoked, so
155 in many simple cases the hook function itself does not need to bother with it.
156  
157 int (*parse)(pTHX_ OP **out, void *hookdata);
158  
159 If present, this should consume text from the parser buffer by invoking
160 C<lex_*> or C<parse_*> functions and eventually return a C<KEYWORD_PLUGIN_*>
161 result value.
162  
163 This is the most generic and powerful of the options, but requires the most
164 amount of implementation work.
165  
166 int (*build)(pTHX_ OP **out, XSParseKeywordPiece *args[], size_t nargs, void *hookdata);
167  
168 If C<parse> is not present, this is called instead after parsing a sequence of
169 arguments, of types given by the I<pieces> field; which should be a zero-
170 terminated array of piece types.
171  
172 This alternative is somewhat less generic and powerful than providing C<parse>
173 yourself, but involves much less parsing work and is shorter and easier to
174 implement.
175  
176 int (*build1)(pTHX_ OP **out, XSParseKeywordPiece *arg0, void *hookdata);
177  
178 If neither C<parse> nor C<build> are present, this is called as a simpler
179 variant of C<build> when only a single argument is required. It takes its type
180 from the C<piece1> field instead.
181  
182 =cut
183  
184 =head1 PIECES AND PIECE TYPES
185  
186 When using the C<build> or C<build1> alternatives for the C<parse> phase, the
187 actual syntax is parsed automatically by this module, according to the
188 specification given by the I<pieces> or I<piece1> field. The result of that
189 parsing step is placed into the I<args> or I<arg0> parameter to the invoked
190 function, using a C<struct> type consisting of the following fields:
191  
192 typedef struct {
193 union {
194 OP *op;
195 CV *cv;
196 SV *sv;
197 int i;
198 struct {
199 SV *name;
200 SV *value;
201 } attr;
202 PADOFFSET padix;
203 struct XSParseInfixInfo *infix;
204 };
205 int line;
206 } XSParseKeywordPiece;
207  
208 Which field of the anonymous union is set depends on the type of the piece.
209 The I<line> field contains the line number of the source file where parsing of
210 that piece began.
211  
212 Some piece types are "atomic", whose definition is self-contained. Others are
213 structural, defined in terms of inner pieces. Together these form an entire
214 tree-shaped definition of the syntax that the keyword expects to find.
215  
216 Atomic types generally provide exactly one argument into the list of I<args>
217 (with the exception of literal matches, which do not provide anything).
218 Structural types may provide an initial argument themselves, followed by a
219 list of the values of each sub-piece they contained inside them. Thus, while
220 the data structure defining the syntax shape is a tree, the argument values it
221 parses into is passed as a flat array to the C<build> function.
222  
223 Some structural types need to be able to determine whether or not syntax
224 relating some optional part of them is present in the incoming source text. In
225 this case, the pieces relating to those optional parts must support "probing".
226 This ability is also noted below.
227  
228 Many of the atomic piece types have a variant which is optional; if the given
229 input does not look like the expected syntax for the piece type then an
230 C<_OPT>-suffixed version of the type will instead yield C<NULL> in its result
231 pointer.
232  
233 The type of each piece should be one of the following macro values.
234  
235 =head2 XPK_BLOCK
236  
237 I<atomic, can probe, emits op.>
238  
239 XPK_BLOCK
240  
241 A brace-delimited block of code is expected, passed as an optree in the I<op>
242 field. This will be parsed as a block within the current function scope.
243  
244 This can be probed by checking for the presence of an open-brace (C<{>)
245 character.
246  
247 Be careful defining grammars with this because an open-brace is also a valid
248 character to start a term expression, for example. Given a choice between
249 C<XPK_BLOCK> and C<XPK_TERMEXPR>, either of them could try to consume such
250 code as
251  
252 { 123, 456 }
253  
254 =head2 XPK_BLOCK_VOIDCTX, XPK_BLOCK_SCALARCTX, XPK_BLOCK_LISTCTX
255  
256 Variants of C<XPK_BLOCK> which wrap a void, scalar or list-context scope
257 around the block.
258  
259 =head2 XPK_PREFIXED_BLOCK
260  
261 I<structural, emits op.>
262  
263 XPK_PREFIXED_BLOCK(pieces ...)
264  
265 Some pieces are expected, followed by a brace-delimited block of code, which
266 is passed as an optree in the I<op> field. The prefix pieces are parsed first,
267 and their results are passed before the block itself.
268  
269 The entire sequence, including the prefix items, is contained within a pair of
270 C<block_start()> / C<block_end()> calls. This permits the prefix pieces to
271 introduce new items into the lexical scope of the block - for example by the
272 use of C<XPK_LEXVAR_MY>.
273  
274 A call to C<intro_my()> is automatically made at the end of the prefix pieces,
275 before the block itself is parsed, ensuring any new lexical variables are now
276 visible.
277  
278 In addition, the following extra piece types are recognised here:
279  
280 =over 4
281  
282 =item XPK_SETUP
283  
284 void setup(pTHX_ void *hookdata);
285  
286 XPK_SETUP(&setup)
287  
288 I<atomic, emits nothing.>
289  
290 This piece type runs a function given by pointer. Typically this function may
291 be used to introduce new lexical state into the parser, or in some other way
292 have some side-effect on the parsing context of the block to be parsed.
293  
294 =back
295  
296 =head2 XPK_PREFIXED_BLOCK_ENTERLEAVE
297  
298 A variant of C<XPK_PREFIXED_BLOCK> which additionally wraps the entire parsing
299 operation, including the C<block_start()>, C<block_end()> and any calls to
300 C<XPK_SETUP> functions, within a C<ENTER>/C<LEAVE> pair.
301  
302 This should not make a difference to the standard parser pieces provided here,
303 but may be useful behaviour for the code in the setup function, especially if
304 it wishes to modify parser state and use the savestack to ensure it is
305 restored again when parsing has finished.
306  
307 =head2 XPK_ANONSUB
308  
309 I<atomic, emits cv.>
310  
311 A brace-delimited block of code is expected, and assembled into the body of a
312 new anonymous subroutine. This will be passed as a protosub CV in the I<cv>
313 field.
314  
315 =head2 XPK_STAGED_ANONSUB
316  
317 XPK_STAGED_ANONSUB(stages ...)
318  
319 I<structural, emits cv.>
320  
321 A variant of C<XPK_ANONSUB> which accepts additional function pointers to be
322 invoked at various points during parsing and compilation. These can be used to
323 interrupt the normal parsing in a manner similar to L<XS::Parse::Sublike>,
324 though currently somewhat less flexibly.
325  
326 The I<stages> list may contain elements of the following types. Not every
327 stage must be present, but any that are present must be in the following
328 order. Multiple copies of each stage are permitted; they are invoked in the
329 written order, with parser code happening inbetween.
330  
331 =over 4
332  
333 =item XPK_ANONSUB_PREPARE
334  
335 XPK_ANONSUB_PREPARE(&callback)
336  
337 I<atomic, emits nothing.>
338  
339 Invokes the callback before C<start_subparse()>.
340  
341 =item XPK_ANONSUB_START
342  
343 XPK_ANONSUB_START(&callback)
344  
345 I<atomic, emits nothing.>
346  
347 Invokes the callback after C<block_start()> but before parsing the actual
348 block contents.
349  
350 =item XPK_ANONSUB_END
351  
352 OP *op_wrapper_callback(pTHX_ OP *o, void *hookdata);
353  
354 XPK_ANONSUB_END(&op_wrapper_callback)
355  
356 I<atomic, emits nothing.>
357  
358 Invokes the callback after parsing the block contents but before calling
359 C<block_end()>. The callback may modify the optree if required and return a
360 new one.
361  
362 =item XPK_ANONSUB_WRAP
363  
364 XPK_ANONSUB_WRAP(&op_wrapper_callback)
365  
366 I<atomic, emits nothing.>
367  
368 Invokes the callback after C<block_end()> but before passing the optree to
369 C<newATTRSUB()>. The callback may modify the optree if required and return a
370 new one.
371  
372 =back
373  
374 =head2 XPK_ARITHEXPR. XPK_ARITHEXPR_OPT
375  
376 I<atomic, emits op.>
377  
378 XPK_ARITHEXPR
379  
380 An arithmetic expression is expected, parsed using C<parse_arithexpr()>, and
381 passed as an optree in the I<op> field.
382  
383 =head2 XPK_ARITHEXPR_VOIDCTX, XPK_ARITHEXPR_OPT
384  
385 =head2 XPK_ARITHEXPR_SCALARCTX, XPK_ARITHEXPR_SCALARCTX_OPT
386  
387 Variants of C<XPK_ARITHEXPR> which puts the expression in void or scalar context.
388  
389 =head2 XPK_TERMEXPR, XPK_TERMEXPR_OPT
390  
391 I<atomic, emits op.>
392  
393 XPK_TERMEXPR
394  
395 A term expression is expected, parsed using C<parse_termexpr()>, and passed as
396 an optree in the I<op> field.
397  
398 =head2 XPK_TERMEXPR_VOIDCTX, XPK_TERMEXPR_VOIDCTX
399  
400 =head2 XPK_TERMEXPR_SCALARCTX, XPK_TERMEXPR_SCALARCTX_OPT
401  
402 Variants of C<XPK_TERMEXPR> which puts the expression in void or scalar context.
403  
404 =head2 XPK_LISTEXPR, XPK_LISTEXPR_OPT
405  
406 I<atomic, emits op.>
407  
408 XPK_LISTEXPR
409  
410 A list expression is expected, parsed using C<parse_listexpr()>, and passed as
411 an optree in the I<op> field.
412  
413 =head2 XPK_LISTEXPR_LISTCTX, XPK_LISTEXPR_LISTCTX_OPT
414  
415 Variant of C<XPK_LISTEXPR> which puts the expression in list context.
416  
417 =head2 XPK_PREFIXED_TERMEXPR_ENTERLEAVE, XPK_PREFIXED_LISTEXPR_ENTERLEAVE
418  
419 XPK_PREFIXED_TERMEXPR_ENTERLEAVE(pieces ...)
420 XPK_PREFIXED_LISTEXPR_ENTERLEAVE(pieces ...)
421  
422 Variants of C<XPK_TERMEXPR> or C<XPK_LISTEXPR> which expect a sequence pieces
423 first before it parses a term expression, similar to how
424 C<XPK_PREFIXED_BLOCK_ENTERLEAVE> works. The entire operation is wrapped in an
425 C<ENTER>/C<LEAVE> pair.
426  
427 These are intended just for use of C<XPK_SETUP> pieces as prefixes. Any other
428 pieces which actually parse real input are likely to cause overly-complex,
429 subtle, or outright ambiguous grammars, and should be avoided.
430  
431 =head2 XPK_IDENT, XPK_IDENT_OPT
432  
433 I<atomic, can probe, emits sv.>
434  
435 A bareword identifier name is expected, and passed as an SV containing a PV
436 in the I<sv> field. An identifier is not permitted to contain a double colon
437 (C<::>).
438  
439 =head2 XPK_PACKAGENAME, XPK_PACKAGENAME_OPT
440  
441 I<atomic, can probe, emits sv.>
442  
443 A bareword package name is expected, and passed as an SV containing a PV in
444 the I<sv> field. A package name is similar to an identifier, except it permits
445 double colons in the middle.
446  
447 =head2 XPK_LEXVARNAME
448  
449 I<atomic, emits sv.>
450  
451 XPK_LEXVARNAME(kind)
452  
453 A lexical variable name is expected, and passed as an SV containing a PV in
454 the I<sv> field. The C<kind> argument specifies what kinds of variable are
455 permitted, and should be a bitmask of one or more bits from
456 C<XPK_LEXVAR_SCALAR>, C<XPK_LEXVAR_ARRAY> and C<XPK_LEXVAR_HASH>. A convenient
457 shortcut C<XPK_LEXVAR_ANY> permits all three.
458  
459 =head2 XPK_ATTRIBUTES
460  
461 I<atomic, emits i followed by more args.>
462  
463 A list of C<:>-prefixed attributes is expected, in the same format as sub or
464 variable attributes. An optional leading C<:> indicates the presence of
465 attributes, then one or more of them are parsed. Attributes may be optionally
466 separated by additional C<:>s, but this is not required.
467  
468 Each attribute is expected to be an identifier name, followed by an optional
469 value wrapped in parentheses. Whitespace is B<NOT> permitted between the name
470 and value, as per standard Perl parsing rules.
471  
472 =for highlighter language=perl
473  
474 :attrname
475 :attrname(value)
476  
477 =for highlighter language=c
478  
479 The I<i> field indicates how many attributes were found. That number of
480 additional arguments are then passed, each containing two SVs in the
481 I<attr.name> and I<attr.value> fields. This number may be zero.
482  
483 It is not an error for there to be no attributes present, or for the optional
484 colon to be missing. In this case I<i> will be set to zero.
485  
486 =head2 XPK_VSTRING, XPK_VSTRING_OPT
487  
488 I<atomic, can probe, emits sv.>
489  
490 A version string is expected, of the form C<v1.234> including the leading C<v>
491 character. It is passed as a L<version> SV object in the I<sv> field.
492  
493 =head2 XPK_LEXVAR
494  
495 I<atomic, emits padix.>
496  
497 XPK_LEXVAR(kind)
498  
499 A lexical variable name is expected and looked up from the current pad. The
500 resulting pad index is passed in the I<padix> field. No error happens if the
501 variable is not found; the value C<NOT_IN_PAD> is passed instead.
502  
503 The C<kind> argument specifies what kinds of variable are permitted, as per
504 C<XPK_LEXVARNAME>.
505  
506 =head2 XPK_LEXVAR_MY
507  
508 I<atomic, emits padix.>
509  
510 XPK_LEXVAR_MY(kind)
511  
512 A lexical variable name is expected, added to the current pad as if specified
513 in a C<my> expression, and passed as the pad index in the I<padix> field.
514  
515 The C<kind> argument specifies what kinds of variable are permitted, as per
516 C<XPK_LEXVARNAME>.
517  
518 =head2 XPK_COMMA, XPK_COLON, XPK_EQUALS
519  
520 I<atomic, can probe, emits nothing.>
521  
522 A literal character (C<,>, C<:> or C<=>) is expected. No argument value is passed.
523  
524 =head2 XPK_AUTOSEMI
525  
526 I<atomic, emits nothing.>
527  
528 A literal semicolon (C<;>) as a statement terminator is optionally expected.
529 If the next token is a closing brace to indicate the end of a block, then a
530 semicolon is not required. If anything else is encountered an error will be
531 raised.
532  
533 This piece type is the same as specifying the C<XPK_FLAG_AUTOSEMI>. It is
534 useful to put at the end of a sequence that forms part of a choice of syntax,
535 where some forms indicate a statement ending in a semicolon, whereas others
536 may end in a full block that does not need one.
537  
538 =head2 XPK_INFIX_*
539  
540 I<atomic, can probe, emits infix.>
541  
542 An infix operator as recognised by L<XS::Parse::Infix>. The returned pointer
543 points to a structure allocated by C<XS::Parse::Infix> describing the
544 operator.
545  
546 Various versions of the macro are provided, each using a different selection
547 filter to choose certain available infix operators:
548  
549 XPK_INFIX_RELATION // any relational operator
550 XPK_INFIX_EQUALITY // an equality operator like `==` or `eq`
551 XPK_INFIX_MATCH_NOSMART // any sort of "match"-like operator, except smartmatch
552 XPK_INFIX_MATCH_SMART // XPK_INFIX_MATCH_NOSMART plus smartmatch
553  
554 =head2 XPK_LITERAL
555  
556 I<atomic, can probe, emits nothing.>
557  
558 XPK_LITERAL("literal")
559  
560 A literal string match is expected. No argument value is passed.
561  
562 This form should generally be avoided if at all possible, because it is very
563 easy to abuse to make syntaxes which confuse humans and code tools alike.
564 Generally it is best reserved just for the first component of a
565 C<XPK_OPTIONAL> or C<XPK_REPEATED> sequence, to provide a "secondary keyword"
566 that such a repeated item can look out for.
567  
568 =head2 XPK_KEYWORD
569  
570 I<atomic, can probe, emits nothing.>
571  
572 XPK_KEYWORD("keyword")
573  
574 A literal string match is expected. No argument value is passed.
575  
576 This is similar to C<XPK_LITERAL> except that it additionally checks that the
577 following character is not an identifier character. This ensures that the
578 expected keyword-like behaviour is preserved. For example, given the input
579 C<"keyword">, the piece C<XPK_LITERAL("key")> would match it, whereas
580 C<XPK_KEYWORD("key")> would not because of the subsequent C<"w"> character.
581  
582 =head2 XPK_INTRO_MY
583  
584 I<atomic, emits nothing.>
585  
586 Calls the core perl C<intro_my()> function immediately. No input is consumed
587 and no output value is generated. This is often useful after C<XPK_LEXVAR_MY>.
588  
589 =head2 XPK_WARNING
590  
591 I<atomic, emits nothing.>
592  
593 XPK_WARNING("message here")
594  
595 Emits a warning by calling the core perl C<warn()> function on the given
596 string literal. This is equivalent to simply calling C<warn()> from the build
597 function, except that it is emitted immediately at parse time, so line
598 numbering will be more accurate. Also, by placing it as part of an optional or
599 choice sequence, the warning will only be emitted conditionally if that part
600 of the grammar structure is encountered.
601  
602 =head2 XPK_WARNING_...
603  
604 Several variants of C<XPK_WARNING> exist that are conditional on particular
605 warning categories being enabled. These are ones that are likely to be useful
606 at parse time:
607  
608 XPK_WARNING_AMBIGUOUS
609 XPK_WARNING_DEPRECATED
610 XPK_WARNING_EXPERIMENTAL
611 XPK_WARNING_PRECEDENCE
612 XPK_WARNING_SYNTAX
613  
614 =head2 XPK_SEQUENCE
615  
616 I<structural, might support probe, emits nothing.>
617  
618 XPK_SEQUENCE(pieces ...)
619  
620 A structural type which contains a number of pieces. This is normally
621 equivalent to simply placing the pieces in sequence inside their own
622 container, but it is useful inside C<XPK_CHOICE> or C<XPK_TAGGEDCHOICE>.
623  
624 An C<XPK_SEQUENCE> supports probe if its first contained piece does; i.e.
625 is transparent to probing.
626  
627 =head2 XPK_OPTIONAL
628  
629 I<structural, emits i.>
630  
631 XPK_OPTIONAL(pieces ...)
632  
633 A structural type which may expects to find its contained pieces, or is happy
634 not to. This will pass an argument whose I<i> field contains either 1 or 0,
635 depending whether the contents were found. The first piece type within must
636 support probe.
637  
638 =head2 XPK_REPEATED
639  
640 I<structural, emits i.>
641  
642 XPK_REPEATED(pieces ...)
643  
644 A structural type which expects to find zero or more repeats of its contained
645 pieces. This will pass an argument whose I<i> field contains the count of the
646 number of repeats it found. The first piece type within must support probe.
647  
648 =head2 XPK_CHOICE
649  
650 I<structural, can probe, emits i.>
651  
652 XPK_CHOICE(options ...)
653  
654 A structural type which expects to find one of a number of alternative
655 options. An ordered list of types is provided, all of which must support
656 probe. This will pass an argument whose I<i> field gives the index of the
657 first choice that was accepted. The first option takes the value 0.
658  
659 As each of the options is interpreted as an alternative, not a sequence, you
660 should use C<XPK_SEQUENCE> if a sequence of multiple items should be
661 considered as a single alternative.
662  
663 It is not an error if no choice matches. At that point, the I<i> field will be
664 set to -1.
665  
666 If you require a failure message in this case, set the final choice to be of
667 type C<XPK_FAILURE>. This will cause an error message to be printed instead.
668  
669 XPK_FAILURE("message string")
670  
671 =head2 XPK_TAGGEDCHOICE
672  
673 I<structural, can probe, emits i.>
674  
675 XPK_TAGGEDCHOICE(choice, tag, ...)
676  
677 A structural type similar to C<XPK_CHOICE>, except that each choice type is
678 followed by an element of type C<XPK_TAG> which gives an integer. It is that
679 integer value, rather than the positional index of the choice within the list,
680 which is passed in the I<i> field.
681  
682 XPK_TAG(value)
683  
684 As each of the options is interpreted as an alternative, not a sequence, you
685 should use C<XPK_SEQUENCE> if a sequence of multiple items should be
686 considered as a single alternative.
687  
688 =head2 XPK_COMMALIST
689  
690 I<structural, might support probe, emits i.>
691  
692 XPK_COMMALIST(pieces ...)
693  
694 A structural type which expects to find one or more repeats of its contained
695 pieces, separated by literal comma (C<,>) characters. This is somewhat similar
696 to C<XPK_REPEATED>, except that it needs at least one copy, needs commas
697 between its items, but does not require that the first contained piece support
698 probe (the comma itself is sufficient to indicate a repeat).
699  
700 An C<XPK_COMMALIST> supports probe if its first contained piece does; i.e.
701 is transparent to probing.
702  
703 =head2 XPK_PARENS
704  
705 I<structural, can probe, emits nothing.>
706  
707 XPK_PARENS(pieces ...)
708  
709 A structural type which expects to find a sequence of pieces, all contained in
710 parentheses as C<( ... )>. This will pass no extra arguments.
711  
712 =head2 XPK_ARGS
713  
714 I<structural, emits nothing.>
715  
716 XPK_ARGS(pieces ...)
717  
718 A structural type similar to C<XPK_PARENS>, except that the parentheses
719 themselves are optional; much like Perl's parsing of calls to known functions.
720  
721 If parentheses are encountered in the input, they will be consumed by this
722 piece and it will behave identically to C<XPK_PARENS>. If there is no open
723 parenthesis, this piece will behave like C<XPK_SEQUENCE> and consume all the
724 pieces inside it, without expecting a closing parenthesis.
725  
726 =head2 XPK_BRACKETS
727  
728 I<structural, can probe, emits nothing.>
729  
730 XPK_BRACKETS(pieces ...)
731  
732 A structural type which expects to find a sequence of pieces, all contained in
733 square brackets as C<[ ... ]>. This will pass no extra arguments.
734  
735 =head2 XPK_BRACES
736  
737 I<structural, can probe, emits nothing.>
738  
739 XPK_BRACES(pieces ...)
740  
741 A structural type which expects to find a sequence of pieces, all contained in
742 braces as C<{ ... }>. This will pass no extra arguments.
743  
744 Note that this is not necessary to use with C<XPK_BLOCK> or C<XPK_ANONSUB>;
745 those will already consume a set of braces. This is intended for special
746 constrained syntax that should not just accept an arbitrary block.
747  
748 =head2 XPK_CHEVRONS
749  
750 I<structural, can probe, emits nothing.>
751  
752 XPK_CHEVRONS(pieces ...)
753  
754 A structural type which expects to find a sequence of pieces, all contained in
755 angle brackets as C<< < ... > >>. This will pass no extra arguments.
756  
757 Remember that expressions like C<< a > b >> are valid term expressions, so the
758 contents of this scope shouldn't allow arbitrary expressions or the closing
759 bracket will be ambiguous.
760  
761 =head2 XPK_PARENS_OPT, XPK_BRACKETS_OPT, XPK_BRACES_OPT, XPK_CHEVRONS_OPT
762  
763 I<structural, can probe, emits i.>
764  
765 XPK_PARENS_OPT(pieces ...)
766 XPK_BRACKETS_OPT(pieces ...)
767 XPK_BRACES_OPT(pieces ...)
768 XPK_CHEVERONS_OPT(pieces ...)
769  
770 Each of the four contained structure macros above has an optional variant,
771 whose name is suffixed by C<_OPT>. These pass an argument whose I<i> field is
772 either true or false, indicating whether the scope was found, followed by the
773 values from the scope itself.
774  
775 This is a convenient shortcut to nesting the scope within a C<XPK_OPTIONAL>
776 macro.
777  
778 =head2 XPK_..._pieces
779  
780 XPK_SEQUENCE_pieces(ptr)
781 XPK_OPTIONAL_pieces(ptr)
782 ...
783  
784 For each of the C<XPK_...> macros that takes a variable-length list of pieces,
785 there is a variant whose name ends with C<..._pieces>, taking a single pointer
786 argument directly. This must point at a C<const XSParseKeywordPieceType []>
787 array whose final element is the zero element.
788  
789 Normally hand-written C code of a fixed grammar would be unlikely to use these
790 forms, but they may be useful in dynamically-generated cases.
791  
792 =cut
793  
794 =head1 AUTHOR
795  
796 Paul Evans <leonerd@leonerd.org.uk>
797  
798 =cut
799  
800 24 0x55AA;
« t/infix.xs ↑ Summary hax/make_argcheck_aux.c.inc »