File Coverage

blib/lib/Syntax/Operator/Equ.pm
Criterion Covered Total %
statement 34 39 87.1
branch 7 8 87.5
condition n/a
subroutine 9 11 81.8
pod 2 3 66.6
total 52 61 85.2


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, 2021-2023 -- leonerd@leonerd.org.uk
5              
6             package Syntax::Operator::Equ 0.06;
7              
8 7     7   1184799 use v5.14;
  7         67  
9 7     7   39 use warnings;
  7         13  
  7         170  
10              
11 7     7   37 use Carp;
  7         56  
  7         1491  
12              
13             require XSLoader;
14             XSLoader::load( __PACKAGE__, our $VERSION );
15              
16             =head1 NAME
17              
18             C - equality operators that distinguish C
19              
20             =head1 SYNOPSIS
21              
22             On Perl v5.38 or later:
23              
24             use v5.38;
25             use Syntax::Operator::Equ;
26              
27             if($x equ $y) {
28             say "x and y are both undef, or both defined and equal strings";
29             }
30              
31             if($i === $j) {
32             say "i and j are both undef, or both defined and equal numbers";
33             }
34              
35             Or via L on Perl v5.14 or later:
36              
37             use v5.14;
38             use Syntax::Keyword::Match;
39             use Syntax::Operator::Equ;
40              
41             match($str : equ) {
42             case(undef) { say "The variable is not defined" }
43             case("") { say "The variable is defined but is empty" }
44             default { say "The string is non-empty" }
45             }
46              
47             =head1 DESCRIPTION
48              
49             This module provides infix operators that implement equality tests of strings
50             or numbers similar to perl's C and C<==> operators, except that they
51             consider C to be a distinct value, separate from the empty string or
52             the number zero.
53              
54             These operators do not warn when either or both operands are C. They
55             yield true if both operands are C, false if exactly one operand is, or
56             otherwise behave the same as the regular string or number equality tests if
57             both operands are defined.
58              
59             Support for custom infix operators was added in the Perl 5.37.x development
60             cycle and is available from development release v5.37.7 onwards, and therefore
61             in Perl v5.38 onwards. The documentation of L
62             describes the situation in more detail.
63              
64             While Perl versions before this do not support custom infix operators, they
65             can still be used via C and hence L.
66             Custom keywords which attempt to parse operator syntax may be able to use
67             these. One such module is L; see the SYNOPSIS example
68             given above.
69              
70             =cut
71              
72             sub import
73             {
74 6     6   272 my $class = shift;
75 6         13 my $caller = caller;
76              
77 6         22 $class->import_into( $caller, @_ );
78             }
79              
80             sub import_into
81             {
82 6     6 0 13 my $class = shift;
83 6         19 my ( $caller, @syms ) = @_;
84              
85 6 100       25 @syms or @syms = qw( equ );
86              
87 6         13 my %syms = map { $_ => 1 } @syms;
  8         45  
88 6 100       55 $^H{"Syntax::Operator::Equ/equ"}++ if delete $syms{equ};
89              
90 6         17 foreach (qw( is_strequ is_numequ )) {
91 7     7   54 no strict 'refs';
  7         57  
  7         1203  
92 12 100       35 *{"${caller}::$_"} = \&{$_} if delete $syms{$_};
  4         28  
  4         12  
93             }
94              
95 6 50       2299 croak "Unrecognised import symbols @{[ keys %syms ]}" if keys %syms;
  0            
96             }
97              
98             =head1 OPERATORS
99              
100             =head2 equ
101              
102             my $equal = $lhs equ $rhs;
103              
104             Yields true if both operands are C, or if both are defined and contain
105             equal string values. Yields false if given exactly one C, or two
106             unequal strings.
107              
108             =head2 ===
109              
110             my $equal = $lhs === $rhs;
111              
112             Yields true if both operands are C, or if both are defined and contain
113             equal numerical values. Yields false if given exactly one C, or two
114             unequal numbers.
115              
116             Note that while this operator will not cause warnings about uninitialized
117             values, it can still warn if given defined stringy values that are not valid
118             as numbers.
119              
120             =cut
121              
122             =head1 FUNCTIONS
123              
124             As a convenience, the following functions may be imported which implement the
125             same behaviour as the infix operators, though are accessed via regular
126             function call syntax.
127              
128             These wrapper functions are implemented using L, and thus
129             have an optimising call-checker attached to them. In most cases, code which
130             calls them should not in fact have the full runtime overhead of a function
131             call because the underlying test operator will get inlined into the calling
132             code at compiletime. In effect, code calling these functions should run with
133             the same performance as code using the infix operators directly.
134              
135             =head2 is_strequ
136              
137             my $equal = is_strequ( $lhs, $rhs );
138              
139             A function version of the L stringy operator.
140              
141             =head2 is_numequ
142              
143             my $equal = is_numequ( $lhs, $rgh );
144              
145             A function version of the L numerical operator.
146              
147             =cut
148              
149             =head1 SEE ALSO
150              
151             =over 4
152              
153             =item *
154              
155             L - string equality and regexp match operator
156              
157             =back
158              
159             =head1 AUTHOR
160              
161             Paul Evans
162              
163             =cut
164              
165             0x55AA;