view release on metacpan or  search on metacpan

lib/Algorithm/Voting/Sortition.pm  view on Meta::CPAN

	Severus Ginny Hagrid Fred George
    /;

    # the results of our predetermined entropy source
    my @keysource = (
        [32,40,43,49,53,21],  # 8/9/08 powerball numbers
        "W 4-1",              # final score of 8/8/08 Twins game
    );

    # use sortition to determine the winners
    my $race = Algorithm::Voting::Sortition->new(
        candidates => \@candidates,
        source     => \@keysource,
        n          => 2,
    );
    printf "Key string is: '%s'\n", $race->keystring;
    print $race->as_string;

=head1 DESCRIPTION

Sortition is an unbiased method for "drawing straws" or "casting lots".  This
package implements the Sortition algorithm as described in RFC 3797, "Publicly
Verifiable Nominations Committee (NomCom) Random Selection"
(L<http://tools.ietf.org/html/rfc3797>):

=over 4

This document describes a method for making random selections in such a way
that the unbiased nature of the choice is publicly verifiable.  As an example,
the selection of the voting members of the IETF Nominations Committee (NomCom)
from the pool of eligible volunteers is used.  Similar techniques would be
applicable to other cases.

=back

=head1 METHODS

=head2 Algorithm::Voting::Sortition->new( %args )

Constructs a new sortition object.

Example:

    my $s = Algorithm::Voting::Sortition->new(
        candidates => [ 'A' .. 'Z' ],
        n          => 3,
        source     => [ $scalar, \@array, \%hash ],
    );

=cut

sub new {
    my $class = shift;
    my %valid = (
        candidates => 1,
        n          => { default => -1 },
        source     => 0,
        keystring  => 0,
    );
    my %args = validate(@_, \%valid);
    return bless \%args, $class;
}

=head2 $obj->candidates

Returns a list containing the current candidates.

=cut

sub candidates {
    return @{ $_[0]->{candidates} };
}

=head2 $obj->n

Returns the number of candidates that are to be chosen from the master list.
If C<n> is unspecified when the sortition object is constructed, the total
number of candidates is used, i.e. the sortition will return a list containing
all candidates.

=cut

sub n {
    my $self = shift;
    if ($self->{n} < 1) {
        $self->{n} = scalar($self->candidates);
    }
    return $self->{n};
}

=head2 $obj->source()

Mutates the entropy source to be used in the sortition.

Example:

    $obj->source(@entropy); # sets the entropy value
    my @e = $obj->source;   # retrieves the entropy

=cut

sub source {
    my $self = shift;
    if (@_) { $self->{source} = \@_; }
    return @{ $self->{source} };
}

=head2 $obj->keystring()

Uses the current value of C<< $self->source >> to create and cache a master
"key string".

=cut

sub keystring {
    my $self = shift;
    unless (exists $self->{keystring}) {
        $self->{keystring} = $self->make_keystring($self->source);
    }
    return $self->{keystring};
}