| 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 -- leonerd@leonerd.org.uk | ||
| 5 | |||
| 6 | package XS::Parse::Infix::FromPerl 0.10; | ||
| 7 | |||
| 8 | 3 | ▶ | use v5.26; # XS code needs op_class() and the OPclass_* constants |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 9 | 3 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 10 | |||
| 11 | 3 | require XSLoader; | |
| 12 | 3 | XSLoader::load( __PACKAGE__, our $VERSION ); | |
| 13 | |||
| 14 | =head1 NAME | ||
| 15 | |||
| 16 | C<XS::Parse::Infix::FromPerl> - drive C<XS::Parse::Infix> directly from Perl | ||
| 17 | |||
| 18 | =head1 DESCRIPTION | ||
| 19 | |||
| 20 | This module provides a Perl-visible API wrapping (some of) the functionality | ||
| 21 | provided by L<XS::Parse::Infix>, allowing extension infix operators to be | ||
| 22 | added to the Perl language by writing code in Perl itself. | ||
| 23 | |||
| 24 | It provides a thin wrapping layer over the XS functions provided by XPI | ||
| 25 | itself. No real attempt is made here to provide further abstractions on top of | ||
| 26 | the API already provided by Perl and XPI, so users will have to be familiar | ||
| 27 | with the overall concepts there as well. | ||
| 28 | |||
| 29 | This module is currently experimental, on top of the already-experimental | ||
| 30 | nature of C<XS::Parse::Infix> itself. | ||
| 31 | |||
| 32 | =cut | ||
| 33 | |||
| 34 | 3 | ▶ | use Exporter 'import'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 35 | 3 | push our @EXPORT_OK, qw( | |
| 36 | register_xs_parse_infix | ||
| 37 | ); | ||
| 38 | |||
| 39 | =head1 FUNCTIONS | ||
| 40 | |||
| 41 | =head2 register_xs_parse_infix | ||
| 42 | |||
| 43 | register_xs_parse_infix "name" => %args; | ||
| 44 | |||
| 45 | Registers a new extension infix operator into the C<XS::Parse::Infix> | ||
| 46 | registry, defined using the given name and arguments. | ||
| 47 | |||
| 48 | Takes the following named arguments: | ||
| 49 | |||
| 50 | =over 4 | ||
| 51 | |||
| 52 | =item cls => INT | ||
| 53 | |||
| 54 | The classification for the operator, which is used both as a filter for the | ||
| 55 | various C<XS::Parse::Keyword> selection macros, and a hint to the Perl parser | ||
| 56 | on the precedence level given to the operator. This should be one of the | ||
| 57 | C<XPI_CLS_*> constants. | ||
| 58 | |||
| 59 | =item wrapper_func_name => STRING | ||
| 60 | |||
| 61 | Optional. A string value to use for the "wrapper_func_name". | ||
| 62 | |||
| 63 | =item permit_hintkey => STRING | ||
| 64 | |||
| 65 | Optional. A string value to use for the "permit_hintkey". | ||
| 66 | |||
| 67 | =item permit => CODE | ||
| 68 | |||
| 69 | Optional. Callback function for the "permit" phase of parsing. | ||
| 70 | |||
| 71 | $ok = $permit->( $hookdata ); | ||
| 72 | |||
| 73 | When invoked, it is passed a single arugment containing the (optional) | ||
| 74 | hookdata value, and its result should be a boolean scalar. | ||
| 75 | |||
| 76 | At least one of C<permit_hintkey> or C<permit> must be provided. | ||
| 77 | |||
| 78 | =item new_op => CODE | ||
| 79 | |||
| 80 | Callback function for the "new_op" phase of parsing. | ||
| 81 | |||
| 82 | $op = $new_op->( $flags, $lhs, $rhs, $parsedata, $hookdata ); | ||
| 83 | |||
| 84 | When invoked, it is passed a flags value, the left-hand and right-hand side | ||
| 85 | operand optree fragments as C<B::OP> references, the parse data (though this | ||
| 86 | will always be C<undef> currently), and the optional hookdata value. | ||
| 87 | |||
| 88 | Its result should be the overall optree fragment, again as a C<B::OP> | ||
| 89 | reference, to represent the entire invocation sequence for the operator. | ||
| 90 | |||
| 91 | =item hookdata => SCALAR | ||
| 92 | |||
| 93 | Optional. If present, this scalar value is stored by the operator definition | ||
| 94 | and passed into each of the phase callbacks when invoked. If not present then | ||
| 95 | C<undef> will be passed to the callbacks instead. | ||
| 96 | |||
| 97 | =back | ||
| 98 | |||
| 99 | =cut | ||
| 100 | |||
| 101 | =head1 AUTHOR | ||
| 102 | |||
| 103 | Paul Evans <leonerd@leonerd.org.uk> | ||
| 104 | |||
| 105 | =cut | ||
| 106 | |||
| 107 | 3 | 0x55AA; | |