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	sub	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.07;
7
8	3	3	481471	use v5.26; # XS code needs op_class() and the OPclass_* constants
	3		27
9	3	3	27	use warnings;
	3		10
	3		167
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	20	use Exporter 'import';
	3		6
	3		208
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 => 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 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;