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

BUGS

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

SEE ALSO

178       Syntax::Feature::Maybe, PerlX::Maybe::XS.
179
180       MooseX::UndefTolerant, PerlX::Perform, Exporter.
181

AUTHOR

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

DISCLAIMER OF WARRANTIES

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