SYNOPSIS

You once wrote:

my $bob = Person->new(
defined $name ? (name => $name) : (),
defined $age ? (age => $age) : (),
);

Now you can write:

 my $bob = Person->new(
    maybe name => $name,
    maybe age  => $age,
 );

DESCRIPTION

Moose classes (and some other classes) distinguish between an attribute being unset and the attribute being set to undef. Supplying a constructor arguments like this:

 my $bob = Person->new(
    name => $name,
    age => $age,
 );

Will result in the "name" and "age" attributes possibly being set to undef (if the corresponding $name and $age variables are not defined), which may violate the Person class' type constraints.

(Note: if you are the author of the class in question, you can solve this using MooseX::UndefTolerant. However, some of us are stuck using non-UndefTolerant classes written by third parties.)

To ensure that the Person constructor does not try to set a name or age at all when they are undefined, ugly looking code like this is often used:

 my $bob = Person->new(
    defined $name ? (name => $name) : (),
    defined $age ? (age => $age) : (),
 );

or:

 my $bob = Person->new(
    (name => $name) x!!(defined $name),
    (age  => $age)  x!!(defined $age),
 );

A slightly more elegant solution is the "maybe" function.

Functions

"maybe $x => $y, @rest"

This function checks that $x and $y are both defined. If they are, it returns them both as a list; otherwise it returns the empty list.

If @rest is provided, it is unconditionally appended to the end of whatever list is returned.

The combination of these behaviours allows the following very sugary syntax to ``just work''.

 my $bob = Person->new(
         name      => $name,
         address   => $addr,
   maybe phone     => $tel,
   maybe email     => $email,
         unique_id => $id,
 );

This function is exported by default.

"provided $condition, $x => $y, @rest"

Like "maybe" but allows you to use a custom condition expression:

 my $bob = Person->new(
                             name      => $name,
                             address   => $addr,
   provided length($tel),    phone     => $tel,
   provided $email =~ /\@/,  email     => $email,
                             unique_id => $id,
 );

This function is not exported by default.

"PerlX::Maybe::IMPLEMENTATION"

Indicates whether the XS backend PerlX::Maybe::XS was loaded.

XS Backend

If you install PerlX::Maybe::XS, a faster XS-based implementation will be used instead of the pure Perl functions. My basic benchmarking experiments seem to show this to be around 30% faster.

Environment

The environment variable "PERLX_MAYBE_IMPLEMENTATION" may be set to "PP" to prevent the XS backend from loading.

AUTHOR

Toby Inkster <[email protected]>.

COPYRIGHT AND LICENCE

This software is copyright (c) 2012-2013 by Toby Inkster.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTIES

THIS PACKAGE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.