| 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, 2023-2024 -- leonerd@leonerd.org.uk | ||
| 5 | |||
| 6 | package XS::Parse::Keyword::FromPerl 0.10; | ||
| 7 | |||
| 8 | 10 | ▶ | use v5.26; # XS code needs op_class() and the OPclass_* constants |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 10 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | 10 | ▶ | use meta 0.003_002; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 12 | 10 | ▶ | no warnings 'meta::experimental'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 13 | |||
| 14 | 10 | require XSLoader; | |
| 15 | 10 | XSLoader::load( __PACKAGE__, our $VERSION ); | |
| 16 | |||
| 17 | =head1 NAME | ||
| 18 | |||
| 19 | C<XS::Parse::Keyword::FromPerl> - drive C<XS::Parse::Keyword> directly from Perl | ||
| 20 | |||
| 21 | =head1 DESCRIPTION | ||
| 22 | |||
| 23 | This module provides a Perl-visible API wrapping (some of) the functionality | ||
| 24 | provided by L<XS::Parse::Keyword>, allowing extension keywords to be added to | ||
| 25 | the Perl language by writing code in Perl itself. | ||
| 26 | |||
| 27 | It provides a thin wrapping layer over the XS functions provided by XPK | ||
| 28 | itself. No real attempt is made here to provide further abstractions on top of | ||
| 29 | the API already provided by Perl and XPK, so users will have to be familiar | ||
| 30 | with the overall concepts there as well. | ||
| 31 | |||
| 32 | This module is currently experimental, on top of the already-experimental | ||
| 33 | nature of C<XS::Parse::Keyword> itself. | ||
| 34 | |||
| 35 | =cut | ||
| 36 | |||
| 37 | 10 | ▶ | use Exporter 'import'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 38 | 10 | push our @EXPORT_OK, qw( | |
| 39 | register_xs_parse_keyword | ||
| 40 | ); | ||
| 41 | |||
| 42 | # Most of the optree stuff is imported from Optree::Generate | ||
| 43 | 10 | require Optree::Generate; | |
| 44 | 10 | foreach my $sym (qw( | |
| 45 | opcode | ||
| 46 | op_contextualize | ||
| 47 | op_scope | ||
| 48 | newOP | ||
| 49 | newASSIGNOP | ||
| 50 | newBINOP | ||
| 51 | newCONDOP | ||
| 52 | newFOROP | ||
| 53 | newGVOP | ||
| 54 | newLISTOP | ||
| 55 | newLOGOP | ||
| 56 | newPADxVOP | ||
| 57 | newSVOP | ||
| 58 | newUNOP | ||
| 59 | G_VOID G_SCALAR G_LIST | ||
| 60 | OPf_WANT OPf_WANT_VOID OPf_WANT_SCALAR OPf_WANT_LIST | ||
| 61 | OPf_KIDS | ||
| 62 | OPf_PARENS | ||
| 63 | OPf_REF | ||
| 64 | OPf_MOD | ||
| 65 | OPf_STACKED | ||
| 66 | OPf_SPECIAL | ||
| 67 | )) { | ||
| 68 | 270 | Optree::Generate->import( $sym ); | |
| 69 | 270 | push @EXPORT_OK, $sym; | |
| 70 | } | ||
| 71 | |||
| 72 | =head1 OPTREE FUNCTIONS | ||
| 73 | |||
| 74 | The L<Optree::Generate> module contains a selection of helper functions to | ||
| 75 | allow Perl code to get access to various parts of the C-level API that would | ||
| 76 | be useful when building optrees for keywords. They used to be part of this | ||
| 77 | module, and so are currently re-exported for convenience, but a later version | ||
| 78 | of this module may start emitting warnings when they are used this way, and | ||
| 79 | eventually that may stop being provided at all. | ||
| 80 | |||
| 81 | Code needing these should import them directly: | ||
| 82 | |||
| 83 | use Optree::Generate qw( opcode newUNOP ... ); | ||
| 84 | |||
| 85 | =head1 XPK FUNCTIONS | ||
| 86 | |||
| 87 | =head2 register_xs_parse_keyword | ||
| 88 | |||
| 89 | register_xs_parse_keyword "name" => %args; | ||
| 90 | |||
| 91 | Registers a new extension keyword into the C<XS::Parse::Keyword> registry, | ||
| 92 | defined using the given name and arguments. | ||
| 93 | |||
| 94 | Takes the following named arguments: | ||
| 95 | |||
| 96 | =over 4 | ||
| 97 | |||
| 98 | =item flags => INT | ||
| 99 | |||
| 100 | Optional. If present, a bitmask of the following flag constants: | ||
| 101 | |||
| 102 | =over 4 | ||
| 103 | |||
| 104 | =item XPK_FLAG_EXPR | ||
| 105 | |||
| 106 | The build phase is expected to return C<KEYWORD_PLUGIN_EXPR>. | ||
| 107 | |||
| 108 | =item XPK_FLAG_STMT | ||
| 109 | |||
| 110 | The build phase is expected to return C<KEYWORD_PLUGIN_STMT>. | ||
| 111 | |||
| 112 | =item XPK_FLAG_AUTOSEMI | ||
| 113 | |||
| 114 | The syntax forms a complete statement, which should be followed by C<;>. | ||
| 115 | |||
| 116 | =back | ||
| 117 | |||
| 118 | =item pieces => ARRAY | ||
| 119 | |||
| 120 | Optional. If present, contains definitions for the syntax pieces to be parsed | ||
| 121 | for the syntax of this keyword. This must be composed of a list of calls to | ||
| 122 | the various C<XPK_...> piece-generating functions; documented below. | ||
| 123 | |||
| 124 | =item permit_hintkey => STRING | ||
| 125 | |||
| 126 | Optional. A string value to use for the "permit_hintkey". | ||
| 127 | |||
| 128 | =item permit => CODE | ||
| 129 | |||
| 130 | Optional. Callback function for the "permit" phase of keyword parsing. | ||
| 131 | |||
| 132 | $ok = $permit->( $hookdata ); | ||
| 133 | |||
| 134 | When invoked, it is passed a single arugment containing the (optional) | ||
| 135 | hookdata value, and its result should be a boolean scalar. | ||
| 136 | |||
| 137 | At least one of C<permit_hintkey> or C<permit> must be provided. | ||
| 138 | |||
| 139 | =item check => CODE | ||
| 140 | |||
| 141 | Optional. Callback function for the "check" phase of keyword parsing. | ||
| 142 | |||
| 143 | $check->( $hookdata ); | ||
| 144 | |||
| 145 | When invoked, it is passsed a single argument containing the (optional) | ||
| 146 | bookdata value. | ||
| 147 | |||
| 148 | =item build => CODE | ||
| 149 | |||
| 150 | Callback function for the "build" phase of keyword parsing. | ||
| 151 | |||
| 152 | $ret = $build->( \$out, \@args, $hookdata ); | ||
| 153 | |||
| 154 | When invoked, it is passed a SCALAR ref to store the output optree into, an | ||
| 155 | ARRAY reference containing the parsed arguments, and the (optional) hookdata | ||
| 156 | value. | ||
| 157 | |||
| 158 | The C<@args> array will contain object references referring to the individual | ||
| 159 | arguments parsed by the parser pieces. See L</Parser Arguments>. | ||
| 160 | |||
| 161 | The callback function should be build an optree as a C<B::OP> fragment, | ||
| 162 | possibly by calling the various C<new*OP()> functions defined above, and store | ||
| 163 | the eventual result into the scalar referred to by the first argument. | ||
| 164 | |||
| 165 | The callback should return one of C<KEYWORD_PLUGIN_EXPR> or | ||
| 166 | C<KEYWORD_PLUGIN_STMT> to indicate how its syntax should be interpreted by the | ||
| 167 | perl parser. | ||
| 168 | |||
| 169 | =item hookdata => SCALAR | ||
| 170 | |||
| 171 | Optional. If present, this scalar value is stored by the keyword definition | ||
| 172 | and passed into each of the phase callbacks when invoked. If not present then | ||
| 173 | C<undef> will be passed to the callbacks instead. | ||
| 174 | |||
| 175 | =back | ||
| 176 | |||
| 177 | =cut | ||
| 178 | |||
| 179 | =head2 Piece Type Functions | ||
| 180 | |||
| 181 | The following functions can be used to generate parsing pieces. | ||
| 182 | |||
| 183 | Many simple piece types have an variant which is optional; if the input source | ||
| 184 | does not look like the expected syntax for the piece type then it will emit | ||
| 185 | C<undef> rather than raise an error. These piece types have their names | ||
| 186 | suffixed by C<_OPT>. | ||
| 187 | |||
| 188 | =head3 XPK_BLOCK | ||
| 189 | |||
| 190 | A block of code, returned in the I<op> field. | ||
| 191 | |||
| 192 | =head3 XPK_ANONSUB | ||
| 193 | |||
| 194 | An anonymous subroutine, returned in the I<cv> field. | ||
| 195 | |||
| 196 | =head3 XPK_ARITHEXPR, XPK_ARITHEXPR_OPT | ||
| 197 | |||
| 198 | An arithemetic expression, returned in the I<op> field. | ||
| 199 | |||
| 200 | =head3 XPK_TERMEXPR, XPK_TERMEXPR_OPT | ||
| 201 | |||
| 202 | A term expression, returned in the I<op> field. | ||
| 203 | |||
| 204 | =head3 XPK_LISTEXPR, XPK_LISTEXPR_OPT | ||
| 205 | |||
| 206 | A list expression, returned in the I<op> field. | ||
| 207 | |||
| 208 | =head3 XPK_IDENT, XPK_IDENT_OPT | ||
| 209 | |||
| 210 | An identifier, returned as a string in the I<sv> field. | ||
| 211 | |||
| 212 | =head3 XPK_PACKAGENAME, XPK_PACKAGENAME_OPT | ||
| 213 | |||
| 214 | A package name, returned as a string in the I<sv> field. | ||
| 215 | |||
| 216 | =head3 XPK_LEXVARNAME | ||
| 217 | |||
| 218 | XPK_LEXVARNAME($kind) | ||
| 219 | |||
| 220 | A lexical variable name, returned as a string in the I<sv> field. | ||
| 221 | |||
| 222 | The C<$kind> must be a bitmask of C<XPK_LEXVAR_SCALAR>, C<XPK_LEXVAR_ARRAY>, | ||
| 223 | C<XPK_LEXVAR_HASH>; or C<XPK_LEXVAR_ANY> for convenience to set all three. | ||
| 224 | |||
| 225 | =head3 XPK_VSTRING, XPK_VSTRING_OPT | ||
| 226 | |||
| 227 | A version string, returned as a L<version> object instance in the I<sv> field. | ||
| 228 | |||
| 229 | =head3 XPK_LEXVAR | ||
| 230 | |||
| 231 | XPK_LEXVAR($kind) | ||
| 232 | |||
| 233 | A lexical variable that already exists in the pad, returned as a pad offset in | ||
| 234 | the I<padix> field. | ||
| 235 | |||
| 236 | C<$kind> is specified as in C<XPK_LEXVARNAME>. | ||
| 237 | |||
| 238 | =head3 XPK_LEXVAR_MY | ||
| 239 | |||
| 240 | XPK_LEXVAR_MY($kind) | ||
| 241 | |||
| 242 | A lexical variable, parsed as if it appeared in a C<my> expression. It will be | ||
| 243 | added to the pad and returned as a pad offset in the I<padix> field. | ||
| 244 | |||
| 245 | =head3 XPK_COMMA | ||
| 246 | |||
| 247 | =head3 XPK_COLON | ||
| 248 | |||
| 249 | =head3 XPK_EQUALS | ||
| 250 | |||
| 251 | A literal comma, colon or equals sign. These do not appear in the arguments | ||
| 252 | list. | ||
| 253 | |||
| 254 | =head3 XPK_LITERAL | ||
| 255 | |||
| 256 | XPK_LISTEXPR($string) | ||
| 257 | |||
| 258 | A literal string match. No value is returned. | ||
| 259 | |||
| 260 | This should be avoided if at all possible, in favour of the character matches | ||
| 261 | above, or C<XPK_KEYWORD>. | ||
| 262 | |||
| 263 | =head3 XPK_KEYWORD | ||
| 264 | |||
| 265 | XPK_KEYWORD($string) | ||
| 266 | |||
| 267 | A literal string match, which requires that the following text does not begin | ||
| 268 | with an identifier character (thus avoiding prefix-match problems). No value | ||
| 269 | is returned. | ||
| 270 | |||
| 271 | =head3 XPK_INTRO_MY | ||
| 272 | |||
| 273 | Calls the perl C<intro_my()> function immediately. No input is consumed and no | ||
| 274 | output value is generated. | ||
| 275 | |||
| 276 | =head3 XPK_WARNING | ||
| 277 | |||
| 278 | XPK_WARNING($message) | ||
| 279 | |||
| 280 | Emits a warning by callling the core perl C<warn()> function immediately. | ||
| 281 | |||
| 282 | =head3 XPK_WARNING_... | ||
| 283 | |||
| 284 | XPK_WARNING_AMBIGUOUS($message) | ||
| 285 | XPK_WARNING_DEPRECATED($message) | ||
| 286 | XPK_WARNING_EXPERIMENTAL($message) | ||
| 287 | XPK_WARNING_PRECEDENCE($message) | ||
| 288 | XPK_WARNING_SYNTAX($message) | ||
| 289 | |||
| 290 | Several variants of L</XPK_WARNING> that are conditional on various warning | ||
| 291 | categories being enabled. | ||
| 292 | |||
| 293 | =head3 XPK_SEQUENCE | ||
| 294 | |||
| 295 | XPK_SEQUENCE(@pieces) | ||
| 296 | |||
| 297 | A sub-sequence. Normally this is not necessary, as most of the | ||
| 298 | structure-forming functions already take a sequence of pieces. It is mostly | ||
| 299 | useful as as an option to the C<XPK_CHOICE> function. | ||
| 300 | |||
| 301 | Nothing extra is returned, beyond the values from the individual pieces. | ||
| 302 | |||
| 303 | =head3 XPK_OPTIONAL | ||
| 304 | |||
| 305 | XPK_OPTIONAL(@pieces) | ||
| 306 | |||
| 307 | An optional sequence of pieces that may or may not be present. Returns an | ||
| 308 | integer value in the I<i> field of 0 if the sequence was not found, or 1 | ||
| 309 | followed by its values if the sequence was found. | ||
| 310 | |||
| 311 | =head3 XPK_REPEATED | ||
| 312 | |||
| 313 | XPK_REPEATED(@pieces) | ||
| 314 | |||
| 315 | A repeating sequence of pieces. Returns an integer value in the I<i> field | ||
| 316 | indicating how many times the sequence repeated, followed by all the values | ||
| 317 | returned by each. | ||
| 318 | |||
| 319 | =head3 XPK_CHOICE | ||
| 320 | |||
| 321 | XPK_CHOICE(@pieces) | ||
| 322 | |||
| 323 | The pieces of this function are not interpreted as a sequence, but instead | ||
| 324 | as a list of possible choices. Returns an integer value in the I<i> field | ||
| 325 | indicating which choice was found, followed by all the values returned by | ||
| 326 | that sequence. | ||
| 327 | |||
| 328 | The first possible choice is numbered C<0>. If no choice matched, it returns | ||
| 329 | C<-1>. To cause an error instead, use L<XPK_FAILURE>. | ||
| 330 | |||
| 331 | =head3 XPK_FAILURE | ||
| 332 | |||
| 333 | XPK_FAILURE($message) | ||
| 334 | |||
| 335 | Attempting to parse this piece type will immediately cause a compile-time | ||
| 336 | failure with the given message. This can be used as the final option in | ||
| 337 | C<XPK_CHOICE> to ensure a valid match. | ||
| 338 | |||
| 339 | =head3 XPK_PARENS | ||
| 340 | |||
| 341 | XPK_PARENS(@pieces) | ||
| 342 | |||
| 343 | Expects to find a sequence of pieces, all surrounded by parentheses (round | ||
| 344 | brackets, C<( ... )>). | ||
| 345 | |||
| 346 | Nothing extra is returned, beyond the values from the individual contained | ||
| 347 | pieces. | ||
| 348 | |||
| 349 | =head3 XPK_ARGS | ||
| 350 | |||
| 351 | XPK_ARGS(@pieces) | ||
| 352 | |||
| 353 | A container similar to C<XPK_PARENS> except that the parentheses themselves | ||
| 354 | are optional, similar to perl's parsing of calls to known functions. | ||
| 355 | |||
| 356 | =head3 XPK_BRACKETS | ||
| 357 | |||
| 358 | XPK_BRACKETS(@pieces) | ||
| 359 | |||
| 360 | Expects to find a sequence of pieces, all surrounded by square brackets | ||
| 361 | (C<[ ... ]>). | ||
| 362 | |||
| 363 | Nothing extra is returned, beyond the values from the individual contained | ||
| 364 | pieces. | ||
| 365 | |||
| 366 | =head3 XPK_BRACES | ||
| 367 | |||
| 368 | XPK_BRACES(@pieces) | ||
| 369 | |||
| 370 | Expects to find a sequence of pieces, all surrounded by braces (C<{ ... }>). | ||
| 371 | |||
| 372 | Nothing extra is returned, beyond the values from the individual contained | ||
| 373 | pieces. | ||
| 374 | |||
| 375 | =head3 XPK_CHEVRONS | ||
| 376 | |||
| 377 | XPK_CHEVRONS(@pieces) | ||
| 378 | |||
| 379 | Expects to find a sequence of pieces, all surrounded by chevrons (angle | ||
| 380 | brackets, C<< < ... > >>). | ||
| 381 | |||
| 382 | Nothing extra is returned, beyond the values from the individual contained | ||
| 383 | pieces. | ||
| 384 | |||
| 385 | =cut | ||
| 386 | |||
| 387 | 10 | my $thispkg = meta::get_this_package(); | |
| 388 | |||
| 389 | # Simple pieces | ||
| 390 | 10 | foreach (qw( | |
| 391 | BLOCK ANONSUB ARITHEXPR TERMEXPR LISTEXPR IDENT IDENT_OPT | ||
| 392 | PACKAGENAME PACKAGENAME_OPT VSTRING VSTRING_OPT COMMA COLON EQUALS | ||
| 393 | )) { | ||
| 394 | 140 | my $name = "XPK_$_"; | |
| 395 | 140 | push @EXPORT_OK, $name; | |
| 396 | 12 | ▶ | $thispkg->add_symbol( "\&$name" => sub { |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 397 | 12 | bless [$name], "XS::Parse::Keyword::FromPerl::_Piece"; | |
| 398 | 140 | } ); | |
| 399 | } | ||
| 400 | # Single-SV parametric pieces | ||
| 401 | 10 | foreach (qw( | |
| 402 | LEXVARNAME LEXVAR LEXVAR_MY LITERAL KEYWORD FAILURE WARNING | ||
| 403 | )) { | ||
| 404 | 70 | my $name = "XPK_$_"; | |
| 405 | 70 | push @EXPORT_OK, $name; | |
| 406 | 4 | ▶ | $thispkg->add_symbol( "\&$name" => sub { |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 407 | 4 | bless [$name, $_[0]], "XS::Parse::Keyword::FromPerl::_Piece"; | |
| 408 | 70 | } ); | |
| 409 | } | ||
| 410 | # Structural multiple-value pieces | ||
| 411 | 10 | foreach (qw( | |
| 412 | SEQUENCE OPTIONAL REPEATED CHOICE | ||
| 413 | PARENS ARGS BRACKETS BRACES CHEVRONS | ||
| 414 | )) { | ||
| 415 | 90 | my $name = "XPK_$_"; | |
| 416 | 90 | push @EXPORT_OK, $name; | |
| 417 | 3 | ▶ | $thispkg->add_symbol( "\&$name" => sub { |
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||
| 418 | 3 | bless [$name, [@_]], "XS::Parse::Keyword::FromPerl::_Piece"; | |
| 419 | 90 | } ); | |
| 420 | } | ||
| 421 | |||
| 422 | # Back-compat wrappers for the old names | ||
| 423 | 10 | foreach (qw( PAREN ARG BRACKET BRACE CHEVRON )) { | |
| 424 | 50 | my $macroname = "XPK_${_}S"; | |
| 425 | 50 | my $funcname = "XPK_${_}SCOPE"; | |
| 426 | 50 | push @EXPORT_OK, $funcname; | |
| 427 | 0 | ▶ | $thispkg->add_symbol( "\&$funcname" => sub { |
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||
| 428 | 0 | warnings::warnif deprecated => "$funcname is now deprecated; use $macroname instead"; | |
| 429 | 0 | bless [$macroname, [@_]], "XS::Parse::Keyword::FromPerl::_Piece"; | |
| 430 | 50 | } ); | |
| 431 | } | ||
| 432 | |||
| 433 | =head2 Parser Arguments | ||
| 434 | |||
| 435 | Each of the values given in the C<@args> array for the "build" phase callback | ||
| 436 | are given as object references having the following methods | ||
| 437 | |||
| 438 | =head3 op | ||
| 439 | |||
| 440 | $op = $arg->op; | ||
| 441 | |||
| 442 | Returns an optree. | ||
| 443 | |||
| 444 | =head3 cv | ||
| 445 | |||
| 446 | $cv = $arg->cv; | ||
| 447 | |||
| 448 | Returns a CV wrapped in a CODE reference. | ||
| 449 | |||
| 450 | =head3 sv | ||
| 451 | |||
| 452 | $sv = $arg->sv; | ||
| 453 | |||
| 454 | Returns the SV itself, or C<undef> if the optional SV was absent. | ||
| 455 | |||
| 456 | =head3 has_sv | ||
| 457 | |||
| 458 | $ok = $arg->has_sv; | ||
| 459 | |||
| 460 | Returns true if the optional SV was present (even if it was C<undef>), or | ||
| 461 | false if it was absent. | ||
| 462 | |||
| 463 | =head3 i | ||
| 464 | |||
| 465 | $i = $arg->i; | ||
| 466 | |||
| 467 | Returns an integer. | ||
| 468 | |||
| 469 | =head3 padix | ||
| 470 | |||
| 471 | $padix = $arg->padix; | ||
| 472 | |||
| 473 | Returns a pad offset index as an integer. | ||
| 474 | |||
| 475 | =head3 line | ||
| 476 | |||
| 477 | $line = $arg->line; | ||
| 478 | |||
| 479 | Returns the line number of the source text on which the piece was started. | ||
| 480 | |||
| 481 | =cut | ||
| 482 | |||
| 483 | =head1 AUTHOR | ||
| 484 | |||
| 485 | Paul Evans <leonerd@leonerd.org.uk> | ||
| 486 | |||
| 487 | =cut | ||
| 488 | |||
| 489 | 10 | 0x55AA; | |