NAME

Vote::Count::Common

VERSION 1.213

Synopsis

This Role is consumed by Vote::Count and Vote::Count::Matrix. It provides common methods for the Active Set.

Usage

This role is consumed by Vote::Count and Vote::Count::Matrix, providing a common set of functions to all Vote::Count objects.

new

The only required parameter is BallotSet. The BallotSet is provided by Vote::Count::ReadBallots, you may place the BallotSet in a variable or more typically read it from within the new method.

  use Vote::Count;
  use Vote::Count::ReadBallots;
  my $Election = Vote::Count->new( BallotSet => read_ballots( $ballotfile ) );

Optional Paramters to Vote::Count

Active

Sets the Active Set at creation. See "Active Sets".

VoteValue

Use to set a Vote Value for methods that weight votes. The default value is 1.

LogTo

Sets a path and Naming pattern for writing logs with the WriteLogs method. If LogTo is not provided the default location is /tmp/votecount.

  'LogTo' => '/logging_path/election_name'

See Vote::Count::Log for more informationand and additional log path options.

Logging Methods

Vote::Count writes 3 logs: terse/brief, verbose, and detail. The three logging methods logt, logv, and logd are used to record messages to those respective logs. The WriteLogs method is used to write the logs to disk.

For more detail, see Vote::Count::Log.

Active Sets

Active sets are a Hash Reference where the keys represent the active choices and the value is true. The VoteCount Object contains an Active Set which can be Accessed via the Active() method which will return a reference to the Active Set (changing the reference will change the active set). The GetActive and SetActive methods break the reference links. GetActiveList returns the Active Set as a sorted list.

Many Components will take an argument for $activeset or default to the current Active set of the Vote::Count object, which is defaulted to the Choices defined in the BallotSet.

Active

Get Active Set as HashRef to the active set. Changing the new HashRef will change the internal Active Set, GetActive is often preferable as it will return a HashRef that is a copy instead. Active may be used as an optional parameter to new.

GetActive

Returns a hashref containing a copy of the Active Set.

GetActiveList

Returns a simple array of the members of the Active Set.

ResetActive

Sets the Active Set to the full choices list of the BallotSet.

SetActive

Sets the Active Set to provided HashRef. The values to the hashref should evaluate as True.

SetActiveFromArrayRef

Same as SetActive except it takes an ArrayRef of the choices to be set as Active.

Vote::Count Methods

Most of these are provided by the Role Common and available directly in both Matrix objects and Vote::Count Objects. Vote::Count objects create a child Matrix object: PairMatrix.

BallotSet

Get BallotSet

PairMatrix

Get a Matrix Object for the Active Set. Generated and cached on the first request.

UpdatePairMatrix

Regenerate and cache Matrix with current Active Set.

VotesCast

Returns the number of votes cast.

VotesActive

Returns the number of non-exhausted ballots based on the current Active Set.

new

Has the following Attributes:

WithdrawalList

A text file containing choices 1 per line that are withdrawn. Use when a choice may be included in the ballots but should be treated as not-present. Removing a choice from the choices list in a Ballot File will generate an exception from ReadBallots if it appears on any Ballots. Withdrawing a choice will exclude it from the Active Set if it is present in the Ballots.

Active

Get Active Set as HashRef to the active set. Changing the new HashRef will change the internal Active Set, GetActive is recommended as it will return a HashRef that is a copy instead.

GetActive

Returns a hashref containing a copy of the Active Set.

Choices

Returns an array of all of the Choices in the Ballot Set.

GetActiveList

Returns a simple array of the members of the Active Set.

ResetActive

Sets the Active Set to the full choices list of the BallotSet.

SetActive

Sets the Active Set to provided HashRef. The values to the hashref should evaluate as True.

SetActiveFromArrayRef

Same as SetActive except it takes an ArrayRef of the choices to be set as Active.

Defeat

Remove $choice from current Active List.

  $Election->Defeat( $choice );
  $Election->logv( "Defeated $choice");

BallotSet

Get BallotSet

GetBallots

Get just the Ballots from the BallotSet.

PairMatrix

Get a Matrix Object for the Active Set. Generated and cached on the first request.

UpdatePairMatrix

Regenerate and cache Matrix with current Active Set.

VotesCast

Returns the number of votes cast.

VotesActive

Returns the number of non-exhausted ballots based on the current Active Set.

VoteValue

Sets a VoteValue for use in weighted systems like STV. The default value is 1. Approval and TopCount are aware of VoteValue for RCV ballots.

BUG TRACKER

https://github.com/brainbuz/Vote-Count/issues

AUTHOR

John Karr (BRAINBUZ) brainbuz@cpan.org

CONTRIBUTORS

Copyright 2019-2021 by John Karr (BRAINBUZ) brainbuz@cpan.org.

LICENSE

This module is released under the GNU Public License Version 3. See license file for details. For more information on this license visit http://fsf.org.

SUPPORT

This software is provided as is, per the terms of the GNU Public License. Professional support and customisation services are available from the author.