File Coverage

blib/lib/safenav.pm

Criterion	Covered	Total	%
statement	12	12	100.0
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	16	16	100.0

package safenav;
use strict;
use warnings;
use PerlX::SafeNav ('$safenav', '$unsafenav', '&safenav');

use Exporter 'import';
our @EXPORT = ('&safenav');

*begin = *wrap = $safenav;
*end = *unwrap = $unsafenav;

1;

=pod

=encoding utf-8

=head1 NAME

safenav - Safe-navigation for Perl

=head1 SYNOPSIS

    use safenav;

    my $obj = Foo->new;
    my $ret;

    # block syntax
    $ret = safenav { $_->x()->y()->z() } $obj;

    # wrap + unwrap
    $ret = $obj-> safenav::wrap() ->x()->y()->z() -> safenav::unwrap();

    # begin + end
    $ret = $obj-> safenav::begin() ->x()->y()->z() -> safenav::end();

    unless (defined $ret) {
        # The car either have no wheels, or the first wheel has no tire.
        ...
    }

=head1 DESCRIPTION

The C pragma is part of L. It provides alternative interfaces for wrapping a chain of calls and make it safe from encountering C values in the way. If any of sub-expressions yield C, instead of aborting the program with an error message, the entire chain yields C instead.

Say we have this call chain on object C<$o>, and each sub-expression right next to the C<< -> >> operators may yield C:

    $o->a()->{b}->c()->[42]->d();

To make it safe from encountering C values, we wrap the chain with C and C:

    $o-> safenav::wrap() -> a()->{b}->c()->[42]->d() -> safenav::unwrap();

... or with C and C:

    $o-> safenav::begin() -> a()->{b}->c()->[42]->d() -> safenav::end()

... or, with a C block:

    safenav {
        $_->a()->{b}->c()->[42]->d()
    } $o;

... in which, C<$_> is the safenav-wrapped version of C<$o>, and the chain is automaticly un-wrapped at the end.

Whichever seems better for you.

=head1 SEE ALSO

L, L

=cut