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