Updated documentation

This commit is contained in:
Jeroen De Meerleer 2019-11-17 01:20:15 +01:00
parent 035e718fd4
commit ab8b091776
WARNING! Although there is a key with this ID in the database it does not verify this commit! This commit is SUSPICIOUS.
GPG Key ID: 28CCCB8F62BFADD6
7 changed files with 351 additions and 117 deletions

View File

@ -28,27 +28,51 @@ use DateTime;
*/ */
class Game class Game
{ {
/** @var Pairing | null */ /**
* The pairing for this games as seen from white's side
*
* @var Pairing | null
*/
public $White; public $White;
/** @var Pairing | null */ /**
* The pairing for this games as seen from blacks's side
*
* @var Pairing | null
*/
public $Black; public $Black;
/** @var GameResult | null */ /**
* The calculated game result
*
* @var GameResult | null
*/
private $CalculatedResult; private $CalculatedResult;
/** @var int */ /**
* The board where this game is held
*
* @var int
*/
public $Board; public $Board;
/**
* Returns fields that were not directly assigned.
* Class Game contains the special field Result containing the result of the game
* @param string $key
* @return Gameresult
*/
public function __get(string $key) public function __get(string $key)
{ {
if ($key == 'Result') { if ($key == 'Result') {
return $this->calculateResult(); return $this->calculateResult();
} }
return null;
} }
/** /**
* Returns the result for the game * Returns the result for the game.
* This method needs to be called from $Game->Result
* *
* @return Gameresult * @return Gameresult
*/ */
@ -86,8 +110,7 @@ class Game
/** /**
* Checks if 2 games are equal * Checks if 2 games are equal
* *
* @param Game $game1 * @param Game $game
* @param Game $game2
* @return bool * @return bool
*/ */
public function equals(Game $game): bool public function equals(Game $game): bool

View File

@ -27,21 +27,45 @@ use JeroenED\Libpairtwo\Enums\Result;
*/ */
class Pairing class Pairing
{ {
/** @var Player | null */ /**
* The player of the pairing. Please note this means the pairing was seen from the point of view of this player
*
* @var Player | null
*/
public $Player; public $Player;
/** @var Player | null */ /**
* The opponent of player
*
* @var Player | null
*/
public $Opponent; public $Opponent;
/** @var Color */ /**
* The color of the player.
* Possible values are Black and White
*
* @var Color
*/
public $Color; public $Color;
/** @var Result */ /**
* The result of the Game. Possible values contain Won, Lost, Draw, Forfait, Bye, etc.
* @var Result
*/
public $Result; public $Result;
/** @var int */ /**
* The round of the game
*
* @var int
*/
public $Round; public $Round;
/** @var int */ /**
* The number of the board where the game was held
*
* @var int
*/
public $Board; public $Board;
} }

View File

@ -28,38 +28,83 @@ use DateTime;
*/ */
class Player class Player
{ {
/** @var string */ /**
* Name of the player
*
* @var string
*/
public $Name; public $Name;
/** @var int[] */ /**
* The player ids for the player. Possible keys are, but not limited to nation and fide
*
* @var int[]
*/
public $Ids; public $Ids;
/** @var int[] */ /**
* The Elos for the player. Possible keys are, but not limited to nation and fide
*
* @var int[]
*/
public $Elos; public $Elos;
/** @var DateTime */ /**
* Birthday of the player
*
* @var DateTime
*/
public $DateOfBirth; public $DateOfBirth;
/** @var float[] */ /**
* Tiebreak points of the player. These values are calculated when Tournament->Ranking is called
*
* @var float[]
*/
public $Tiebreaks = []; public $Tiebreaks = [];
/** @var string */ /**
* The nation the player belongs to. Be noted this does not actually mean this is his main nationality. A player can be signed USCF but may be Italian
*
* @var string
*/
public $Nation; public $Nation;
// TODO: Implement categories // TODO: Implement categories
/** @var string */ /**
* The category the player belongs to
*
* @var string
*/
public $Category; public $Category;
/** @var Title */ /**
* The title of the player. Possible values can be GM, IM, IA, etc.
*
* @var Title
*/
public $Title; public $Title;
/** @var Gender */ /**
* The gender of the player. Possible values contain Male, Female and Neutral
*
* @var Gender
*/
public $Gender; public $Gender;
/** @var Pairing[] */ /**
* The pairings of the player
*
* @var Pairing[]
*/
public $Pairings = []; public $Pairings = [];
/** @var bool|DateTime|int|string[] */ /**
* Binary data that was read out of the pairing file
*
* @var bool|DateTime|int|string[]
*/
private $BinaryData; private $BinaryData;
/** /**
@ -214,6 +259,8 @@ class Player
* *
* WARNING: Calculation currently incorrect. Uses the rule of 400 as temporary solution * WARNING: Calculation currently incorrect. Uses the rule of 400 as temporary solution
* *
* @param $type
* @param $unratedElo
* @return int * @return int
*/ */
public function Performance(string $type, int $unratedElo): float public function Performance(string $type, int $unratedElo): float
@ -278,10 +325,10 @@ class Player
* Sets binary data that is read out the pairing file but is not needed immediately * Sets binary data that is read out the pairing file but is not needed immediately
* *
* @param string $key * @param string $key
* @param bool|int|DateTime|string $Valueey * @param bool|int|DateTime|string $value
*/ */
public function __set(string $key, $Valueey): void public function __set(string $key, $value): void
{ {
$this->BinaryData[$key] = $Valueey; $this->BinaryData[$key] = $value;
} }
} }

View File

@ -2,7 +2,7 @@
/** /**
* Reader Pairtwo6 * Reader Pairtwo6
* *
* Reads out Pairtwo-6 files * Reads out Pairtwo-6 and Pairtwo-5 files
* *
* @author Jeroen De Meerleer <schaak@jeroened.be> * @author Jeroen De Meerleer <schaak@jeroened.be>
* @category Main * @category Main
@ -39,19 +39,30 @@ use DateTime;
*/ */
class Pairtwo6 implements ReaderInterface class Pairtwo6 implements ReaderInterface
{ {
private const PT_DAYFACTOR = 32; const PT_DAYFACTOR = 32;
private const PT_MONTHFACTOR = 16; const PT_MONTHFACTOR = 16;
private const PT_YEARFACTOR = 512; const PT_YEARFACTOR = 512;
private const PT_PASTOFFSET = 117; const PT_PASTOFFSET = 117;
private const CompatibleVersions = ['6.', '5.']; const CompatibleVersions = ['6.', '5.'];
/** @var string */ /**
* Version of Pairtwo this file was created with
*
* @var string
*/
public $Release; public $Release;
/** @var Tournament */ /**
* The tournament
*
* @var Tournament
*/
public $Tournament; public $Tournament;
/** @var bool|DateTime|int|string[] */ /**
* Binary data that was read out of the pairing file
* @var bool|DateTime|int|string[]
*/
private $BinaryData; private $BinaryData;
/** /**
@ -72,15 +83,15 @@ class Pairtwo6 implements ReaderInterface
* Sets binary data that is read out the pairtwo file but is not needed immediately * Sets binary data that is read out the pairtwo file but is not needed immediately
* *
* @param string $key * @param string $key
* @param bool|int|DateTime|string $Valueey * @param bool|int|DateTime|string $value
*/ */
public function __set(string $key, $Valueey): void public function __set(string $key, $value): void
{ {
$this->BinaryData[$key] = $Valueey; $this->BinaryData[$key] = $value;
} }
/** /**
* Reads out $swsfile and returns a Pairtwo6 class object * Actually reads the Swar-File
* *
* @param string $filename * @param string $filename
* @throws IncompatibleReaderException * @throws IncompatibleReaderException

View File

@ -1,6 +1,6 @@
<?php <?php
/** /**
* Reader Swar4 * Reader Swar-4
* *
* Reads out Swar-4 files * Reads out Swar-4 files
* *
@ -9,8 +9,6 @@
* @package Libpairtwo * @package Libpairtwo
* @copyright Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be> * @copyright Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be>
*/ */
namespace JeroenED\Libpairtwo\Readers; namespace JeroenED\Libpairtwo\Readers;
use JeroenED\Libpairtwo\Enums\Color; use JeroenED\Libpairtwo\Enums\Color;
@ -28,24 +26,42 @@ use JeroenED\Libpairtwo\Tournament;
use DateTime; use DateTime;
/** /**
* Class Swar4 * Reader Swar4
* @package JeroenED\Libpairtwo\Readers *
* Reads out Swar-4 files
*
* @author Jeroen De Meerleer <schaak@jeroened.be>
* @category Main
* @package Libpairtwo
* @copyright Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be>
*/ */
class Swar4 implements ReaderInterface class Swar4 implements ReaderInterface
{ {
/** @var Tournament */ /**
public $Tournament; * Version of Pairtwo this file was created with
*
/** @var string */ * @var string
*/
public $Release; public $Release;
/** @var bool|int|DateTime|string[] */ /**
* The tournament
*
* @var Tournament
*/
public $Tournament;
/**
* Binary data that was read out of the pairing file
*
* @var bool|DateTime|int|string[]
*/
private $BinaryData; private $BinaryData;
/** @var array */ /** @var array */
private const CompatibleVersions = ['v4.']; const CompatibleVersions = ['v4.'];
private const Tempos = [ const Tempos = [
[ [
'105 min/40 moves + 15 min. QPF', '105 min/40 moves + 15 min. QPF',
'120 min/40 moves + 15 min. with incr. 30" starting from 40th move', '120 min/40 moves + 15 min. with incr. 30" starting from 40th move',
@ -105,6 +121,8 @@ class Swar4 implements ReaderInterface
]; ];
/** /**
* Actually reads the Swar-File
*
* @param string $filename * @param string $filename
* @throws IncompatibleReaderException * @throws IncompatibleReaderException
*/ */
@ -496,6 +514,15 @@ class Swar4 implements ReaderInterface
} }
/** /**
* Reads data of the filehandle and converts to $type. defaults to $default if given
*
* Possible types for $type are:
* * String (UTF-8 String representation of $data. Default: empty string '')
* * Hex (Capitalized Hex Value of $data. Default: 00)
* * Int (Unsigned Integer value of $data Default: 0)
* * Bool (Boolean representation of $data. Default: false)
* * Date (Date representation of $data. Default: 1902/01/01)
*
* @param string $type * @param string $type
* @param $handle * @param $handle
* @param null $default * @param null $default
@ -580,14 +607,15 @@ class Swar4 implements ReaderInterface
* Sets binary data that is read out the swar file but is not needed immediately * Sets binary data that is read out the swar file but is not needed immediately
* *
* @param string $key * @param string $key
* @param bool|int|DateTime|string $Valueey * @param bool|int|DateTime|string $value
*/ */
public function __set(string $key, $Valueey): void public function __set(string $key, $value): void
{ {
$this->BinaryData[$key] = $Valueey; $this->BinaryData[$key] = $value;
} }
/** /**
* Converts a swar-4 string to a \DateTime object
* @param string $string * @param string $string
* @return DateTime * @return DateTime
*/ */
@ -600,6 +628,9 @@ class Swar4 implements ReaderInterface
} }
} }
/**
* Adds the first tiebreak to the tournament
*/
private function addTiebreaks(): void private function addTiebreaks(): void
{ {
switch ($this->Tournament->System) { switch ($this->Tournament->System) {

View File

@ -55,7 +55,7 @@ class Round
*/ */
public $Pairings = []; public $Pairings = [];
/* /**
* Adds a game to the round * Adds a game to the round
* *
* @param Game $game * @param Game $game

View File

@ -1,8 +1,6 @@
<?php <?php
/** /**
* Class Tournament * The file contains the Tournament class which takes care of almost every element in your tournament
*
* Class for the tournament from the pairing file
* *
* @author Jeroen De Meerleer <schaak@jeroened.be> * @author Jeroen De Meerleer <schaak@jeroened.be>
* @category Main * @category Main
@ -30,79 +28,178 @@ use DateTime;
*/ */
class Tournament class Tournament
{ {
/** @var string */ /**
* Name of the Tournament
*
* @var string
*/
public $Name; public $Name;
/** @var string */ /**
* Organiser of the tournament (eg. Donald J. Trump)
*
*
* @var string
*/
public $Organiser; public $Organiser;
/** @var int */ /**
* Club ID of the tournament organiser (eg. 205001600)
*
* @var string
*/
public $OrganiserClubNo; public $OrganiserClubNo;
/** @var string */ /**
* Club name of the tournament organiser (eg. The White House Chess Club)
*
* @var string
*/
public $OrganiserClub; public $OrganiserClub;
/** @var string */ /**
* Place where the Tounament is held (eg. The Oval Office)
*
* @var string
*/
public $OrganiserPlace; public $OrganiserPlace;
/** @var string */ /**
* The country where the tournament is held
*
* @var string
*/
public $OrganiserCountry; public $OrganiserCountry;
/** @var int */ /**
* Whether or not the tournament is an official tournament and send to the world chess organisation
*
* @var int
*/
public $FideHomol; public $FideHomol;
/** @var DateTime */ /**
* Start date (First round or Players meeting) of the tournament
* @var DateTime
*/
public $StartDate; public $StartDate;
/** @var DateTime */ /**
* End date (Last round or Award Ceremony) of the tournament
*
* @var DateTime
*/
public $EndDate; public $EndDate;
/** @var string[] */ /**
* An Array of the assigned arbiters
*
* @var string[]
*/
public $Arbiters; public $Arbiters;
/** @var int */ /**
* Number of round the tournament has
*
* @var int
*/
public $NoOfRounds; public $NoOfRounds;
/** @var Round[] */ /**
* Round objects of all rounds in the tournament
*
* @var Round[]
*/
public $Rounds = []; public $Rounds = [];
/** @var string */ /**
* The tempo of the tournament (eg. 90 min/40 moves + 30 sec. increment starting from move 1)
* @var string
*/
public $Tempo; public $Tempo;
/** @var int */ /**
* The elo a player gets if he does not have an official elo
*
* @var int
*/
public $NonRatedElo; public $NonRatedElo;
/** @var TournamentSystem */ /**
* The system the tournament (eg. Swiss, Closed, American)
*
* @var TournamentSystem
*/
public $System; public $System;
/** @var string */ /**
* The tempo for the first period of a game in the tournament
*
* @var string
*/
public $FirstPeriod; public $FirstPeriod;
/** @var string */ /**
* The tempo for the second period of a game in the tournament
*
* @var string
*/
public $SecondPeriod; public $SecondPeriod;
/** @var string */ /**
* The federation for which this tournament is held
*
* @var string
*/
public $Federation; public $Federation;
/** @var Player[] */ /**
* All players of the tournament
*
* @var Player[]
*/
public $Players = []; public $Players = [];
/** @var int */ /**
* The year or season the tournament is held or is count for
*
* @var int
*/
public $Year; public $Year;
/** @var Pairing[] */ /**
* All pairings of the tournament
*
* @var Pairing[]
*/
public $Pairings = []; public $Pairings = [];
/** @var Tiebreak[] */ /**
* The tiebreaks for the tournament
*
* @var Tiebreak[]
*/
public $Tiebreaks = []; public $Tiebreaks = [];
/** @var string */ /**
* The elo that priority above all others
*
* @var string
*/
public $PriorityElo = 'Fide'; public $PriorityElo = 'Fide';
/** @var string */ /**
* The Id that has priority above all other
*
* @var string
*/
public $PriorityId = 'Nation'; public $PriorityId = 'Nation';
/** @var bool|DateTime|int|string[] */ /**
* Binary data that was read out of the pairing file
*
* @var bool|DateTime|int|string[]
*/
private $BinaryData = []; private $BinaryData = [];
/** /**
@ -381,8 +478,7 @@ class Tournament
/** /**
* Sort by tiebreak * Sort by tiebreak
* *
* @param Player $a * @param int $key
* @param Player $b
* @return Closure * @return Closure
*/ */
private function sortTiebreak(int $key): Closure private function sortTiebreak(int $key): Closure
@ -402,9 +498,9 @@ class Tournament
* @param Tiebreak $tiebreak * @param Tiebreak $tiebreak
* @param Player $player * @param Player $player
* @param int $tbkey * @param int $tbkey
* @return float | null * @return float
*/ */
private function calculateTiebreak(Tiebreak $tiebreak, Player $player, int $tbkey = 0): ?float private function calculateTiebreak(Tiebreak $tiebreak, Player $player, int $tbkey = 0): float
{ {
switch ($tiebreak) { switch ($tiebreak) {
case Tiebreak::Keizer: case Tiebreak::Keizer:
@ -468,7 +564,7 @@ class Tournament
return $player->Performance($this->PriorityElo, $this->NonRatedElo); return $player->Performance($this->PriorityElo, $this->NonRatedElo);
break; break;
default: default:
return null; return 0;
} }
} }
@ -507,9 +603,9 @@ class Tournament
* Points following keizer system * Points following keizer system
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateKeizer(Player $player): ?float private function calculateKeizer(Player $player): float
{ {
return $player->ScoreAmerican; return $player->ScoreAmerican;
} }
@ -518,9 +614,9 @@ class Tournament
* Number of points * Number of points
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculatePoints(Player $player): ?float private function calculatePoints(Player $player): float
{ {
return $player->calculatePoints(); return $player->calculatePoints();
} }
@ -530,9 +626,9 @@ class Tournament
* Number of won games * Number of won games
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateBaumbach(Player $player): ?float private function calculateBaumbach(Player $player): float
{ {
$totalwins = 0; $totalwins = 0;
foreach ($player->Pairings as $pairing) { foreach ($player->Pairings as $pairing) {
@ -550,9 +646,9 @@ class Tournament
* Number of played games with black * Number of played games with black
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateBlackPlayed(Player $player): ?float private function calculateBlackPlayed(Player $player): float
{ {
$totalwins = 0; $totalwins = 0;
foreach ($player->Pairings as $pairing) { foreach ($player->Pairings as $pairing) {
@ -567,9 +663,9 @@ class Tournament
* Number of won games with black * Number of won games with black
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateBlackWin(Player $player): ?float private function calculateBlackWin(Player $player): float
{ {
$totalwins = 0; $totalwins = 0;
foreach ($player->Pairings as $pairing) { foreach ($player->Pairings as $pairing) {
@ -587,9 +683,9 @@ class Tournament
* @param Player $player * @param Player $player
* @param array $opponents * @param array $opponents
* @param int $key * @param int $key
* @return float | null * @return float
*/ */
private function calculateMutualResult(Player $player, array $opponents, int $key): ?float private function calculateMutualResult(Player $player, array $opponents, int $key): float
{ {
$interestingplayers = $opponents; $interestingplayers = $opponents;
if ($key != 0) { if ($key != 0) {
@ -627,10 +723,11 @@ class Tournament
* The average rating of the opponents * The average rating of the opponents
* *
* @param Player $player * @param Player $player
* @param string $type
* @param int $cut * @param int $cut
* @return float * @return float
*/ */
private function calculateAverageRating(Player $player, string $type, int $cut = 0): ?float private function calculateAverageRating(Player $player, string $type, int $cut = 0): float
{ {
$pairings = $player->Pairings; $pairings = $player->Pairings;
$allratings = []; $allratings = [];
@ -656,10 +753,11 @@ class Tournament
* The average performance of the opponents * The average performance of the opponents
* *
* @param Player $player * @param Player $player
* @param string $type
* @param int $cut * @param int $cut
* @return float | null * @return float
*/ */
private function calculateAveragePerformance(Player $player, string $type, int $cut = 0): ?float private function calculateAveragePerformance(Player $player, string $type, int $cut = 0): float
{ {
$pairings = $player->Pairings; $pairings = $player->Pairings;
$allratings = []; $allratings = [];
@ -682,9 +780,9 @@ class Tournament
* *
* @param Player $player * @param Player $player
* @param int $cut * @param int $cut
* @return float | null * @return float
*/ */
private function calculateKoya(Player $player, int $cut = 50): ?float private function calculateKoya(Player $player, int $cut = 50): float
{ {
$tiebreak = 0; $tiebreak = 0;
foreach ($player->Pairings as $plkey => $plpairing) { foreach ($player->Pairings as $plkey => $plpairing) {
@ -705,9 +803,9 @@ class Tournament
* @param Player $player * @param Player $player
* @param int $cutlowest * @param int $cutlowest
* @param int $cuthighest * @param int $cuthighest
* @return float | null * @return float
*/ */
private function calculateBuchholz(Player $player, int $cutlowest = 0, int $cuthighest = 0): ?float private function calculateBuchholz(Player $player, int $cutlowest = 0, int $cuthighest = 0): float
{ {
$tiebreak = 0; $tiebreak = 0;
$intpairingsWithBye = $player->Pairings; $intpairingsWithBye = $player->Pairings;
@ -750,9 +848,9 @@ class Tournament
* The points of $player's opponents who $player won against, plus half of the points of $player's opponents who $player drew against * The points of $player's opponents who $player won against, plus half of the points of $player's opponents who $player drew against
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateSonneborn(Player $player): ?float private function calculateSonneborn(Player $player): float
{ {
$tiebreak = 0; $tiebreak = 0;
foreach ($player->Pairings as $key => $pairing) { foreach ($player->Pairings as $key => $pairing) {
@ -773,9 +871,9 @@ class Tournament
* *
* @param Player $player * @param Player $player
* @param int[] $points * @param int[] $points
* @return float | null * @return float
*/ */
private function calculateKashdan(Player $player, array $points): ?float private function calculateKashdan(Player $player, array $points): float
{ {
$tiebreak = 0; $tiebreak = 0;
foreach ($player->Pairings as $pairing) { foreach ($player->Pairings as $pairing) {
@ -800,9 +898,9 @@ class Tournament
* Combined score of $player after each round * Combined score of $player after each round
* *
* @param Player $player * @param Player $player
* @return float | null * @return float
*/ */
private function calculateCumulative(Player $player): ?float private function calculateCumulative(Player $player): float
{ {
$tiebreak = 0; $tiebreak = 0;
$score = []; $score = [];
@ -846,11 +944,11 @@ class Tournament
* Sets binary data that is read out the pairing file but is not needed immediately * Sets binary data that is read out the pairing file but is not needed immediately
* *
* @param string $key * @param string $key
* @param bool|int|DateTime|string $Valueeyey * @param bool|int|DateTime|string $value
* @return void * @return void
*/ */
public function __set(string $key, $Valueey): void public function __set(string $key, $value): void
{ {
$this->BinaryData[$key] = $Valueey; $this->BinaryData[$key] = $value;
} }
} }