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.

