blib/lib/Syntax/Operator/In.pm

filter: Statementstmt 100% 26 / 26 Branchbran 50.0% 2 / 4 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod 25.0% 1 / 4 totaltotal 88.3% 38 / 43 CC 3 SCAR 4.5
CC
3
Cov
93%
apply
3.1
elem_num
1.0
BEGIN
1.0
CRAP 1.6
« blib/lib/Syntax/Operator/Elem.pm ↑ Summary hax/BINOP_ANY.c.inc »
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-2024 -- leonerd@leonerd.org.uk
5  
6 package Syntax::Operator::In 0.11;
7  
8 7 ▶use v5.20;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 7 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 7 require XSLoader;
14 7 XSLoader::load( __PACKAGE__, our $VERSION );
15  
16 =head1 NAME
17  
18 C<Syntax::Operator::In> - infix element-of-list meta-operator
19  
20 =head1 SYNOPSIS
21  
22 =for highlighter language=perl
23  
24 On Perl v5.38 or later:
25  
26 use Syntax::Operator::In;
27  
28 if($x in:eq @some_strings) {
29 say "x is one of the given strings";
30 }
31  
32 =head1 DESCRIPTION
33  
34 This module provides an infix meta-operator that implements a element-of-list
35 test on either strings or numbers.
36  
37 Support for custom infix operators was added in the Perl 5.37.x development
38 cycle and is available from development release v5.37.7 onwards, and therefore
39 in Perl v5.38 onwards. The documentation of L<XS::Parse::Infix>
40 describes the situation in more detail.
41  
42 While Perl versions before this do not support custom infix operators, they
43 can still be used via C<XS::Parse::Infix> and hence L<XS::Parse::Keyword>.
44 Custom keywords which attempt to parse operator syntax may be able to use
45 these.
46  
47 For operators that already specialize on string or numerical equality, see
48 instead L<Syntax::Operator::Elem>.
49  
50 =cut
51  
52 sub import
53 2 ▶{
Subroutine import: called CC=1 SCAR=0.0
54 2 my $pkg = shift;
55 2 my $caller = caller;
56  
57 2 $pkg->import_into( $caller, @_ );
58 }
59  
60 sub unimport
61 1 ▶{
Subroutine unimport: called CC=1 SCAR=0.0
62 1 my $pkg = shift;
63 1 my $caller = caller;
64  
65 1 $pkg->unimport_into( $caller, @_ );
66 }
67  
68 2 ▶sub import_into { shift->apply( 1, @_ ) }
Subroutine import_into: called CC=1 SCAR=0.0
Pod undocumented
69 1 ▶sub unimport_into { shift->apply( 0, @_ ) }
Subroutine unimport_into: called CC=1 SCAR=0.0
Pod undocumented
70  
71 sub apply
72 3 ▶{
Subroutine apply: called CC=3 SCAR=11.3
Pod undocumented
73 3 my $pkg = shift;
74 3 my ( $on, $caller, @syms ) = @_;
75  
76 3 ▶ @syms or @syms = qw( in );
Branch: 1 branch
BranchTrueFalseTotal
@syms or @syms = "in" 0 3 3
77  
78 3 $pkg->XS::Parse::Infix::apply_infix( $on, \@syms, qw( in ) );
79  
80 3 ▶ croak "Unrecognised import symbols @syms" if @syms;
Branch: 1 branch
BranchTrueFalseTotal
if @syms 0 3 3
81 }
82  
83 =head1 OPERATORS
84  
85 =head2 in
86  
87 my $present = $lhs in:OP @rhs;
88  
89 my $present = $lhs in<OP> @rhs;
90  
91 Yields true if the value on the lefhand side is equal to any of the values in
92 the list on the right, according to some equality test operator C<OP>.
93  
94 This test operator must be either C<eq> for string match, or C<==> for number
95 match, or any other custom infix operator that is registered in the
96 C<XPI_CLS_EQUALITY> classification.
97  
98 There are currently two accepted forms of the syntax for this operator, using
99 either a prefix colon or a circumfix pair of angle-brackets. They are entirely
100 identical in semantics, differing only in the surface-level syntax to notate
101 them. This is because I'm still entirely undecided on which notation is better
102 in terms of readable neatness, flexibility, parsing ambiguity and so on. This
103 is somewhat of an experiment to see which will eventually win.
104  
105 =cut
106  
107 =head1 TODO
108  
109 =over 4
110  
111 =item *
112  
113 Improve runtime performance of compiletime-constant sets of strings, by
114 detecting when the RHS contains string constants and convert it into a hash
115 lookup.
116  
117 =item *
118  
119 Consider cross-module integration with L<Syntax::Keyword::Match>, permitting
120  
121 match($val : elem) {
122 case(@arr_of_strings) { ... }
123 }
124  
125 Or perhaps this would be too weird, and maybe C<match/case> should have an
126 "any-of" list/array matching ability itself. See also
127 L<https://rt.cpan.org/Ticket/Display.html?id=143482>.
128  
129 =back
130  
131 =head1 AUTHOR
132  
133 Paul Evans <leonerd@leonerd.org.uk>
134  
135 =cut
136  
137 7 0x55AA;
« blib/lib/Syntax/Operator/Elem.pm ↑ Summary hax/BINOP_ANY.c.inc »