README.pod
1=encoding utf-8
2
3=head1 NAME
4
5Call::Context - Sanity-check calling context
6
7=head1 SYNOPSIS
8
9 use Call::Context;
10
11 sub gives_a_list {
12
13 #Will die() if the context is not list.
14 Call::Context::must_be_list();
15
16 return (1, 2, 3);
17 }
18
19 gives_a_list(); #die()s: incorrect context (void)
20
21 my $v = gives_a_list(); #die()s: incorrect context (scalar)
22
23 my @list = gives_a_list(); #lives
24
25=head1 DISCUSSION
26
27If your function only expects to return a list, then a call in some other
28context is, by definition, an error. The problem is that, depending on how
29the function is written, it may actually do something expected in testing, but
30then in production act differently.
31
32=head1 FUNCTIONS
33
34=head2 must_be_list()
35
36C<die()>s if the calling function is itself called outside list context.
37(See the SYNOPSIS for examples.)
38
39=head1 EXCEPTIONS
40
41This module throws instances of C<Call::Context::X>. C<Call::Context::X> is
42overloaded to stringify; however, to keep memory usage low, C<overload> is not
43loaded until instantiation.
44
45=head1 REPOSITORY
46
47https://github.com/FGasper/p5-Call-Context
48
49