/ 
App-War-0.02
River stage zero No dependents
/ App::War

NAME

App::War - turn one big decision into many small decisions

SYNOPSIS

use App::War;
my $war = App::War->new;
$war->items(qw/ this that the-other that-too /);
$war->init;
$war->rank;
print $war->report;

DESCRIPTION

How do you go about ranking a number of items? One way to do it is to compare the objects two at a time until a clear winner can be established.

This module does just that, using a topological sort to establish a unique ordering of all the "combatants" in the "war".

This module is modeled loosely after http://kittenwar.com/, a crowdsourced web application for determining the cutest kitten in the universe.

METHODS

App::War->new()

Constructs a new war object.

$war->run

Starts the war.

$war->init

Uses the content of $self->items to initialize a graph containing only vertices, one per item.

$war->report

Returns the current state of the war graph as a multiline string.

$war->graph

Returns the graph object that stores the user choices.

$war->items

Get/set the items to be ranked. It's a bad idea to modify this once the war has started.

$war->rank

Starts the process of uniquely ordering the graph vertices. This method calls method tsort_not_unique until it returns false, i.e. we have a unique topo sort.

$war->tsort_not_unique

This method returns a true value (more on this later) if the graph currently lacks a unique topo sort. If the graph has a unique sort, the "war" is over, and results should be reported.

If the graph lacks a unique topological sort, this method returns an arrayref containing a pair of vertices that have an ambiguous ordering. From http://en.wikipedia.org/wiki/Topological_sorting:

    If a topological sort has the property that all pairs of consecutive vertices in the sorted order are connected by edges, then these edges form a directed Hamiltonian path in the DAG. If a Hamiltonian path exists, the topological sort order is unique; no other order respects the edges of the path.

This property of the topological sort is used to ensure that we have a unique ordering of the "combatants" in our "war".

$war->compare($index1,$index2)

Handles user interaction choosing one of two alternatives. Arguments $index1 and $index2 are indexes into the internal array of items to be ranked, and indicate the two items that need to have their rank disambiguated.

AUTHOR

John Trammell, <johntrammell <at> gmail <dot> com>

BUGS

Please report any bugs or feature requests to bug-app-war at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=App-War. 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 App::War

Your operating system may also have installed a manual page for this module; it would likely be available via the command

man war

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2009 John Trammell, all rights reserved.

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