File Coverage

blib/lib/Syntax/Operator/Is.pm

Criterion	Covered	Total	%
statement	15	17	88.2
branch	2	4	50.0
condition			n/a
subroutine	5	6	83.3
pod	0	1	0.0
total	22	28	78.5

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2024 -- [e-mail]

package Syntax::Operator::Is 0.02;

use v5.14;
use warnings;

use Carp;

require XSLoader;
XSLoader::load( __PACKAGE__, our $VERSION );

=head1 NAME

C - match operator using L constraints

=head1 SYNOPSIS

On Perl v5.38 or later:

   use v5.38;
   use Syntax::Operator::Is;

   use Data::Checks qw( Num Object );

   my $x = ...;

   if($x is Num) {
      say "x can be used as a number";
   }
   elsif($x is Object) {
      say "x can be used as an object";
   }

Or via L on Perl v5.14 or later:

   use v5.14;
   use Syntax::Operator::Is;
   use Syntax::Keyword::Match;

   use Data::Checks qw( Num Object );

   my $x = ...;

   match($x : is) {
      case(Num)    { say "x can be used as a number"; }
      case(Object) { say "x can be used as an object"; }
   }

=head1 DESCRIPTION

This module provides an infix operator that checks if a given value matches a
value constraint provided by L.

Support for custom infix operators was added in the Perl 5.37.x development
cycle and is available from development release v5.37.7 onwards, and therefore
in Perl v5.38 onwards. The documentation of L
describes the situation in more detail.

While Perl versions before this do not support custom infix operators, they
can still be used via C and hence L.
Custom keywords which attempt to parse operator syntax may be able to use
these. One such module is L; see the SYNOPSIS example
given above.

=head2 Operator Name vs C / C

This module provides a named operator called C. The same name is used by
both L and L as a unit test assertion function. Since
each has to be imported by request, this does not cause issues for code that
does not try to use both of them at once. Most real use-cases will not be unit
test scripts, and most unit test scripts will not need to use this operator.

In situations where you need to use this C operator and one of the testing
modules at the same time (for example, during a unit test of some
check-related code), note that because of the way infix operator plugins work,
the named operator will always take precedence and thus you will need to call
the C testing function by its fully-qualified name:

   use Test2::V0;
   use Syntax::Operator::Is;

   Test2::V0::is( 1 is Num, builtin::true, '1 is Num' );

Alternatively, use the ability of L to import the operator
with a different name and avoid the collision.

   use Test2::V0;
   use Syntax::Operator::Is is => { -as => "is_checked" };

   is( 1 is_checked Num, builtin::true, '1 is Num' );

=cut

sub import
{
   my $pkg = shift;
   $pkg->apply( 1, @_ );
}

sub unimport
{
   my $pkg = shift;
   $pkg->apply( 0, @_ );
}

sub apply
{
   my $pkg = shift;
   my ( $on, @syms ) = @_;

   @syms or @syms = qw( is );

   $pkg->XS::Parse::Infix::apply_infix( $on, \@syms, qw( is ) );

   croak "Unrecognised import symbols @syms" if @syms;
}

=head1 OPERATORS

=head2 is

   my $ok = $value is $Constraint;

Yields true if the given value is accepted by the given constraint checker.
Yields false but should not otherwise throw an exception if the value is
rejected.

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;