1PerlX::Maybe(3)       User Contributed Perl Documentation      PerlX::Maybe(3)
2
3
4

NAME

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

SYNOPSIS

9       You once wrote:
10
11        my $bob = Person->new(
12           defined $name ? (name => $name) : (),
13           defined $age ? (age => $age) : (),
14        );
15
16       Now you can write:
17
18        use PerlX::Maybe;
19
20        my $bob = Person->new(
21           maybe name => $name,
22           maybe age  => $age,
23        );
24

DESCRIPTION

26       Moose classes (and some other classes) distinguish between an attribute
27       being unset and the attribute being set to undef. Supplying a
28       constructor arguments like this:
29
30        my $bob = Person->new(
31           name => $name,
32           age => $age,
33        );
34
35       Will result in the "name" and "age" attributes possibly being set to
36       undef (if the corresponding $name and $age variables are not defined),
37       which may violate the Person class' type constraints.
38
39       (Note: if you are the author of the class in question, you can solve
40       this using MooseX::UndefTolerant. However, some of us are stuck using
41       non-UndefTolerant classes written by third parties.)
42
43       To ensure that the Person constructor does not try to set a name or age
44       at all when they are undefined, ugly looking code like this is often
45       used:
46
47        my $bob = Person->new(
48           defined $name ? (name => $name) : (),
49           defined $age ? (age => $age) : (),
50        );
51
52       or:
53
54        my $bob = Person->new(
55           (name => $name) x!!(defined $name),
56           (age  => $age)  x!!(defined $age),
57        );
58
59       A slightly more elegant solution is the "maybe" function.
60
61   Functions
62       "maybe $x => $y, @rest"
63           This function checks that $x and $y are both defined. If they are,
64           it returns them both as a list; otherwise it returns the empty
65           list.
66
67           If @rest is provided, it is unconditionally appended to the end of
68           whatever list is returned.
69
70           The combination of these behaviours allows the following very
71           sugary syntax to "just work".
72
73            my $bob = Person->new(
74                    name      => $name,
75                    address   => $addr,
76              maybe phone     => $tel,
77              maybe email     => $email,
78                    unique_id => $id,
79            );
80
81           This function is exported by default.
82
83       "provided $condition, $x => $y, @rest"
84           Like "maybe" but allows you to use a custom condition expression:
85
86            my $bob = Person->new(
87                                        name      => $name,
88                                        address   => $addr,
89              provided length($tel),    phone     => $tel,
90              provided $email =~ /\@/,  email     => $email,
91                                        unique_id => $id,
92            );
93
94           This function is not exported by default.
95
96       "provided_deref $condition, $r, @rest"
97           Like "provided" but dereferences the second argument into list
98           context:
99
100            my $bob = Person->new(
101                                        name        => $name,
102                                        address     => $addr,
103              provided length($tel),    phone       => $tel,
104              provided $email =~ /\@/,  email       => $email,
105              provided_deref $employee, sub {
106                                        employee_id => $employee->employee_id,
107                                  maybe department  => $employee->department,
108                                      },
109                                        unique_id   => $id,
110            );
111
112           The second argument may be a HASH or ARRAY reference. It may also
113           be a CODE reference, which will be called in list context. If it is
114           a blessed object, it will be treated as if it were a HASH reference
115           (internally it could be another type of reference with
116           overloading). A code reference can be used if evaluation of the
117           second argument should only occur if the condition is met (e.g. to
118           prevent method calls on an uninitialised value).
119
120           This function is not exported by default.
121
122       "provided_deref_with_maybe $condition, $r, @rest"
123           Like "provide_deref" but will perform "maybe" on each key-value
124           pair in the dereferenced values.
125
126            my $bob = Person->new(
127                                        name        => $name,
128                                        address     => $addr,
129              provided length($tel),    phone       => $tel,
130              provided $email =~ /\@/,  email       => $email,
131              provided_deref_with_maybe $employee, $employee,
132                                        unique_id   => $id,
133            );
134
135           Also, if the second argument is a blessed object, it will also skip
136           any 'private' attributes (keys starting with an underscore).
137
138           It not only "just works", it "DWIM"s!
139
140           This function is not exported by default.
141
142       "PerlX::Maybe::IMPLEMENTATION"
143           Indicates whether the XS backend PerlX::Maybe::XS was loaded.
144
145   XS Backend
146       If you install PerlX::Maybe::XS, a faster XS-based implementation will
147       be used instead of the pure Perl functions. My basic benchmarking
148       experiments seem to show this to be around 30% faster.
149
150       Currently there are no XS implementations of the "provided_deref" and
151       "provided_deref_with_maybe" functions. Contributions welcome.
152
153   Environment
154       The environment variable "PERLX_MAYBE_IMPLEMENTATION" may be set to
155       "PP" to prevent the XS backend from loading.
156
157   Exporting
158       Only "maybe" is exported by default. You can request other functions by
159       name:
160
161         use PerlX::Maybe "maybe", "provided";
162
163       Or to export everything:
164
165         use PerlX::Maybe ":all";
166
167       If Exporter::Tiny is installed, you can rename imports:
168
169         use PerlX::Maybe "maybe" => { -as => "perhaps" };
170

BUGS

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

SEE ALSO

176       Syntax::Feature::Maybe, PerlX::Maybe::XS.
177
178       MooseX::UndefTolerant, PerlX::Perform, Exporter.
179

AUTHOR

181       Toby Inkster <tobyink@cpan.org>.
182
183       "provided_deref" and "provided_deref_with_maybe" by Theo van Hoesel.
184
186       This software is copyright (c) 2012-2013, 2018 by Toby Inkster.
187
188       This is free software; you can redistribute it and/or modify it under
189       the same terms as the Perl 5 programming language system itself.
190

DISCLAIMER OF WARRANTIES

192       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
193       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
194       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
195
196
197
198perl v5.38.0                      2023-07-21                   PerlX::Maybe(3)
Impressum