2 Sub::Nary - Try to count how many elements a subroutine can return in
11 my $sn = Sub::Nary->new();
12 my $r = $sn->nary(\&hlagh);
15 This module uses the B framework to walk into subroutines and try to
16 guess how many scalars are likely to be returned in list context. It's
17 not always possible to give a definitive answer to this question at
18 compile time, so the results are given in terms of "probability of
19 return" (to be understood in a sense described below).
23 The usual constructor. Currently takes no argument.
26 Takes a code reference to a named or anonymous subroutine, and returns a
27 hash reference whose keys are the possible numbers of returning scalars,
28 and the corresponding values the "probability" to get them. The special
29 key 'list' is used to denote a possibly infinite number of returned
30 arguments. The return value hence would look at
32 { 1 => 0.2, 2 => 0.4, 4 => 0.3, list => 0.1 }
34 that is, we should get 1 scalar 1 time over 5 and so on. The sum of all
35 values is 1. The returned result, and all the results obtained from
36 intermediate subs, are cached into the object.
39 Flushes the Sub::Nary object cache. Returns the object itself.
42 The probability is computed as such :
44 * All the returning points in the same subroutine (i.e. all the explicit
45 "return" and the last computed value) are considered equally possible.
46 For example, the subroutine
56 is seen returning one or two arguments each with probability "1/2".
68 it is considered to return 1 (when the two tests fail, the last
69 computed value is returned, which here is "$x > 0.9" evaluated in
70 the scalar context of the test), 2 or 3 arguments each with
73 * The total probability law for a given returning point is the
74 convolution product of the probabilities of its list elements.
81 returns 3 or 4 arguments with probability "1/2" ; and
84 return simple(), simple()
87 never returns 1 argument but returns 2 with probability "1/2 * 1/2 =
88 1/4", 3 with probability "1/2 * 1/2 + 1/2 * 1/2 = 1/2" and 4 with
89 probability "1/4" too.
91 * The 'list' state is absorbant in regard of all the other ones.
92 This is just a pedantic way to say that "list + fixed length =
96 return 1, simple(), @_
99 is considered as always returning an unbounded list. The convolution
100 law also does not behave the same when "list" elements are involved
101 : in the following example,
112 return oneorlist(), oneorlist()
115 "composed" returns 2 scalars with probability "1/2 * 1/2 = 1/4" and
116 a "list" with probability "3/4".
119 An object-oriented module shouldn't export any function, and so does
123 The algorithm may be pessimistic (things seen as "list" while they are
124 of fixed length) but not optimistic (the opposite, duh).
126 "wantarray" isn't specialized when encountered in the optree.
131 Carp (standard since perl 5), B (since perl 5.005), XSLoader (since perl
132 5.006) and List::Util (since perl 5.007003).
135 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
137 You can contact me by mail or on #perl @ FreeNode (vincent or
141 Please report any bugs or feature requests to "bug-b-nary at
142 rt.cpan.org", or through the web interface at
143 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Nary>. I will be
144 notified, and then you'll automatically be notified of progress on your
145 bug as I make changes.
148 You can find documentation for this module with the perldoc command.
152 Tests code coverage report is available at
153 <http://www.profvince.com/perl/cover/Sub-Nary>.
156 Thanks to Sebastien Aperghis-Tramoni for helping to name this module.
159 Copyright 2008 Vincent Pit, all rights reserved.
161 This program is free software; you can redistribute it and/or modify it
162 under the same terms as Perl itself.