The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Sub-Frequency-0.05
River stage zero No dependents
1 ++
/ Sub::Frequency

NAME

Sub::Frequency - Run code blocks according to a given probability

SYNOPSIS

    use Sub::Frequency;

    always {
        # code here will always run
    };

    usually {
        # code here will run 75% of the time
        # 'normally' and 'often' also work
    };

    sometimes {
        # code here will run 50% of the time
        # 'maybe' also works
    };

    rarely {
        # code here will run 25% of the time
        # 'seldom' also works
    };

    never {
        # code here will never run
    };

You can also specify your own probability for the code to run:

    with_probability 0.42 => sub {
        ...
    };

Since version 0.03 you can chain probabilities together:

    normally {

        # code here will run 75% of the time

    } maybe {

        # code here will run 50% of the remaining 25% of the time,
        # ie 12.5% of the total time

    } seldom {

        # code here will run 25% of the remaining 12.5% of the time,
        # ie 3.125% of the total time

    } always {

        # code here will run on the remaining time, ie 9,375% of the time

    };

Note an absence of some semicolons compared with the previous examples.

The function with_probability cannot be chained yet.

DESCRIPTION

This module provides a small DSL to deal with an event's frequency, or likelihood of happening.

Potential aplications include games, pseudo-random events and anything that may or may not run with a given probability.

EXPORTS

All functions are exported by default using Exporter.

If you need to rename any of the keywords, consider using Sub::Import to get Sub::Exporter's flexibility.

always

Takes a mandatory subroutine and executes it every time.

usually

normally

often

Takes a mandatory subroutine and executes it with a probability of 75%.

sometimes

maybe

Takes a mandatory subroutine and executes it with a probability of 50%.

rarely

seldom

Takes a mandatory subroutine and executes it with a probability of 25%.

never

Takes a mandatory subroutine and does nothing.

with_probability

Takes a probability and a subroutine, and executes the subroutine with the given probability.

The probability may be a real number between 0 and 1, or a percentage, passed as a string:

    with_probability 0.79 => \&foo;

    with_probability '79%' => \&bar;

Also, for greater flexibility, spaces around the number are trimmed, and we don't care about leading zeros:

    with_probability .04 => \&baz;

    with_probability ' .4  %  ' => \&something;

And you can, of course, replace the => with a ,:

    with_probability 20, {
        say "Mutley, do something!"
    };

TIP: OFTEN (THIS), ELSE (THAT)

Just chain your probability call with an always() call:

    sometimes {
        ...
    } always {
        ...
    };

In chained mode, the next function will be called when the first isn't (meaning "1 - p" of the times). Adding an always() call as that next function will make the remainder part always be called, working like an "else" for your probability block..

DIAGNOSTICS

"$foo does not look like a number or a percentage."

Hint: Are you using something other than '.' as your floating point separator?

This coercion error may occur when you try passing a scalar to with_probability() with something that doesn't look like a number or a percentage. Like:

    with_probability 'monkey', { say 'some code' };

In the code above, you should replace 'monkey' with a number between 0 and 1, or a percentage string (such as '15%').

CAVEATS

* calling return() will return from the block itself, not from the parent sub. For example, the code below will likely NOT do what you want:

  sub foo {
    sometimes { return 1 }; # WRONG! Don't do this
    return 2;
  }

To get the desired behavior, you can either play with modules such as Scope::Upper or do something like this:

  sub foo {
     my $value = 2;
     sometimes { $value = 1 };
     return $value;
  }

SEE ALSO

Sub::Rate

Sub::Retry

AUTHORS

Breno G. de Oliveira (garu), <garu at cpan.org>

Tiago Peczenyj (pac-man)

CONTRIBUTORS

Thiago Rondon (maluco) tbr at cpan.org>

Wesley Dal`Col (blabos) <blabos at cpan.org>

BUGS

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

SUPPORT

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

    perldoc Sub::Frequency

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Breno G. de Oliveira, Tiago Peczenyj.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.