README
1NAME
2 Return::Type - specify a return type for a function (optionally with
3 coercion)
4
5SYNOPSIS
6 use Return::Type;
7 use Types::Standard qw(Int);
8
9 sub first_item :ReturnType(Int) {
10 return $_[0];
11 }
12
13 my $answer = first_item(42, 43, 44); # returns 42
14 my $pie = first_item(3.141592); # throws an error!
15
16DESCRIPTION
17 Return::Type allows you to specify a return type for your subs. Type
18 constraints from any Type::Tiny, MooseX::Types or MouseX::Types type
19 library are supported.
20
21 The simple syntax for specifying a type constraint is shown in the
22 "SYNOPSIS". If the attribute is passed a single type constraint as shown,
23 this will be applied to the return value if called in scalar context, and
24 to each item in the returned list if called in list context. (If the sub
25 is called in void context, type constraints are simply ignored.)
26
27 It is possible to specify different type constraints for scalar and list
28 context:
29
30 sub foo :ReturnType(scalar => Int, list => HashRef[Num]) {
31 if (wantarray) {
32 return (pie => 3.141592);
33 }
34 else {
35 return 42;
36 }
37 }
38
39 The return value is not type checked if the function is called in void
40 context.
41
42 # Note that the ~Any type is the opposite of Any.
43 # So all values will fail the type check.
44 # That means that the following function can only
45 # be called in void context.
46 #
47 sub foo :ReturnType(scalar => ~Any, list => ~Any) {
48 ...;
49 }
50
51 # Shortcut for the above.
52 #
53 sub foo :ReturnType(Void) {
54 ...;
55 }
56
57 Note that because type constraint libraries are really aimed at validating
58 scalars, the type constraint for the list is specified as a *hashref* of
59 numbers and not a hash of numbers! For the purposes of validation against
60 the type constraint, we slurp the returned list into a temporary arrayref
61 or hashref.
62
63 For type constraints with coercions, you can also pass the option `coerce
64 => 1`:
65
66 use Return::Type;
67 use Types::Standard qw( Int Num );
68
69 # Define a subtype of "Int" at compile time, which can
70 # coerce from "Num" by rounding to nearest integer.
71 use constant Rounded => Int->plus_coercions(Num, sub { int($_) });
72
73 sub first_item :ReturnType(scalar => Rounded, coerce => 1) {
74 return $_[0];
75 }
76
77 my $answer = first_item(42, 43, 44); # returns 42
78 my $pie = first_item(3.141592); # returns 3
79
80 The options `coerce_scalar` and `coerce_list` are also available if you
81 wish to enable coercion only in particular contexts.
82
83 Power-user Inferface
84 Rather than using the `:ReturnType` attribute, it's possible to wrap a
85 coderef like this:
86
87 my $wrapped = Return::Type->wrap_sub($orig, %options);
88
89 The accepted options are `scalar`, `list`, `coerce`, `coerce_list`, and
90 `coerce_scalar`, as per the attribute-based interface.
91
92 There is an additional option `scope_upper` which will load and use
93 Scope::Upper so that things like `caller` used within the wrapped sub are
94 unaware of being wrapped. This behaviour was the default prior to
95 Return::Type 0.004, but is now optional and disabled by default.
96
97BUGS
98 Please report any bugs to
99 <http://rt.cpan.org/Dist/Display.html?Queue=Return-Type>.
100
101SUPPORT
102 IRC: support is available through in the *#moops* channel on irc.perl.org
103 <http://www.irc.perl.org/channels.html>.
104
105SEE ALSO
106 Attribute::Contract, Sub::Filter, Sub::Contract.
107
108AUTHOR
109 Toby Inkster <tobyink@cpan.org>.
110
111COPYRIGHT AND LICENCE
112 This software is copyright (c) 2013-2014 by Toby Inkster.
113
114 This is free software; you can redistribute it and/or modify it under the
115 same terms as the Perl 5 programming language system itself.
116
117DISCLAIMER OF WARRANTIES
118 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
119 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
120 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
121
122