| 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, 2022-2024 -- leonerd@leonerd.org.uk | ||||||||||||||||||||
| 5 | |||||||||||||||||||||
| 6 | package Syntax::Operator::Elem 0.11; | ||||||||||||||||||||
| 7 | |||||||||||||||||||||
| 8 | 3 | ▶ | use v5.20; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 9 | 3 | ▶ | use warnings; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 10 | |||||||||||||||||||||
| 11 | 3 | ▶ | use Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 12 | |||||||||||||||||||||
| 13 | 3 | ▶ | use meta 0.003_002; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 14 | 3 | ▶ | no warnings 'meta::experimental'; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 15 | |||||||||||||||||||||
| 16 | =encoding UTF-8 | ||||||||||||||||||||
| 17 | |||||||||||||||||||||
| 18 | =head1 NAME | ||||||||||||||||||||
| 19 | |||||||||||||||||||||
| 20 | C<Syntax::Operator::Elem> - element-of-list operators | ||||||||||||||||||||
| 21 | |||||||||||||||||||||
| 22 | =head1 SYNOPSIS | ||||||||||||||||||||
| 23 | |||||||||||||||||||||
| 24 | =for highlighter language=perl | ||||||||||||||||||||
| 25 | |||||||||||||||||||||
| 26 | On Perl v5.38 or later: | ||||||||||||||||||||
| 27 | |||||||||||||||||||||
| 28 | use Syntax::Operator::Elem; | ||||||||||||||||||||
| 29 | |||||||||||||||||||||
| 30 | if($x elem @some_strings) { | ||||||||||||||||||||
| 31 | say "x is one of the given strings"; | ||||||||||||||||||||
| 32 | } | ||||||||||||||||||||
| 33 | |||||||||||||||||||||
| 34 | Or on Perl v5.14 or later: | ||||||||||||||||||||
| 35 | |||||||||||||||||||||
| 36 | use v5.14; | ||||||||||||||||||||
| 37 | use Syntax::Operator::Elem qw( elem_str ); | ||||||||||||||||||||
| 38 | |||||||||||||||||||||
| 39 | if(elem_str $x, @some_strings) { | ||||||||||||||||||||
| 40 | say "x is one of the given strings"; | ||||||||||||||||||||
| 41 | } | ||||||||||||||||||||
| 42 | |||||||||||||||||||||
| 43 | =head1 DESCRIPTION | ||||||||||||||||||||
| 44 | |||||||||||||||||||||
| 45 | This module provides infix operators that implement element-of-list tests for | ||||||||||||||||||||
| 46 | strings and numbers. | ||||||||||||||||||||
| 47 | |||||||||||||||||||||
| 48 | Support for custom infix operators was added in the Perl 5.37.x development | ||||||||||||||||||||
| 49 | cycle and is available from development release v5.37.7 onwards, and therefore | ||||||||||||||||||||
| 50 | in Perl v5.38 onwards. The documentation of L<XS::Parse::Infix> | ||||||||||||||||||||
| 51 | describes the situation in more detail. | ||||||||||||||||||||
| 52 | |||||||||||||||||||||
| 53 | While Perl versions before this do not support custom infix operators, they | ||||||||||||||||||||
| 54 | can still be used via C<XS::Parse::Infix> and hence L<XS::Parse::Keyword>. | ||||||||||||||||||||
| 55 | Custom keywords which attempt to parse operator syntax may be able to use | ||||||||||||||||||||
| 56 | these. | ||||||||||||||||||||
| 57 | |||||||||||||||||||||
| 58 | Additionally, earlier versions of perl can still use the function-like | ||||||||||||||||||||
| 59 | wrapper versions of these operators. Even though the syntax appears like a | ||||||||||||||||||||
| 60 | regular function call, the code is compiled internally into the same more | ||||||||||||||||||||
| 61 | efficient operator internally, so will run without the function-call overhead | ||||||||||||||||||||
| 62 | of a regular function. | ||||||||||||||||||||
| 63 | |||||||||||||||||||||
| 64 | =cut | ||||||||||||||||||||
| 65 | |||||||||||||||||||||
| 66 | sub import | ||||||||||||||||||||
| 67 | 3 | ▶ | { | ||||||||||||||||||
|
Subroutine
import: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 68 | 3 | my $pkg = shift; | |||||||||||||||||||
| 69 | 3 | my $caller = caller; | |||||||||||||||||||
| 70 | |||||||||||||||||||||
| 71 | 3 | $pkg->import_into( $caller, @_ ); | |||||||||||||||||||
| 72 | } | ||||||||||||||||||||
| 73 | |||||||||||||||||||||
| 74 | sub unimport | ||||||||||||||||||||
| 75 | 1 | ▶ | { | ||||||||||||||||||
|
Subroutine
unimport: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 76 | 1 | my $pkg = shift; | |||||||||||||||||||
| 77 | 1 | my $caller = caller; | |||||||||||||||||||
| 78 | |||||||||||||||||||||
| 79 | 1 | $pkg->unimport_into( $caller, @_ ); | |||||||||||||||||||
| 80 | } | ||||||||||||||||||||
| 81 | |||||||||||||||||||||
| 82 | 3 | ▶ | sub import_into { shift->apply( 1, @_ ) } | ||||||||||||||||||
|
Subroutine
import_into: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||
| 83 | 1 | ▶ | sub unimport_into { shift->apply( 0, @_ ) } | ||||||||||||||||||
|
Subroutine
unimport_into: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||
| 84 | |||||||||||||||||||||
| 85 | sub apply | ||||||||||||||||||||
| 86 | 4 | ▶ | { | ||||||||||||||||||
|
Subroutine
apply: called CC=7 SCAR=19.7
Pod
undocumented
| |||||||||||||||||||||
| 87 | 4 | my $pkg = shift; | |||||||||||||||||||
| 88 | 4 | my ( $on, $caller, @syms ) = @_; | |||||||||||||||||||
| 89 | |||||||||||||||||||||
| 90 | 4 | require Syntax::Operator::In; # no import | |||||||||||||||||||
| 91 | |||||||||||||||||||||
| 92 | 4 | ▶ | @syms or @syms = qw( elem ∈ ); | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 93 | |||||||||||||||||||||
| 94 | 4 | $pkg->XS::Parse::Infix::apply_infix( $on, \@syms, qw( elem ∈ ) ); | |||||||||||||||||||
| 95 | |||||||||||||||||||||
| 96 | 4 | my %syms = map { $_ => 1 } @syms; | |||||||||||||||||||
| 97 | 4 | my $callerpkg; | |||||||||||||||||||
| 98 | |||||||||||||||||||||
| 99 | 4 | foreach (qw( elem_str elem_num )) { | |||||||||||||||||||
| 100 | 8 | ▶ | next unless delete $syms{$_}; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 101 | |||||||||||||||||||||
| 102 | 2 | ▶ | $callerpkg //= meta::package->get( $caller ); | ||||||||||||||||||
|
Condition66%2/3
$callerpkg //= "meta::package"->get($caller)
MC/DC0%0/2
$callerpkg //= "meta::package"->get($caller)
$callerpkg
"meta::package"->get($caller)
Truth table66%2/3
A //= B
A= $callerpkgB= "meta::package"->get($caller)
| |||||||||||||||||||||
| 103 | |||||||||||||||||||||
| 104 | 2 | ▶ | $on ? $callerpkg->add_symbol( '&'.$_ => \&{$_} ) | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 105 | : $callerpkg->remove_symbol( '&'.$_ ); | ||||||||||||||||||||
| 106 | } | ||||||||||||||||||||
| 107 | |||||||||||||||||||||
| 108 | 0 | ▶ | croak "Unrecognised import symbols @{[ keys %syms ]}" if keys %syms; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 109 | } | ||||||||||||||||||||
| 110 | |||||||||||||||||||||
| 111 | =head1 OPERATORS | ||||||||||||||||||||
| 112 | |||||||||||||||||||||
| 113 | =head2 elem | ||||||||||||||||||||
| 114 | |||||||||||||||||||||
| 115 | my $present = $lhs elem @rhs; | ||||||||||||||||||||
| 116 | |||||||||||||||||||||
| 117 | Yields true if the string on the lefthand side is equal to any of the strings | ||||||||||||||||||||
| 118 | in the list on the right. | ||||||||||||||||||||
| 119 | |||||||||||||||||||||
| 120 | Note that it is specifically B<not> guaranteed that this test will be | ||||||||||||||||||||
| 121 | performed in any particular order. Nor is it guaranteed that any C<eq> | ||||||||||||||||||||
| 122 | operator overloading present on any of the elements is respected. These | ||||||||||||||||||||
| 123 | conditions may allow an implementation at least partially based on a hash, | ||||||||||||||||||||
| 124 | balanced binary tree, or other techniques. | ||||||||||||||||||||
| 125 | |||||||||||||||||||||
| 126 | =head2 ∈ | ||||||||||||||||||||
| 127 | |||||||||||||||||||||
| 128 | my $present = $lhs ∈ @rhs; | ||||||||||||||||||||
| 129 | |||||||||||||||||||||
| 130 | Yields true if the number on the lefthand side is equal to any of the numbers | ||||||||||||||||||||
| 131 | in the list on the right. | ||||||||||||||||||||
| 132 | |||||||||||||||||||||
| 133 | Note that it is specifically B<not> guaranteed that this test will be | ||||||||||||||||||||
| 134 | performed in any particular order. Nor is it guaranteed that any C<==> | ||||||||||||||||||||
| 135 | operator overloading present on any of the elements is respected. These | ||||||||||||||||||||
| 136 | conditions may allow an implementation at least partially based on a hash, | ||||||||||||||||||||
| 137 | balanced binary tree, or other techniques. | ||||||||||||||||||||
| 138 | |||||||||||||||||||||
| 139 | =cut | ||||||||||||||||||||
| 140 | |||||||||||||||||||||
| 141 | =head1 FUNCTIONS | ||||||||||||||||||||
| 142 | |||||||||||||||||||||
| 143 | As a convenience, the following functions may be imported which implement the | ||||||||||||||||||||
| 144 | same behaviour as the infix operators, though are accessed via regular | ||||||||||||||||||||
| 145 | function call syntax. | ||||||||||||||||||||
| 146 | |||||||||||||||||||||
| 147 | =head2 elem_str | ||||||||||||||||||||
| 148 | |||||||||||||||||||||
| 149 | my $present = elem_str( $lhs, @rhs ); | ||||||||||||||||||||
| 150 | |||||||||||||||||||||
| 151 | A function version of the L</elem> stringy operator. | ||||||||||||||||||||
| 152 | |||||||||||||||||||||
| 153 | =head2 elem_num | ||||||||||||||||||||
| 154 | |||||||||||||||||||||
| 155 | my $present = elem_num( $lhs, @rhs ); | ||||||||||||||||||||
| 156 | |||||||||||||||||||||
| 157 | A function version of the L</∈> numerical operator. | ||||||||||||||||||||
| 158 | |||||||||||||||||||||
| 159 | =cut | ||||||||||||||||||||
| 160 | |||||||||||||||||||||
| 161 | =head1 AUTHOR | ||||||||||||||||||||
| 162 | |||||||||||||||||||||
| 163 | Paul Evans <leonerd@leonerd.org.uk> | ||||||||||||||||||||
| 164 | |||||||||||||||||||||
| 165 | =cut | ||||||||||||||||||||
| 166 | |||||||||||||||||||||
| 167 | 3 | 0x55AA; | |||||||||||||||||||