| 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
| |||||||||||
| 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
| |||||||||||
| 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; | |||||||||