Toby Inkster > PerlX-Maybe-1.000 > PerlX::Maybe

Download:
PerlX-Maybe-1.000.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.000   Source  

NAME ^

PerlX::Maybe - return a pair only if they are both defined

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.

BUGS ^

Please report any bugs to http://rt.cpan.org/Dist/Display.html?Queue=PerlX-Maybe.

SEE ALSO ^

Syntax::Feature::Maybe, PerlX::Maybe::XS.

MooseX::UndefTolerant, PerlX::Perform, Exporter.

AUTHOR ^

Toby Inkster <tobyink@cpan.org>.

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.

syntax highlighting: