# Portable Game Notation

Portable Game Notation (PGN) désigne un format standard de codage des parties d'échecs.
Il est principalement utilisé pour la retransmission des parties sur internet et dans les bases de données de parties. Il utilise la notation algébrique anglaise abrégée. La plupart des programmes d’échecs la reconnaissent.
Le fichier PGN d’une partie d'échecs est composée de deux parties : la première est une liste d’en-têtes qui décrivent la date et le lieu de la rencontre, les noms des protagonistes, etc. La seconde est constituée des coups joués et d’éventuels commentaires et qui est ponctuée par le résultat.

## Exemple
### Exemple simple

Dans l'exemple suivant, seuls les sept en-têtes obligatoires sont présents. Ils sont séparés de la liste des coups joués par une ligne vide. Il n'y a aucun commentaire associé aux coups joués, et le résultat final termine la partie.

### Exemple plus complexe

Dans cet exemple sont illustrés les variantes et commentaires.

## Syntaxe
### Format d'importation et format d'exportation

On distingue deux types de formats :
* d'exportation : c'est le format rigoureusement conforme à la norme PGN et tel que deux programmes différents produiront pour les mêmes données un résultat parfaitement identique,
* d'importation : c'est le format qui sera toléré en lecture, qui sera plus laxiste que le format d'exportation.
Par exemple, en format d'exportation, les lignes auront une taille maximale de 80 caractères, tandis qu'en importation, les programmes liront des lignes de taille quelconque.

### Jeu de caractères

Le jeu de caractères utilisés par PGN est celui de la norme ISO/CEI 8859-1 codé sur 8 bits avec les restrictions suivantes :
* 0 à 31 : interdits sauf retour à la ligne (10) et TAB (9)
* 32 à 126 : autorisés
* 127 à 159 : sont interdits
* 160 à 191 : utilisation déconseillée
* 192 à 255 : autorisés
Les lignes sont terminées par le caractère ASCII 0x0A (LF, \n), et leur longueur maximale est de 80 caractères.

### En-têtes

Le fichier commence par 7 en-têtes obligatoires :

#### Event

    Le nom du tournoi ou de l'événement.
Exemples :

#### Site

    Le lieu, de préférence utilisant des abréviations standardisées pour les noms de pays, comme celles du comité olympique international.
Exemples :

#### Date

    La date du début de la partie en format AAAA.MM.JJ
Exemples :

#### Round

    Le numéro de la ronde
Exemples :

#### White

    Le joueur blanc (en format "Nom, Prénom")
Exemples :

#### Black

    Le joueur noir

#### Result

    Le résultat (* pour une partie en cours ou un résultat inconnu)
D'autres en-têtes facultatifs sont également possibles :
* WhiteTitle, BlackTitle : titre des joueurs blanc et noir (GM, IM, -),
* WhiteElo, BlackElo : classement Elo des Blancs et des Noirs,
* WhiteUSCF, BlackUSCF : classement Elo américain des Blancs et des Noirs,
* WhiteNA, BlackNA : adresse électronique des joueurs blanc et noir,
* WhiteType, BlackType : human ou program (homme ou machine),
* EventDate : date de début du tournoi,
* EventSponsor : sponsor de l'événement,
* Section : open, Reserver, etc.
* Stage : Preliminary, Semifinal, ... (stade préliminaire, demi-finale, ...)
* Board : échiquier,
* Opening : ouverture,
* Variation : variante,
* SubVariation : sous-variante,
* ECO : code ECO,
* NIC : code NIC,
* Time : heure sous forme HH:MM:SS
* UTCTime : heure UTC
* UTCDate : date UTC
* Timecontrol : de la forme coups/temps (en s): par exemple: 40/7200, 300, 3600+30
* SetUp : 0 pour la position initiale, 1 pour une position différente,
* FEN : la position initiale dans le standard de la notation Forsyth-Edwards
* Termination : résultat
** "abandoned" : abandon
** "adjudication" : décision
** "emergency" : urgence
** "normal"
** "rules infraction" : infraction aux règles
** "time forfeit" : perte au temps
** "unterminated" : partie inachevée
* Annotator : commentateur
* Mode:
** "OTB" (over the board),
** "PM" (paper mail),
** "EM" (electronic mail),
** "ICS" (Internet Chess Server),
** "TC" (general telecommunication).
* PlyCount: nombre de demi-coups

### Commentaires

Des commentaires peuvent apparaître dans les données PGN :
* soit introduits par un point-virgule ';', et le commentaire s'étend alors jusqu'à la fin de la ligne
* soit entouré d'accolades '{' et '}', les accolades ne peuvent être imbriquées.

### Extensions

Si une ligne commence par le caractère « pour cent » (%) dans la première colonne, alors le reste de la ligne est destiné à une extension du format PGN et sera ignoré par les autres implémentations.
L’extension pgn étant faite de texte, les formats textes comme txt sont également possibles.

## SAN

Les coups joués sont décrits par le format SAN (Standard Algebraic Notation), qui se rapproche fort de la notation algébrique abrégée en anglais, toutefois :
* la promotion est indiquée par un signe "=" : e8=Q et non e8Q
* en cas d'ambigüité, on préfère toujours le nom de la colonne à celui de la rangée: Nce4 et non N3e4
* il n'y a pas d'indication de la prise en passant
* le mat est indiqué par #, l'échec par +, il n'y a pas de signe particulier pour l'échec double
Des commentaires habituels tels que "!", "?", "!!", "!?", "?!", et "??" peuvent figurer à la fin du coup en format d'importation. En format d'exportation, ils seront remplacés par les NAG correspondants (voir plus loin)

### NAG

Les NAG (Numeric Annotation Glyph) sont des commentaires standardisés introduits par le caractère $ suivi d'un nombre, en voici la liste :

#### NAG de 0 à 9

Les NAG de 0 à 9 sont un commentaire du coup qui précède immédiatement :
* 0 null annotation : pas d'annotation
* 1 good move (traditional "!") : bon coup
* 2 poor move (traditional "?") : mauvais coup
* 3 very good move (traditional "!!") : coup excellent
* 4 very poor move (traditional "??") : très mauvais coup
* 5 speculative move (traditional "!?") : coup spéculatif
* 6 questionable move (traditional "?!") : coup douteux
* 7 forced move (all others lose quickly) : coup forcé (tous les autres coups perdent rapidement)
* 8 singular move (no reasonable alternatives) : seul coup (pas d'alternative raisonnable)
* 9 worst move : le plus mauvais coup

#### NAG de 10 à 135

Les NAG de 10 à 135 sont des commentaires sur la position :
* 10 drawish position : position égale
* 11 equal chances, quiet position : chances égales, position équilibrée
* 12 equal chances, active position : chances égales, position dynamique
* 13 unclear position : position peu claire
* 14 White has a slight advantage : les Blancs ont un avantage minime
* 15 Black has a slight advantage : les Noirs ont un avantage minime
* 16 White has a moderate advantage : les Blancs ont un avantage modéré
* 17 Black has a moderate advantage : les Noirs ont un avantage modéré
* 18 White has a decisive advantage : les Blancs ont un avantage décisif
* 19 Black has a decisive advantage : les Noirs ont un avantage décisif
* 20 White has a crushing advantage (Black should resign) : les Blancs ont un avantage insurmontable (les Noirs devraient abandonner)
* 21 Black has a crushing advantage (White should resign) : les Noirs ont un avantage insurmontable (les Blancs devraient abandonner)
* 22 White is in zugzwang : les Blancs sont en zugzwang
* 23 Black is in zugzwang : les Noirs sont en zugzwang
* 24 White has a slight space advantage : les Blancs ont un léger avantage spatial
* 25 Black has a slight space advantage : les Noirs ont un léger avantage spatial
* 26 White has a moderate space advantage : les Blancs ont un avantage spatial modéré
* 27 Black has a moderate space advantage : les Noirs ont un avantage spatial modéré
* 28 White has a decisive space advantage : les Blancs ont un avantage spatial décisif
* 29 Black has a decisive space advantage : les Noirs ont un avantage spatial décisif
* 30 White has a slight time (development) advantage : les Blancs ont un léger avantage de développement
* 31 Black has a slight time (development) advantage : les Noirs ont un léger avantage de développement
* 32 White has a moderate time (development) advantage : les Blancs ont un avantage de développement modéré
* 33 Black has a moderate time (development) advantage : les Noirs ont un avantage de développement modéré
* 34 White has a decisive time (development) advantage : les Blancs ont un avantage de développement décisif
* 35 Black has a decisive time (development) advantage : les Noirs ont un avantage de développement décisif
* 36 White has the initiative : les Blancs ont l'initiative
* 37 Black has the initiative : les Noirs ont l'initiative
* 38 White has a lasting initiative : les Blancs ont une initiative durable
* 39 Black has a lasting initiative : les Noirs ont une initiative durable
* 40 White has the attack : les Blancs sont à l'attaque
* 41 Black has the attack : les Noirs sont à l'attaque
* 42 White has insufficient compensation for material deficit : les Blancs ont une compensation insuffisante pour le matériel sacrifié
* 43 Black has insufficient compensation for material deficit : les Noirs ont une compensation insuffisante pour le matériel sacrifié
* 44 White has sufficient compensation for material deficit : les Blancs ont une compensation suffisante pour le matériel sacrifié
* 45 Black has sufficient compensation for material deficit : les Noirs ont une compensation suffisante pour le matériel sacrifié
* 46 White has more than adequate compensation for material deficit : les Blancs ont une nette compensation pour le matériel sacrifié
* 47 Black has more than adequate compensation for material deficit : les Noirs ont une nette compensation pour le matériel sacrifié
* 48 White has a slight center control advantage : Les Blancs ont un léger avantage au centre
* 49 Black has a slight center control advantage : les Noirs ont un léger avantage au centre
* 50 White has a moderate center control advantage : les Blancs ont un avantage modéré au centre
* 51 Black has a moderate center control advantage : les Noirs ont un avantage modéré au centre
* 52 White has a decisive center control advantage : les Blancs ont un avantage décisif au centre
* 53 Black has a decisive center control advantage : les Noirs ont un avantage décisif au centre
* 54 White has a slight kingside control advantage : les Blancs ont un léger avantage à l'aile-roi
* 55 Black has a slight kingside control advantage : les Noirs ont un léger avantage à l'aile-roi
* 56 White has a moderate kingside control advantage : les Blancs ont un avantage modéré à l'aile-roi
* 57 Black has a moderate kingside control advantage : les Noirs ont un avantage modéré à l'aile-roi
* 58 White has a decisive kingside control advantage : les Blancs ont un avantage décisif à l'aile-roi
* 59 Black has a decisive kingside control advantage : les Noirs ont un avantage décisif à l'aile-roi
* 60 White has a slight queenside control advantage : les Blancs ont un léger avantage à l'aile-dame
* 61 Black has a slight queenside control advantage : les Noirs ont un léger avantage à l'aile-dame
* 62 White has a moderate queenside control advantage : les Blancs ont un avantage modéré à l'aile-dame
* 63 Black has a moderate queenside control advantage : les Noirs ont un avantage modéré à l'aile-dame
* 64 White has a decisive queenside control advantage : les Blancs ont un avantage décisif à l'aile-dame
* 65 Black has a decisive queenside control advantage : les Noirs ont un avantage décisif à l'aile-dame
* 66 White has a vulnerable first rank : les Blancs sont vulnérables sur la première rangée
* 67 Black has a vulnerable first rank : les Noirs sont vulnérables sur la première rangée
* 68 White has a well protected first rank : la première rangée des Blancs est bien protégée
* 69 Black has a well protected first rank : la première rangée des Noirs est bien protégée
* 70 White has a poorly protected king : le roi blanc n'est pas bien protégé
* 71 Black has a poorly protected king : le roi noir n'est pas bien protégé
* 72 White has a well protected king : le roi blanc est bien protégé
* 73 Black has a well protected king : le roi noir est bien protégé
* 74 White has a poorly placed king : le roi blanc est mal placé
* 75 Black has a poorly placed king : le roi noir est mal placé
* 76 White has a well placed king : le roi blanc est bien placé
* 77 Black has a well placed king : le roi noir est bien placé
* 78 White has a very weak pawn structure : les Blancs ont une structure de pions très faible
* 79 Black has a very weak pawn structure : les Noirs ont une structure de pions très faible
* 80 White has a moderately weak pawn structure : les Blancs ont une structure de pions relativement faible
* 81 Black has a moderately weak pawn structure : les Noirs ont une structure de pions relativement faible
* 82 White has a moderately strong pawn structure : les Blancs ont une structure de pions assez forte
* 83 Black has a moderately strong pawn structure : les Noirs ont une structure de pions assez forte
* 84 White has a very strong pawn structure : les Blancs ont une structure de pions très solide
* 85 Black has a very strong pawn structure : les Noirs ont une structure de pions très solide
* 86 White has poor knight placement : le(s) cavalier(s) blanc(s) est(sont) mal placé(s)
* 87 Black has poor knight placement : le(s) cavalier(s) noir(s) est(sont) mal placé(s)
* 88 White has good knight placement : le(s) cavalier(s) blanc(s) est(sont) bien placé(s)
* 89 Black has good knight placement : le(s) cavalier(s) noir(s) est(sont) bien placé(s)
* 90 White has poor bishop placement : le(s) fou(s) blanc(s) est(sont) mal placé(s)
* 91 Black has poor bishop placement : le(s) fou(s) noir(s) est(sont) mal placé(s)
* 92 White has good bishop placement : le(s) fou(s) blanc(s) est(sont) bien placé(s)
* 93 Black has good bishop placement : le(s) fou(s) noir(s) est(sont) bien placé(s)
* 94 White has poor rook placement : la(les) tour(s) blanche(s) sont mal placée(s)
* 95 Black has poor rook placement : la(les) tour(s) noire(s) sont mal placée(s)
* 96 White has good rook placement : la(les) tour(s) blanche(s) sont bien placée(s)
* 97 Black has good rook placement : la(les) tour(s) noire(s) sont bien placée(s)
* 98 White has poor queen placement : la dame blanche est mal placée
* 99 Black has poor queen placement : la dame noire est mal placée
* 100 White has good queen placement : la dame blanche est bien placée
* 101 Black has good queen placement : la dame noire est bien placée
* 102 White has poor piece coordination : les pièces blanches sont mal coordonnées
* 103 Black has poor piece coordination : les pièces noires sont mal coordonnées
* 104 White has good piece coordination : les pièces blanches sont bien coordonnées
* 105 Black has good piece coordination : les pièces noires sont bien coordonnées
* 106 White has played the opening very poorly : les Blancs ont très mal joué l'ouverture
* 107 Black has played the opening very poorly : les Noirs ont très mal joué l'ouverture
* 108 White has played the opening poorly : les Blancs ont mal joué l'ouverture
* 109 Black has played the opening poorly : les Noirs ont mal joué l'ouverture
* 110 White has played the opening well : les Blancs ont bien joué l'ouverture
* 111 Black has played the opening well : les Noirs ont bien joué l'ouverture
* 112 White has played the opening very well : les Blancs ont très bien joué l'ouverture
* 113 Black has played the opening very well : les Noirs ont très bien joué l'ouverture
* 114 White has played the middlegame very poorly : les Blancs ont très mal joué le milieu de partie
* 115 Black has played the middlegame very poorly : les Noirs ont très mal joué le milieu de partie
* 116 White has played the middlegame poorly : les Blancs ont mal joué le milieu de partie
* 117 Black has played the middlegame poorly : les Noirs ont mal joué le milieu de partie
* 118 White has played the middlegame well : les Blancs ont bien joué le milieu de partie
* 119 Black has played the middlegame well : les Noirs ont bien joué le milieu de partie
* 120 White has played the middlegame very well : les Blancs ont très bien joué le milieu de partie
* 121 Black has played the middlegame very well : les Noirs ont très bien joué le milieu de partie
* 122 White has played the ending very poorly : les Blancs ont très mal joué la fin de partie
* 123 Black has played the ending very poorly : les Noirs ont très mal joué la fin de partie
* 124 White has played the ending poorly : les Blancs ont mal joué la fin de partie
* 125 Black has played the ending poorly : les Noirs ont mal joué la fin de partie
* 126 White has played the ending well : les Blancs ont bien joué la fin de partie
* 127 Black has played the ending well : les Noirs ont bien joué la fin de partie
* 128 White has played the ending very well : les Blancs ont très bien joué la fin de partie
* 129 Black has played the ending very well : les Noirs ont très bien joué la fin de partie
* 130 White has slight counterplay : les Blancs ont un léger contrejeu
* 131 Black has slight counterplay : les Noirs ont un léger contrejeu
* 132 White has moderate counterplay : les Blancs ont un contrejeu modéré
* 133 Black has moderate counterplay : les Noirs ont un contrejeu modéré
* 134 White has decisive counterplay : les Blancs ont un contrejeu décisif
* 135 Black has decisive counterplay : les Noirs ont un contrejeu décisif

#### NAG de 136 à 139

Ces NAG expriment la pression du temps (Zeitnot).
* 136 White has moderate time control pressure : les Blancs sont pressés par le temps
* 137 Black has moderate time control pressure : les Noirs sont pressés par le temps
* 138 White has severe time control pressure : les Blancs sont sévèrement pressés par le temps
* 139 Black has severe time control pressure : les Noirs sont sévèrement pressés par le temps

## Programmation

Lire un fichier au format PGN se fait selon les étapes suivantes :

### Lecture des en-têtes

Détecter les crochets : [ et ] Le nom est à gauche de la valeur qui elle est entre guillemets : " "

### Détection des coups

Découper les mots.
Pour chacun des mots :
* Soit le mot est un numéro de tour : 1. ; 2. ; ... ; 30. ; ...
* Soit le mot est un coup : voir paragraphe suivant et l'appliquer aux blancs si c'est le premier coup du tour
* Soit le mot est une fin de partie : 1/2-1/2 (nul) ; 1-0 (les blancs gagnent) ; 0-1 (les noirs gagnent) ; * (partie interrompue)

### Analyse d'un coup

Recherche de la pièce :
* Si la première lettre est un O, il s'agit d'un roque, le roi et la tour bougent :
** Si le mot est O-O, c'est un petit roque.
** Si le mot est O-O-O, c'est un grand roque.
** Alors le coup est analysé.
* Sinon, si la première lettre est K, Q, B, N ou R, il s'agit de Roi, Dame, Fou, Cavalier ou Tour :
** On peut alors retirer la première lettre du mot.
* Sinon la pièce concernée est un pion (P).
Recherche du prérequis, pour distinguer deux pièces (ou plus) pouvant effectuer le coup :
* Si la première lettre est de a à h et la seconde un x ou une lettre de a à h
** Prérequis : la pièce doit être dans la colonne désignée par cette lettre
** On peut alors retirer la première lettre du mot.
* Sinon, si la première lettre est un chiffre de 1 à 8 et la seconde un x ou une lettre de a à h
** Prérequis : la pièce doit être dans la ligne désignée par ce chiffre
** On peut alors retirer la première lettre du mot.
* Sinon, si la première lettre est de a à h et si la seconde lettre est un chiffre de 1 à 8 et la troisième un x ou une lettre de a à h
** Prérequis : la pièce doit être dans la case désignée par la lettre et le chiffre
** On peut alors retirer la première et la seconde lettre du mot.
* Sinon, il n'y a pas de prérequis (donc pas d'ambiguité)
Cas d'une attaque, lorsque le déplacement capture une pièce ennemie :
* Si la première lettre est un x, alors il y a capture de la pièce ennemie :
** On peut alors retirer la première lettre du mot.
* Sinon il n'y a pas de capture de pièce ennemie.
Coordonnées du déplacement en lui-même
* Première lettre : colonne (a,b,c,d,e,f,g,h)
* Seconde lettre (un chiffre) : ligne (1,2,3,4,5,6,7,8)
* On peut alors retirer la première et la seconde lettre du mot.
Promotion d'un pion :
* Si la première lettre est un signe =, alors il y a promotion :
** La seconde lettre indique la nouvelle pièce, Q, B, N ou R pour Dame, Fou, Cavalier ou Tour
** On peut alors retirer la première et la seconde lettre du mot.
* Sinon il n'y a pas de promotion.
Mise en échec du roi :
* Si la première lettre est un signe + ou un signe #, alors il y a échec :
** On peut alors retirer la première lettre du mot.
* Sinon il n'y a pas échec.
Le coup est analysé.