File Coverage

blib/lib/Syntax/Operator/ExistsOr.pm

Criterion	Covered	Total	%
statement	20	25	80.0
branch	4	8	50.0
condition			n/a
subroutine	6	8	75.0
pod	0	3	0.0
total	30	44	68.1

#  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, 2022-2023 -- [e-mail]

package Syntax::Operator::ExistsOr 0.02;

use v5.14;
use warnings;

use Carp;

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

=head1 NAME

C - an infix operator sensitive to hash element existence

=head1 SYNOPSIS

On a suitable perl version:

   use Syntax::Operator::ExistsOr;

   sub func ( %args ) {
      my $count = $args{count} \\ 10;

      say "Count is ", $count // "";
   }

   func( count => 20 );
   func();

   func( count => undef );

=head1 DESCRIPTION

This module provides an infix operator that similar to the defined-or C
core perl operator, but which cares about hash element existence rather than
definedness.

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.

This module does not provide wrapper functions for the operators, as their
inherent short-circuiting behaviour would appear confusing when expressed in
function-like syntax.

=cut

sub import
{
   my $pkg = shift;
   my $caller = caller;

   $pkg->import_into( $caller, @_ );
}

sub unimport
{
   my $pkg = shift;
   my $caller = caller;

   $pkg->unimport_into( $caller, @_ );
}

sub import_into   { shift->apply( 1, @_ ) }
sub unimport_into { shift->apply( 0, @_ ) }

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

   @syms or @syms = qw( existsor );

   my %syms = map { $_ => 1 } @syms;
   if( delete $syms{existsor} ) {
      $on ? $^H{"Syntax::Operator::ExistsOr/existsor"}++
          : delete $^H{"Syntax::Operator::ExistsOr/existsor"};
   }

   croak "Unrecognised import symbols @{[ keys %syms ]}" if keys %syms;
}

=head1 OPERATORS

=head2 \\

   my $value = $hash{$key} \\ EXPR;

The lefthand operand must be a hash element access (i.e. C<$hash{$key}> or
C<< $href->{$key} >> for some expressions yielding a key and a hashref).

If the hash contains the given key then the operator yields its value (even if
that value is C). If the key does not exist in the hash, then the
righthand operand will be evaluated in scalar context and its value returned.

This is a short-circuiting operator; if the hash does contain the key then the
righthand side expression is not evaluated at all.

This operator parses at the same precedence level as the logical-or operators
(C<||> and C).

=head2 existsor

   do {
      $hash{$key} existsor EXPR;
   };

Similar to the C<\\> operator but parses at the same level as the
low-precedence or operator (C). This is unlikely to be very useful, as
normally C would be used for value-less control flow. Such a potential use
for this operator would be neater written

   exists $hash{$key} or EXPR;

It is included largely for completeness.

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;