@chess-fu/pgn-parser/readme.md

Chess PGN parser for 8x8 chess games for import or export standards

# @chess-fu/pgn-parser

## SYNOPSIS

PGN Specification compliant parser for parsing import or export formatted PGN game data.

## STANDARDS COMPLIANCE

The library can handle some unknown characters in move text; however, it generally asserts that the formatting is loosly valid. This library does not validate legality of the moves as that is expected to be handled by another module.

Specifically this library should be compliant with the following specification sections
- 4.2: Tab characters
- 5: Commentary
- 6: Escape mechanism
- 7: Tokens
- 8.1: Tag pair section
- 8.2.2: Movetext move number indications
- 8.2.2.1: Import format move number indications
- 8.2.3: Movetext SAN (Standard Algebraic Notation)
  - The library will also accept LAN (e4-d5) or abbrieviated SAN (ed)
- 8.2.3.1: Square identification
- 8.2.3.2: Piece identification
- 8.2.3.3: Basic SAN move construction
- 8.2.3.4: Disambiguation
- 8.2.3.5: Check and checkmate indication characters
  - The library will also allow `++` to indicate a checkmate
- 8.2.3.8: SAN move suffix annotations
- 8.2.4: Movetext NAG (Numeric Annotation Glyph)
- 8.2.5: Movetext RAV (Recursive Annotation Variation)
- 8.2.6: Game Termination Markers

## INSTALL

```
npm install --save @chess-fu/pgn-parser
```
Not much else to it.

## USAGE

Basic Usage:
```Javascript
  function () {
    const parser = new PgnParser();
    const [game] = parser.parse(`
    [Event "21st European Teams"]
    [Site "Hersonissos GRE"]
    [Date "2017.10.29"]
    [Round "2.9"]
    [White "Adams,Mi"]
    [Black "Tari,A"]
    [Result "1/2-1/2"]
    [ECO "B11"]
    
    1.e4 c6 2.Nf3 d5 3.Nc3 Bg4 4.h3 Bxf3 5.Qxf3 e6 6.g3 Nf6 7.Bg2 Bc5 8.O-O Nbd7
    9.d3 O-O 10.Qe2 Bd4 11.Nd1 dxe4 12.dxe4 Qc7 13.c3 Bc5 14.Ne3 a5 15.Kh2 Rfe8
    16.a4 Bf8 17.Nc4 Nc5 18.Bg5 h6 19.Bxf6 gxf6 20.Qg4+ Bg7 21.Qh5 Nxa4 22.Rxa4 b5
    23.Rxa5 Rxa5 24.Nxa5 Qxa5 25.Qc5 Qc7 26.Ra1 Bf8 27.Qd4 Qd8 28.Qe3 Qd6 29.Qf3 Qe5
    30.h4 Rd8 31.Ra6 Rc8 32.Ra7 Qb8 33.Ra6 Be7 34.Qe3 Kg7 35.Bf3 Qe5 36.Kg2 b4
    37.Be2 bxc3 38.bxc3 Bc5 39.Qd3 Qd6 40.Qxd6 Bxd6 41.f4 Bc5 42.Kf3 Kf8 43.Bc4 Bg1
    44.Ra2 Rb8 45.Ra6 Rc8 46.Ra1 1/2-1/2
    `);
    assert.isObject(game);
    assert.equal(game.headers.length, 10);
    assert.equal(game.history.length, 92);
    assert.equal(game.history[91].result, '1/2-1/2');
  }
```
### `interface HeaderEntry`

- `name: string` The TAG token
- `value: string` The quoted string as an unescaped string value
- `comments: string[]` Comments encountered 

### `class MoveHistory`

- `number: number` The move indicator if one preceded this move 
- `raw: string` The plain-text of the move that was parsed 
- `san: string` The normalized SAN without annotations 
- `from: string` The originating file, rank or both 
- `to: string` The target file, rank, both, or castle 
- `piece: string` The piece that was moved 
- `nag: string` The NAG string, $ followed by a number 
- `rav: MoveHistory[]` The RAV alternative play 
- `check: string` The move check or mate indicator 
- `captured: boolean` True if this was a capture 
- `promotion: string` Promotion type: Q, R, N, or B 
- `annotations: string` Annotations like !, ?, !?, etc 
- `comments: string[]` Comments encountered 
- `result: string` A game result, 1-0, 0-1, 1/2-1/2, or "*"
- `unknown: string` Other non-delimiter characters following the parsed move 

### `class PgnGame`

- `readonly headers: HeaderEntry[]` Returns the structured content found in the headers/tag-pairs.
- `readonly history: MoveHistory[]` Returns the structured move text content.
- `headersMap(): { [key: string]: string }` Returns a key-value map of headers as an object.
- `moves(): MoveHistory[]` Returns the move history excluding any non-move entries.

### `class PgnParser`

- `parse(data: string): PgnGame[]` The main parse API to parse one or more games from text.

**Note:** There are other classes and members available; however, they are not deemed part of the API. Direct use of classes/members not listed above is not recommended.

## LINKS

- Source: https://github.com/chess-fu/chess-modules
- PGN General: https://en.wikipedia.org/wiki/Portable_Game_Notation
- PGN Speccification: https://raw.githubusercontent.com/chess-fu/chess-modules/master/docs/PGN-Standard.txt