/ 
Module-Generic-v0.31.0
River stage two • 17 direct dependents • 20 total dependents
/ Module::Generic::Null

NAME

Module::Generic::Null - Null Value Chaining Object Class

SYNOPSIS

# In your code:
sub customer
{
    my $self = shift( @_ );
    return( $self->error( "No customer id was provided" ) ) if( !scalar( @_ ) );
    return( $self->customer_info_to_object( @_ ) );
}

# And this method is called without providing an id, thus triggering an error,
# but is chained. Upon error triggered by method "error", a Module::Generic::Null
# object is returned
my $name = $object->customer->name;

VERSION

v1.1.1

DESCRIPTION

Normally the call above would have triggered a perl error like Cannot call method name on an undefined value, but since "error" in Module::Generic returns a Module::Generic::Null object, the method name here is called without triggering an error, and returns the right value based on the expectation of the caller which will ultimately result in undef in scalar context or an empty list in list context.

Module::Generic::Null uses AUTOLOAD to allow any method to work in chaining, but contains the original error within its object.

When the AUTOLOAD is called, it checks the call context and returns the appropriate value (self object, code ref, hash ref, array ref, scalar ref, or simply undef or empty list)

If the caller wants an hash reference, it returns an empty hash reference.

If the caller wants an array reference, it returns an empty array reference.

If the caller wants a scalar reference, it returns a scalar reference pointing to undef.

If the caller wants a code reference, it returns an anonymous subroutine that returns undef or an empty list.

If the caller is calling another method right after, this means this is an object context and Module::Generic::Null will return the current object it was called with.

In any other context, undef is returned or an empty list.

Without using Module::Generic::Null, if you return simply undef, like:

my $val = $object->return_false->[0];

sub return_false{ return }

The above would trigger an error that the value returned by return_false is not an array reference. Instead of having the caller checking what kind of returned value was returned, the caller only need to check if it is defined or not, no matter the context in which it is called.

For example:

my $this = My::Object->new;
my $val  = $this->call1;
defined( $val ) || die( $this->error );
# return undef)

# object context
$val = $this->call1->call_again;
defined( $val ) || die( $this->error );
# $val is undefined

# hash reference context
$val = $this->call1->fake->{name};
defined( $val ) || die( $this->error );
# $val is undefined

# array reference context
$val = $this->call1->fake->[0];
defined( $val ) || die( $this->error );
# $val is undefined

# code reference context
$val = $this->call1->fake->();
defined( $val ) || die( $this->error );
# $val is undefined

# scalar reference context
$val = ${$this->call1->fake};
defined( $val ) || die( $this->error );
# $val is undefined

# simple scalar
$val = $this->call1->fake;
defined( $val ) || die( $this->error );
# $val is undefined

package My::Object;
use parent qw( Module::Generic );

sub call1
{
    return( shift->call2 );
}

sub call2 { return( shift->new_null ); }

sub call_again
{
    my $self = shift( @_ );
    print( "Got here in call_again\n" );
    return( $self );
}

Undefined value is the typical response one gets when an error occurred, so you can check like this, assuming you know you normally would not get a false value :

my $name = $object->customer->name || die( $object->error );

Apart from that, this does not do anything meaningful.

METHODS

There is only 1 method. This module makes it possible to call it with any method to fake original data flow.

new

This takes an error object and an optional hash reference of key-value pairs and return the object.

Possible options:

wants

This can be any of (case do not actually matter): ARRAY, BOOLEAN, CODE, GLOB, HASH, LIST, OBJECT, REFSCALAR, SCALAR, VOID

SERIALISATION

Serialisation by CBOR, Sereal and Storable::Improved (or the legacy Storable) is supported by this package. To that effect, the following subroutines are implemented: FREEZE, THAW, STORABLE_freeze and STORABLE_thaw

CREDITS

Based on an original idea from Brian D. Foy discussed on StackOverflow and also on Perl Monks

AUTHOR

Jacques Deguest <jack@deguest.jp>

COPYRIGHT & LICENSE

Copyright (c) 2000-2021 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.