Debian Codegraph @

README

raw
1 NAME
2 PerlX::Maybe - return a pair only if they are both defined
3
4 SYNOPSIS
5 You once wrote:
6
7 my $bob = Person->new(
8 defined $name ? (name => $name) : (),
9 defined $age ? (age => $age) : (),
10 );
11
12 Now you can write:
13
14 use PerlX::Maybe;
15
16 my $bob = Person->new(
17 maybe name => $name,
18 maybe age => $age,
19 );
20
21 DESCRIPTION
22 Moose classes (and some other classes) distinguish between an attribute
23 being unset and the attribute being set to undef. Supplying a constructor
24 arguments like this:
25
26 my $bob = Person->new(
27 name => $name,
28 age => $age,
29 );
30
31 Will result in the `name` and `age` attributes possibly being set to undef
32 (if the corresponding $name and $age variables are not defined), which may
33 violate the Person class' type constraints.
34
35 (Note: if you are the *author* of the class in question, you can solve
36 this using MooseX::UndefTolerant. However, some of us are stuck using
37 non-UndefTolerant classes written by third parties.)
38
39 To ensure that the Person constructor does not try to set a name or age at
40 all when they are undefined, ugly looking code like this is often used:
41
42 my $bob = Person->new(
43 defined $name ? (name => $name) : (),
44 defined $age ? (age => $age) : (),
45 );
46
47 or:
48
49 my $bob = Person->new(
50 (name => $name) x!!(defined $name),
51 (age => $age) x!!(defined $age),
52 );
53
54 A slightly more elegant solution is the `maybe` function.
55
56 Functions
57 `maybe $x => $y, @rest`
58 This function checks that $x and $y are both defined. If they are, it
59 returns them both as a list; otherwise it returns the empty list.
60
61 If @rest is provided, it is unconditionally appended to the end of
62 whatever list is returned.
63
64 The combination of these behaviours allows the following very sugary
65 syntax to "just work".
66
67 my $bob = Person->new(
68 name => $name,
69 address => $addr,
70 maybe phone => $tel,
71 maybe email => $email,
72 unique_id => $id,
73 );
74
75 This function is exported by default.
76
77 `provided $condition, $x => $y, @rest`
78 Like `maybe` but allows you to use a custom condition expression:
79
80 my $bob = Person->new(
81 name => $name,
82 address => $addr,
83 provided length($tel), phone => $tel,
84 provided $email =~ /\@/, email => $email,
85 unique_id => $id,
86 );
87
88 This function is not exported by default.
89
90 `provided_deref $condition, $r, @rest`
91 Like `provided` but dereferences the second argument into list
92 context:
93
94 my $bob = Person->new(
95 name => $name,
96 address => $addr,
97 provided length($tel), phone => $tel,
98 provided $email =~ /\@/, email => $email,
99 provided_deref $employee, sub {
100 employee_id => $employee->employee_id,
101 maybe department => $employee->department,
102 },
103 unique_id => $id,
104 );
105
106 The second argument may be a HASH or ARRAY reference. It may also be a
107 CODE reference, which will be called in list context. If it is a
108 blessed object, it will be treated as if it were a HASH reference
109 (internally it could be another type of reference with overloading). A
110 code reference can be used if evaluation of the second argument should
111 only occur if the condition is met (e.g. to prevent method calls on an
112 uninitialised value).
113
114 This function is not exported by default.
115
116 `provided_deref_with_maybe $condition, $r, @rest`
117 Like `provide_deref` but will perform `maybe` on each key-value pair
118 in the dereferenced values.
119
120 my $bob = Person->new(
121 name => $name,
122 address => $addr,
123 provided length($tel), phone => $tel,
124 provided $email =~ /\@/, email => $email,
125 provided_deref_with_maybe $employee, $employee,
126 unique_id => $id,
127 );
128
129 Also, if the second argument is a blessed object, it will also skip
130 any 'private' attributes (keys starting with an underscore).
131
132 It not only "just works", it "DWIM"s!
133
134 This function is not exported by default.
135
136 `PerlX::Maybe::IMPLEMENTATION`
137 Indicates whether the XS backend PerlX::Maybe::XS was loaded.
138
139 XS Backend
140 If you install PerlX::Maybe::XS, a faster XS-based implementation will be
141 used instead of the pure Perl functions. My basic benchmarking experiments
142 seem to show this to be around 30% faster.
143
144 Currently there are no XS implementations of the `provided_deref` and
145 `provided_deref_with_maybe` functions. Contributions welcome.
146
147 Environment
148 The environment variable `PERLX_MAYBE_IMPLEMENTATION` may be set to "PP"
149 to prevent the XS backend from loading.
150
151 Exporting
152 Only `maybe` is exported by default. You can request other functions by
153 name:
154
155 use PerlX::Maybe "maybe", "provided";
156
157 Or to export everything:
158
159 use PerlX::Maybe ":all";
160
161 If Exporter::Tiny is installed, you can rename imports:
162
163 use PerlX::Maybe "maybe" => { -as => "perhaps" };
164
165 BUGS
166 Please report any bugs to
167 <http://rt.cpan.org/Dist/Display.html?Queue=PerlX-Maybe>.
168
169 SEE ALSO
170 Syntax::Feature::Maybe, PerlX::Maybe::XS.
171
172 MooseX::UndefTolerant, PerlX::Perform, Exporter.
173
174 AUTHOR
175 Toby Inkster <[email protected]>.
176
177 `provided_deref` and `provided_deref_with_maybe` by Theo van Hoesel.
178
179 COPYRIGHT AND LICENCE
180 This software is copyright (c) 2012-2013, 2018 by Toby Inkster.
181
182 This is free software; you can redistribute it and/or modify it under the
183 same terms as the Perl 5 programming language system itself.
184
185 DISCLAIMER OF WARRANTIES
186 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
187 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
188 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
189