PerlX::Maybe(3)

💖 NAME 💖

Okay so this is a User Contributed Perl Documentation page, and the manual name is PerlX::Maybe(3) — the whole vibe is return a pair only if they are both defined. Bestie, it's giving "constructor arguments but make them conditional" energy, and honestly? Obsessed. Main character energy fr. 🎀

🎀 SYNOPSIS 🎀

You once wrote this little tragedy, no cap:

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

Now you can write this iconic thing instead:

        use PerlX::Maybe;

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

💅 DESCRIPTION 💅

Okay so Moose classes (and some other classes) distinguish between an attribute being unset and the attribute being set to undef. Supplying 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, bestie: if you are the author of the class in question, you can solve this using MooseX::UndefTolerant. Lowkey, though, 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. Periodt.

🧚 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. Slay. ✨

🦋 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.

🌸 provided_deref $condition, $r, @rest 🌸

Like "provided" but dereferences the second argument into list context:

            my $bob = Person->new(
                                        name        => $name,
                                        address     => $addr,
              provided length($tel),    phone       => $tel,
              provided $email =~ /\@/,  email       => $email,
              provided_deref $employee, sub {
                                        employee_id => $employee->employee_id,
                                  maybe department  => $employee->department,
                                      },
                                        unique_id   => $id,
            );

The second argument may be a HASH or ARRAY reference. It may also be a CODE reference, which will be called in list context. If it is a blessed object, it will be treated as if it were a HASH 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).

This function is not exported by default. It ate, honestly. 💅

🎀 provided_deref_with_maybe $condition, $r, @rest 🎀

Like "provide_deref" (yes, that's the exact spelling in the original, bestie) but will perform "maybe" on each key-value pair in the dereferenced values.

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

Also, if the second argument is a blessed object, it will also skip any 'private' attributes (keys starting with an underscore).

It not only "just works", it "DWIM"s! Iconic.

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. The original docs literally say: "My basic benchmarking experiments seem to show this to be around 30% faster." Ngl, highkey a cute little speed boost. 🏎️

Currently there are no XS implementations of the "provided_deref" and "provided_deref_with_maybe" functions. Contributions welcome.

🌈 Environment 🌈

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

🍓 Exporting 🍓

Only "maybe" is exported by default. You can request other functions by name:

         use PerlX::Maybe "maybe", "provided";

Or to export everything:

         use PerlX::Maybe ":all";

If Exporter::Tiny is installed, you can rename imports:

         use PerlX::Maybe "maybe" => { -as => "perhaps" };

Iykyk, renaming imports is a cute lil flex. 🫶

💀 BUGS 💀

Not me begging you to report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=PerlX-Maybe>. Please do it, bestie. 🙈

👀 SEE ALSO 👀

• Syntax::Feature::Maybe
• PerlX::Maybe::XS
• MooseX::UndefTolerant
• PerlX::Perform
• Exporter

👑 AUTHOR 👑

Toby Inkster <tobyink@cpan.org>.

provided_deref and provided_deref_with_maybe by Theo van Hoesel.

🎀 COPYRIGHT AND LICENCE 🎀

This software is copyright (c) 2012-2013, 2018 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 💜

Legal voice, no cap, fr fr:

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.

---

Source/version check, bestie: perl v5.42.0, dated 2022-03-15, for PerlX::Maybe(3). Bye, love you! 💖✨