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.03
   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     * When branching, each branch is considered equally possible.
  45         For example, the subroutine
  46
  47             sub simple {
  48              if (rand < 0.1) {
  49               return 1;
  50              } else {
  51               return 2, 3;
  52              }
  53             }
  54
  55         is seen returning one or two arguments each with probability "1/2".
  56         As for
  57
  58             sub hlagh {
  59              my $x = rand;
  60              if ($x < 0.1) {
  61               return 1, 2, 3;
  62              } elsif ($x > 0.9) {
  63               return 4, 5;
  64              }
  65             }
  66
  67         it is considered to return 3 scalars with probability "1/2", 2 with
  68         probability "1/2 * 1/2 = 1/4" and 1 (when the two tests fail, the
  69         last computed value is returned, which here is "$x > 0.9" evaluated
  70         in the scalar context of the test) with remaining probability "1/4".
  71
  72     * The total probability law for a given returning point is the
  73     convolution product of the probabilities of its list elements.
  74         As such,
  75
  76             sub notsosimple {
  77              return 1, simple(), 2
  78             }
  79
  80         returns 3 or 4 arguments with probability "1/2" ; and
  81
  82             sub double {
  83              return simple(), simple()
  84             }
  85
  86         never returns 1 argument but returns 2 with probability "1/2 * 1/2 =
  87         1/4", 3 with probability "1/2 * 1/2 + 1/2 * 1/2 = 1/2" and 4 with
  88         probability "1/4" too.
  89
  90     * If a core function may return different numbers of scalars, each kind
  91     is considered equally possible.
  92         For example, "stat" returns 13 elements on success and 0 on error.
  93         The according probability will then be "{ 0 => 0.5, 13 => 0.5 }".
  94
  95     * The "list" state is absorbing in regard of all the other ones.
  96         This is just a pedantic way to say that "list + fixed length =
  97         list". That's why
  98
  99             sub listy {
 100              return 1, simple(), @_
 101             }
 102
 103         is considered as always returning an unbounded list.
 104
 105         Also, the convolution law does not behave the same when "list"
 106         elements are involved : in the following example,
 107
 108             sub oneorlist {
 109              if (rand < 0.1) {
 110               return 1
 111              } else {
 112               return @_
 113              }
 114             }
 115
 116             sub composed {
 117              return oneorlist(), oneorlist()
 118             }
 119
 120         "composed" returns 2 scalars with probability "1/2 * 1/2 = 1/4" and
 121         a "list" with probability "3/4".
 122
 123 EXPORT
 124     An object-oriented module shouldn't export any function, and so does
 125     this one.
 126
 127 CAVEATS
 128     The algorithm may be pessimistic (things seen as "list" while they are
 129     of fixed length) but not optimistic (the opposite, duh).
 130
 131     "wantarray" isn't specialized when encountered in the optree.
 132
 133 DEPENDENCIES
 134     perl 5.8.1.
 135
 136     Carp (standard since perl 5), B (since perl 5.005) and XSLoader (since
 137     perl 5.006).
 138
 139 AUTHOR
 140     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 141
 142     You can contact me by mail or on #perl @ FreeNode (vincent or
 143     Prof_Vince).
 144
 145 BUGS
 146     Please report any bugs or feature requests to "bug-b-nary at
 147     rt.cpan.org", or through the web interface at
 148     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Nary>. I will be
 149     notified, and then you'll automatically be notified of progress on your
 150     bug as I make changes.
 151
 152 SUPPORT
 153     You can find documentation for this module with the perldoc command.
 154
 155         perldoc Sub::Nary
 156
 157     Tests code coverage report is available at
 158     <http://www.profvince.com/perl/cover/Sub-Nary>.
 159
 160 ACKNOWLEDGEMENTS
 161     Thanks to Sebastien Aperghis-Tramoni for helping to name this module.
 162
 163 COPYRIGHT & LICENSE
 164     Copyright 2008 Vincent Pit, all rights reserved.
 165
 166     This program is free software; you can redistribute it and/or modify it
 167     under the same terms as Perl itself.
 168