File Coverage

blib/lib/XS/Parse/Infix/FromPerl.pm
Criterion Covered Total %
statement 8 8 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 11 11 100.0


line stmt bran cond sub pod time code
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.05;
7              
8 3     3   468469 use v5.26; # XS code needs op_class() and the OPclass_* constants
  3         31  
9 3     3   19 use warnings;
  3         6  
  3         157  
10              
11             require XSLoader;
12             XSLoader::load( __PACKAGE__, our $VERSION );
13              
14             =head1 NAME
15              
16             C - drive C 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, 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 itself.
31              
32             =cut
33              
34 3     3   15 use Exporter 'import';
  3         5  
  3         198  
35             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
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 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 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 or C must be provided.
77              
78             =item new_op
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 references, the parse data (though this
86             will always be C currently), and the optional hookdata value.
87              
88             Its result should be the overall optree fragment, again as a C
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 will be passed to the callbacks instead.
96              
97             =back
98              
99             =cut
100              
101             =head1 AUTHOR
102              
103             Paul Evans
104              
105             =cut
106              
107             0x55AA;