Merge branch 'task/phpdoc' into develop

This commit is contained in:
Jeroen De Meerleer 2019-11-17 01:22:18 +01:00
commit 283b69ca30
Signed by: JeroenED
GPG Key ID: 28CCCB8F62BFADD6
9 changed files with 353 additions and 118 deletions

View File

@ -5,6 +5,7 @@
* MAJOR CHANGE: Getter and setter methods have been removed. (Please see [0d8a325](https://github.com/JeroenED/libpairtwo/commit/0d8a325eb501b775830f68fa6f600f9f4ca5588c) for more info)
* CHANGE: Some fields has been renamed to match coding guideline (Please see [1ab96fa](https://github.com/JeroenED/libpairtwo/commit/1ab96fa04782c1b0f2b6bb9d1bac8397a74ab38e) for more info)
* CHANGE: Logo has been redesigned
* CHANGE: Phpdoc is used again for docs generation
* REMOVED: `Tiebreak::American` and all its uses were removed (Please see [a6015ae](https://github.com/JeroenED/libpairtwo/commit/a6015ae8169f0973f4937605d0f807aacc233630) for more info)
## v1.2 (Release: 28-sep-2019)

View File

@ -16,7 +16,7 @@ view-coverage: ## Shows the code coverage report
open build/coverage/index.html
api: ## Generates api-docs
VERSIONTAG=$(VERSION) doxygen
phpdoc -d ./src -t ./doc/api
dist: ## Generates distribution
cp dist/composer* res/

View File

@ -28,27 +28,51 @@ use DateTime;
*/
class Game
{
/** @var Pairing | null */
/**
* The pairing for this games as seen from white's side
*
* @var Pairing | null
*/
public $White;
/** @var Pairing | null */
/**
* The pairing for this games as seen from blacks's side
*
* @var Pairing | null
*/
public $Black;
/** @var GameResult | null */
/**
* The calculated game result
*
* @var GameResult | null
*/
private $CalculatedResult;
/** @var int */
/**
* The board where this game is held
*
* @var int
*/
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)
{
if ($key == 'Result') {
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
*/
@ -86,8 +110,7 @@ class Game
/**
* Checks if 2 games are equal
*
* @param Game $game1
* @param Game $game2
* @param Game $game
* @return bool
*/
public function equals(Game $game): bool

View File

@ -27,21 +27,45 @@ use JeroenED\Libpairtwo\Enums\Result;
*/
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;
/** @var Player | null */
/**
* The opponent of player
*
* @var Player | null
*/
public $Opponent;
/** @var Color */
/**
* The color of the player.
* Possible values are Black and White
*
* @var Color
*/
public $Color;
/** @var Result */
/**
* The result of the Game. Possible values contain Won, Lost, Draw, Forfait, Bye, etc.
* @var Result
*/
public $Result;
/** @var int */
/**
* The round of the game
*
* @var int
*/
public $Round;
/** @var int */
/**
* The number of the board where the game was held
*
* @var int
*/
public $Board;
}

View File

@ -28,38 +28,83 @@ use DateTime;
*/
class Player
{
/** @var string */
/**
* Name of the player
*
* @var string
*/
public $Name;
/** @var int[] */
/**
* The player ids for the player. Possible keys are, but not limited to nation and fide
*
* @var int[]
*/
public $Ids;
/** @var int[] */
/**
* The Elos for the player. Possible keys are, but not limited to nation and fide
*
* @var int[]
*/
public $Elos;
/** @var DateTime */
/**
* Birthday of the player
*
* @var DateTime
*/
public $DateOfBirth;
/** @var float[] */
/**
* Tiebreak points of the player. These values are calculated when Tournament->Ranking is called
*
* @var float[]
*/
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;
// TODO: Implement categories
/** @var string */
/**
* The category the player belongs to
*
* @var string
*/
public $Category;
/** @var Title */
/**
* The title of the player. Possible values can be GM, IM, IA, etc.
*
* @var Title
*/
public $Title;
/** @var Gender */
/**
* The gender of the player. Possible values contain Male, Female and Neutral
*
* @var Gender
*/
public $Gender;
/** @var Pairing[] */
/**
* The pairings of the player
*
* @var Pairing[]
*/
public $Pairings = [];
/** @var bool|DateTime|int|string[] */
/**
* Binary data that was read out of the pairing file
*
* @var bool|DateTime|int|string[]
*/
private $BinaryData;
/**
@ -214,6 +259,8 @@ class Player
*
* WARNING: Calculation currently incorrect. Uses the rule of 400 as temporary solution
*
* @param $type
* @param $unratedElo
* @return int
*/
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
*
* @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
*
* Reads out Pairtwo-6 files
* Reads out Pairtwo-6 and Pairtwo-5 files
*
* @author Jeroen De Meerleer <schaak@jeroened.be>
* @category Main
@ -39,19 +39,30 @@ use DateTime;
*/
class Pairtwo6 implements ReaderInterface
{
private const PT_DAYFACTOR = 32;
private const PT_MONTHFACTOR = 16;
private const PT_YEARFACTOR = 512;
private const PT_PASTOFFSET = 117;
private const CompatibleVersions = ['6.', '5.'];
const PT_DAYFACTOR = 32;
const PT_MONTHFACTOR = 16;
const PT_YEARFACTOR = 512;
const PT_PASTOFFSET = 117;
const CompatibleVersions = ['6.', '5.'];
/** @var string */
/**
* Version of Pairtwo this file was created with
*
* @var string
*/
public $Release;
/** @var Tournament */
/**
* The tournament
*
* @var 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;
/**
@ -72,15 +83,15 @@ class Pairtwo6 implements ReaderInterface
* Sets binary data that is read out the pairtwo file but is not needed immediately
*
* @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
* @throws IncompatibleReaderException

View File

@ -1,6 +1,6 @@
<?php
/**
* Reader Swar4
* Reader Swar-4
*
* Reads out Swar-4 files
*
@ -9,8 +9,6 @@
* @package Libpairtwo
* @copyright Copyright (c) 2018-2019 Jeroen De Meerleer <schaak@jeroened.be>
*/
namespace JeroenED\Libpairtwo\Readers;
use JeroenED\Libpairtwo\Enums\Color;
@ -28,24 +26,42 @@ use JeroenED\Libpairtwo\Tournament;
use DateTime;
/**
* Class Swar4
* @package JeroenED\Libpairtwo\Readers
* Reader Swar4
*
* 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
{
/** @var Tournament */
public $Tournament;
/** @var string */
/**
* Version of Pairtwo this file was created with
*
* @var string
*/
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;
/** @var array */
private const CompatibleVersions = ['v4.'];
const CompatibleVersions = ['v4.'];
private const Tempos = [
const Tempos = [
[
'105 min/40 moves + 15 min. QPF',
'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
* @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 $handle
* @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
*
* @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
* @return DateTime
*/
@ -600,6 +628,9 @@ class Swar4 implements ReaderInterface
}
}
/**
* Adds the first tiebreak to the tournament
*/
private function addTiebreaks(): void
{
switch ($this->Tournament->System) {

View File

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

View File

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