File Coverage

blib/lib/safenav.pm

Criterion	Covered	Total	%
statement	9	9	100.0
branch			n/a
condition			n/a
subroutine	3	3	100.0
pod			n/a
total	12	12	100.0

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

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

1;

=pod

=encoding utf-8

=head1 NAME

safenav - Safe-navigation for Perl

=head1 SYNOPSIS

    use safenav;

    my $tire_age = $car
         -> safenav::wrap()
         -> wheels()
         -> [0]               # undef, if no wheels at all.
         -> tire()            # undef, if no tire on the wheel.
         -> {created_on}
         -> delta_days($now)
         -> safenav::unwrap();

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

=head1 DESCRIPTION

This C pragma provides helper methods 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.

This pragma is part of L. It is just an alternative interface.

Say we have this chain, in which each part right after ther C<< -> >> operator may yield C:

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

To make it safe from C values, we mark the beginning and the end with C and C:

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

Or alternatively, with C and C:

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

Whichever seems better for you.

=head1 SEE ALSO

L, L

=cut