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.02
   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 $coderef"
  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     * If a core function may return different numbers of scalars, each kind
  92     is considered equally possible.
  93         For example, "stat" returns 13 elements on success and 0 on error.
  94         The according probability will then be "{ 0 => 0.5, 13 => 0.5 }".
  95
  96     * The "list" state is absorbing in regard of all the other ones.
  97         This is just a pedantic way to say that "list + fixed length =
  98         list". That's why
  99
 100             sub listy {
 101              return 1, simple(), @_
 102             }
 103
 104         is considered as always returning an unbounded list.
 105
 106         Also, the convolution law does not behave the same when "list"
 107         elements are involved : in the following example,
 108
 109             sub oneorlist {
 110              if (rand < 0.1) {
 111               return 1
 112              } else {
 113               return @_
 114              }
 115             }
 116
 117             sub composed {
 118              return oneorlist(), oneorlist()
 119             }
 120
 121         "composed" returns 2 scalars with probability "1/2 * 1/2 = 1/4" and
 122         a "list" with probability "3/4".
 123
 124 EXPORT
 125     An object-oriented module shouldn't export any function, and so does
 126     this one.
 127
 128 CAVEATS
 129     The algorithm may be pessimistic (things seen as "list" while they are
 130     of fixed length) but not optimistic (the opposite, duh).
 131
 132     "wantarray" isn't specialized when encountered in the optree.
 133
 134 DEPENDENCIES
 135     perl 5.8.1.
 136
 137     Carp (standard since perl 5), B (since perl 5.005), XSLoader (since perl
 138     5.006) and List::Util (since perl 5.007003).
 139
 140 AUTHOR
 141     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 142
 143     You can contact me by mail or on #perl @ FreeNode (vincent or
 144     Prof_Vince).
 145
 146 BUGS
 147     Please report any bugs or feature requests to "bug-b-nary at
 148     rt.cpan.org", or through the web interface at
 149     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Nary>. I will be
 150     notified, and then you'll automatically be notified of progress on your
 151     bug as I make changes.
 152
 153 SUPPORT
 154     You can find documentation for this module with the perldoc command.
 155
 156         perldoc Sub::Nary
 157
 158     Tests code coverage report is available at
 159     <http://www.profvince.com/perl/cover/Sub-Nary>.
 160
 161 ACKNOWLEDGEMENTS
 162     Thanks to Sebastien Aperghis-Tramoni for helping to name this module.
 163
 164 COPYRIGHT & LICENSE
 165     Copyright 2008 Vincent Pit, all rights reserved.
 166
 167     This program is free software; you can redistribute it and/or modify it
 168     under the same terms as Perl itself.
 169