.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PerlX::Maybe 3pm"
.TH PerlX::Maybe 3pm "2018-12-19" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PerlX::Maybe \- return a pair only if they are both defined
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
You once wrote:
.PP
.Vb 4
\& my $bob = Person\->new(
\&    defined $name ? (name => $name) : (),
\&    defined $age ? (age => $age) : (),
\& );
.Ve
.PP
Now you can write:
.PP
.Vb 1
\& use PerlX::Maybe;
\& 
\& my $bob = Person\->new(
\&    maybe name => $name,
\&    maybe age  => $age,
\& );
.Ve
.SH "DESCRIPTION"
.IX Header "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:
.PP
.Vb 4
\& my $bob = Person\->new(
\&    name => $name,
\&    age => $age,
\& );
.Ve
.PP
Will result in the \f(CW\*(C`name\*(C'\fR and \f(CW\*(C`age\*(C'\fR attributes possibly being set to
undef (if the corresponding \f(CW$name\fR and \f(CW$age\fR variables are not defined),
which may violate the Person class' type constraints.
.PP
(Note: if you are the \fIauthor\fR 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.)
.PP
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:
.PP
.Vb 4
\& my $bob = Person\->new(
\&    defined $name ? (name => $name) : (),
\&    defined $age ? (age => $age) : (),
\& );
.Ve
.PP
or:
.PP
.Vb 1
\& use PerlX::Maybe;
\&
\& my $bob = Person\->new(
\&    (name => $name) x!!(defined $name),
\&    (age  => $age)  x!!(defined $age),
\& );
.Ve
.PP
A slightly more elegant solution is the \f(CW\*(C`maybe\*(C'\fR function.
.SS "Functions"
.IX Subsection "Functions"
.ie n .IP """maybe $x => $y, @rest""" 4
.el .IP "\f(CWmaybe $x => $y, @rest\fR" 4
.IX Item "maybe $x => $y, @rest"
This function checks that \f(CW$x\fR and \f(CW$y\fR are both defined. If they
are, it returns them both as a list; otherwise it returns the empty list.
.Sp
If \f(CW@rest\fR is provided, it is unconditionally appended to the end of
whatever list is returned.
.Sp
The combination of these behaviours allows the following very sugary syntax
to \*(L"just work\*(R".
.Sp
.Vb 7
\& my $bob = Person\->new(
\&         name      => $name,
\&         address   => $addr,
\&   maybe phone     => $tel,
\&   maybe email     => $email,
\&         unique_id => $id,
\& );
.Ve
.Sp
This function is exported by default.
.ie n .IP """provided $condition, $x => $y, @rest""" 4
.el .IP "\f(CWprovided $condition, $x => $y, @rest\fR" 4
.IX Item "provided $condition, $x => $y, @rest"
Like \f(CW\*(C`maybe\*(C'\fR but allows you to use a custom condition expression:
.Sp
.Vb 7
\& my $bob = Person\->new(
\&                             name      => $name,
\&                             address   => $addr,
\&   provided length($tel),    phone     => $tel,
\&   provided $email =~ /\e@/,  email     => $email,
\&                             unique_id => $id,
\& );
.Ve
.Sp
This function is not exported by default.
.ie n .IP """provided_deref $condition, $r, @rest""" 4
.el .IP "\f(CWprovided_deref $condition, $r, @rest\fR" 4
.IX Item "provided_deref $condition, $r, @rest"
Like \f(CW\*(C`provided\*(C'\fR but dereferences the second argument into list context:
.Sp
.Vb 11
\& my $bob = Person\->new(
\&                             name        => $name,
\&                             address     => $addr,
\&   provided length($tel),    phone       => $tel,
\&   provided $email =~ /\e@/,  email       => $email,
\&   provided_deref $employee, sub {
\&                             employee_id => $employee\->employee_id,
\&                       maybe department  => $employee\->department,
\&                           },
\&                             unique_id   => $id,
\& );
.Ve
.Sp
The second argument may be a \s-1HASH\s0 or \s-1ARRAY\s0 reference. It may also be a \s-1CODE\s0
reference, which will be called in list context. If it is a blessed object,
it will be treated as if it were a \s-1HASH\s0 reference (internally it could be
another type of reference with overloading). A code reference can be used
if evaluation of the second argument should only occur if the condition is met
(e.g. to prevent method calls on an uninitialised value).
.Sp
This function is not exported by default.
.ie n .IP """provided_deref_with_maybe $condition, $r, @rest""" 4
.el .IP "\f(CWprovided_deref_with_maybe $condition, $r, @rest\fR" 4
.IX Item "provided_deref_with_maybe $condition, $r, @rest"
Like \f(CW\*(C`provide_deref\*(C'\fR but will perform \f(CW\*(C`maybe\*(C'\fR on each key-value pair in
the dereferenced values.
.Sp
.Vb 8
\& my $bob = Person\->new(
\&                             name        => $name,
\&                             address     => $addr,
\&   provided length($tel),    phone       => $tel,
\&   provided $email =~ /\e@/,  email       => $email,
\&   provided_deref_with_maybe $employee, $employee,
\&                             unique_id   => $id,
\& );
.Ve
.Sp
Also, if the second argument is a blessed object, it will also skip any
\&'private' attributes (keys starting with an underscore).
.Sp
It not only \*(L"just works\*(R", it \*(L"\s-1DWIM\s0\*(R"s!
.Sp
This function is not exported by default.
.ie n .IP """PerlX::Maybe::IMPLEMENTATION""" 4
.el .IP "\f(CWPerlX::Maybe::IMPLEMENTATION\fR" 4
.IX Item "PerlX::Maybe::IMPLEMENTATION"
Indicates whether the \s-1XS\s0 backend PerlX::Maybe::XS was loaded.
.SS "\s-1XS\s0 Backend"
.IX Subsection "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.
.PP
Currently there are no \s-1XS\s0 implementations of the \f(CW\*(C`provided_deref\*(C'\fR and
\&\f(CW\*(C`provided_deref_with_maybe\*(C'\fR functions. Contributions welcome.
.SS "Environment"
.IX Subsection "Environment"
The environment variable \f(CW\*(C`PERLX_MAYBE_IMPLEMENTATION\*(C'\fR may be set to
\&\f(CW"PP"\fR to prevent the \s-1XS\s0 backend from loading.
.SS "Exporting"
.IX Subsection "Exporting"
Only \f(CW\*(C`maybe\*(C'\fR is exported by default. You can request other functions
by name:
.PP
.Vb 1
\&  use PerlX::Maybe "maybe", "provided";
.Ve
.PP
Or to export everything:
.PP
.Vb 1
\&  use PerlX::Maybe ":all";
.Ve
.PP
If Exporter::Tiny is installed, you can rename imports:
.PP
.Vb 1
\&  use PerlX::Maybe "maybe" => { \-as => "perhaps" };
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to
<http://rt.cpan.org/Dist/Display.html?Queue=PerlX\-Maybe>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Syntax::Feature::Maybe, PerlX::Maybe::XS.
.PP
MooseX::UndefTolerant, PerlX::Perform, Exporter.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.PP
\&\f(CW\*(C`provided_deref\*(C'\fR and \f(CW\*(C`provided_deref_with_maybe\*(C'\fR by Theo van Hoesel.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2012\-2013, 2018 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0