File Coverage

=head1 NAME

Sub::Nary - Try to count how many elements a subroutine can return in list context.

=head1 VERSION

Version 0.02

=cut

=head1 SYNOPSIS

    use Sub::Nary;

    my $sn = Sub::Nary->new();
    my $r  = $sn->nary(\&hlagh);

=head1 DESCRIPTION

This module uses the L<B> framework to walk into subroutines and try to guess how many scalars are likely to be returned in list context. It's not always possible to give a definitive answer to this question at compile time, so the results are given in terms of "probability of return" (to be understood in a sense described below).

=head1 METHODS

=head2 C<new>

The usual constructor. Currently takes no argument.

=head2 C<nary $coderef>

Takes a code reference to a named or anonymous subroutine, and returns a hash reference whose keys are the possible numbers of returning scalars, and the corresponding values the "probability" to get them. The special key C<'list'> is used to denote a possibly infinite number of returned arguments. The return value hence would look at

    { 1 => 0.2, 2 => 0.4, 4 => 0.3, list => 0.1 }

that is, we should get C<1> scalar C<1> time over C<5> and so on. The sum of all values is C<1>. The returned result, and all the results obtained from intermediate subs, are cached into the object.

=head2 C<flush>

Flushes the L<Sub::Nary> object cache. Returns the object itself.

=head1 PROBABILITY OF RETURN

The probability is computed as such :

=over 4

=item * When branching, each branch is considered equally possible.

For example, the subroutine

    sub simple {
     if (rand < 0.1) {
      return 1;
     } else {
      return 2, 3;
     }
    }

is seen returning one or two arguments each with probability C<1/2>.
As for

    sub hlagh {
     my $x = rand;
     if ($x < 0.1) {
      return 1, 2, 3;
     } elsif ($x > 0.9) {
      return 4, 5;
     }
    }

it is considered to return C<3> scalars with probability C<1/2>, C<2> with probability C<1/2 * 1/2 = 1/4> and C<1> (when the two tests fail, the last computed value is returned, which here is C<< $x > 0.9 >> evaluated in the scalar context of the test) with remaining probability C<1/4>.

=item * The total probability law for a given returning point is the convolution product of the probabilities of its list elements.

As such, 

    sub notsosimple {
     return 1, simple(), 2
    }

returns C<3> or C<4> arguments with probability C<1/2> ; and

    sub double {
     return simple(), simple()
    }

never returns C<1> argument but returns C<2> with probability C<1/2 * 1/2 = 1/4>, C<3> with probability C<1/2 * 1/2 + 1/2 * 1/2 = 1/2> and C<4> with probability C<1/4> too.

=item * If a core function may return different numbers of scalars, each kind is considered equally possible.

For example, C<stat> returns C<13> elements on success and C<0> on error. The according probability will then be C<< { 0 => 0.5, 13 => 0.5 } >>.

=item * The C<list> state is absorbing in regard of all the other ones.

This is just a pedantic way to say that "list + fixed length = list".
That's why

    sub listy {
     return 1, simple(), @_
    }

is considered as always returning an unbounded list.

Also, the convolution law does not behave the same when C<list> elements are involved : in the following example,

    sub oneorlist {
     if (rand < 0.1) {
      return 1
     } else {
      return @_
     }
    }

    sub composed {
     return oneorlist(), oneorlist()
    }

C<composed> returns C<2> scalars with probability C<1/2 * 1/2 = 1/4> and a C<list> with probability C<3/4>.

=back

=cut

=head1 EXPORT

An object-oriented module shouldn't export any function, and so does this one.

=head1 CAVEATS

The algorithm may be pessimistic (things seen as C<list> while they are of fixed length) but not optimistic (the opposite, duh).

C<wantarray> isn't specialized when encountered in the optree.

=head1 DEPENDENCIES

L<perl> 5.8.1.

L<Carp> (standard since perl 5), L<B> (since perl 5.005) and L<XSLoader> (since perl 5.006).

=head1 AUTHOR

Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.

You can contact me by mail or on #perl @ FreeNode (vincent or Prof_Vince).

=head1 BUGS

Please report any bugs or feature requests to C<bug-b-nary at rt.cpan.org>, or through the web interface at L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Sub-Nary>.  I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Sub::Nary

Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Sub-Nary>.

=head1 ACKNOWLEDGEMENTS

Thanks to Sebastien Aperghis-Tramoni for helping to name this module.

=head1 COPYRIGHT & LICENSE

Copyright 2008 Vincent Pit, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

=cut