]> git.vpit.fr Git - perl/modules/Sub-Nary.git/blob - README
Importing Sub-Nary-0.01.tar.gz
[perl/modules/Sub-Nary.git] / README
1 NAME
2     Sub::Nary - Try to count how many elements a subroutine can return in
3     list context.
4
5 VERSION
6     Version 0.01
7
8 SYNOPSIS
9         use Sub::Nary;
10
11         my $sn = Sub::Nary->new();
12         my $r  = $sn->nary(\&hlagh);
13
14 DESCRIPTION
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).
20
21 METHODS
22   "new"
23     The usual constructor. Currently takes no argument.
24
25   "nary $coderf"
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
31
32         { 1 => 0.2, 2 => 0.4, 4 => 0.3, list => 0.1 }
33
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.
37
38   "flush"
39     Flushes the Sub::Nary object cache. Returns the object itself.
40
41 PROBABILITY OF RETURN
42     The probability is computed as such :
43
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
47
48             sub simple {
49              if (rand < 0.1) {
50               return 1;
51              } else {
52               return 2, 3;
53              }
54             }
55
56         is seen returning one or two arguments each with probability "1/2".
57         As for
58
59             sub hlagh {
60              my $x = rand;
61              if ($x < 0.1) {
62               return 1, 2, 3;
63              } elsif ($x > 0.9) {
64               return 4, 5;
65              }
66             }
67
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
71         probability "1/3".
72
73     * The total probability law for a given returning point is the
74     convolution product of the probabilities of its list elements.
75         As such,
76
77             sub notsosimple {
78              return 1, simple(), 2
79             }
80
81         returns 3 or 4 arguments with probability "1/2" ; and
82
83             sub double {
84              return simple(), simple()
85             }
86
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.
90
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 =
93         list". That's why
94
95             sub listy {
96              return 1, simple(), @_
97             }
98
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,
102
103             sub oneorlist {
104              if (rand < 0.1) {
105               return 1
106              } else {
107               return @_
108              }
109             }
110
111             sub composed {
112              return oneorlist(), oneorlist()
113             }
114
115         "composed" returns 2 scalars with probability "1/2 * 1/2 = 1/4" and
116         a "list" with probability "3/4".
117
118 EXPORT
119     An object-oriented module shouldn't export any function, and so does
120     this one.
121
122 CAVEATS
123     The algorithm may be pessimistic (things seen as "list" while they are
124     of fixed length) but not optimistic (the opposite, duh).
125
126     "wantarray" isn't specialized when encountered in the optree.
127
128 DEPENDENCIES
129     perl 5.8.1.
130
131     Carp (standard since perl 5), B (since perl 5.005), XSLoader (since perl
132     5.006) and List::Util (since perl 5.007003).
133
134 AUTHOR
135     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
136
137     You can contact me by mail or on #perl @ FreeNode (vincent or
138     Prof_Vince).
139
140 BUGS
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.
146
147 SUPPORT
148     You can find documentation for this module with the perldoc command.
149
150         perldoc Sub::Nary
151
152     Tests code coverage report is available at
153     <http://www.profvince.com/perl/cover/Sub-Nary>.
154
155 ACKNOWLEDGEMENTS
156     Thanks to Sebastien Aperghis-Tramoni for helping to name this module.
157
158 COPYRIGHT & LICENSE
159     Copyright 2008 Vincent Pit, all rights reserved.
160
161     This program is free software; you can redistribute it and/or modify it
162     under the same terms as Perl itself.
163