@echecs/pgn 3.0.2 → 3.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +99 -188
  2. package/dist/index.d.ts +5 -0
  3. package/dist/index.js +5 -0
  4. package/dist/index.js.map +1 -1
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -1,7 +1,8 @@
1
1
  # PGN
2
2
 
3
- **PGN** is part of the **ECHECS** project. **PGN** is a parser of the
4
- [PGN specification](http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm).
3
+ `PGN` is a parser that is part of the **ECHECS** project, designed to interpret
4
+ the
5
+ [PGN (Portable Game Notation) specification](http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm).
5
6
 
6
7
  ## Installation
7
8
 
@@ -11,223 +12,133 @@ npm install --save-dev @echecs/pgn
11
12
 
12
13
  ## Usage
13
14
 
14
- `parse(input: string): PGN[]`
15
-
16
- **PGN** format:
15
+ The `parse` function takes a PGN formatted string as input and returns an array
16
+ of parsed PGN objects.
17
17
 
18
+ ```typescript
19
+ parse(input: string): PGN[]
18
20
  ```
21
+
22
+ ### PGN Object Format
23
+
24
+ Here’s the structure of the `PGN` object:
25
+
26
+ #### PGN Object
27
+
28
+ ```json
19
29
  {
20
- meta: Meta,
21
- moves: Moves,
22
- result: 1-0 // 1-0 | 0-1 | 1/2-1/2 | ?
30
+ "meta": Meta,
31
+ "moves": Moves,
32
+ "result": "1-0" // possible values: "1-0", "0-1", "1/2-1/2", "?"
23
33
  }
24
34
  ```
25
35
 
26
- **Meta** format:
36
+ #### Meta Object
27
37
 
28
- ```
38
+ The `meta` object contains metadata about the chess game.
39
+
40
+ ```json
29
41
  {
30
- // Based on the PGN specification at least the following Tags should be available
31
- Event: "the name of the tournament or match event"
32
- Site: "the location of the event"
33
- Date: "the starting date of the game"
34
- Round: "the playing round ordinal of the game"
35
- White: "the player of the white pieces"
36
- Black: "the player of the black pieces"
37
- Result: "the result of the game"
38
- // plus any other additional tags with `key` string
42
+ "Event": "name of the tournament or match event",
43
+ "Site": "location of the event",
44
+ "Date": "starting date of the game",
45
+ "Round": "playing round ordinal of the game",
46
+ "White": "player of the white pieces",
47
+ "Black": "player of the black pieces",
48
+ "Result": "result of the game",
49
+ // Any other additional tags
39
50
  [key]: "string"
40
51
  }
41
52
  ```
42
53
 
43
- **Moves** is an _array_ of:
54
+ #### Moves Array
44
55
 
45
- ```
46
- // move number, white move, black move
47
- [5, Move, Move]
56
+ `Moves` is an array representing the sequence of moves in the game. Each element
57
+ is an array containing the move number, the white move, and the black move.
58
+
59
+ ```json
60
+ [
61
+ moveNumber,
62
+ Move,
63
+ Move
64
+ ]
48
65
  ```
49
66
 
50
- Notice that half move are available for variations of if the last move of the
51
- game was white.
67
+ Note: Half moves are included for variations or in cases where the last move was
68
+ made by white.
52
69
 
53
- **Move** format:
70
+ #### Move Object
54
71
 
55
- ```
72
+ Each move is represented by the following structure:
73
+
74
+ ```json
56
75
  {
57
- annotations: ["!", "$126"], // (optional) all the annotations for the given move
58
- capture: false, // (optional) indicates if the move capture any piece
59
- castling: true, // (optional) indicates if the move was castling
60
- check: false, // (optional) indicates if the move checks the rival king
61
- checkmate: false, // (optional) indicates if it is checkmate
62
- comment: 'Some comment', // (optional) comment of the move
63
- from: 'e', // (optional) Disambiguation of the move
64
- piece: 'K', // (required) P (Pawn) | R (Rook) | N (Knight) | B (Bishop) | Q (Queen) | K (King)
65
- promotion: Piece; // (optional) R (Rook) | N (Knight) | B (Bishop) | Q (Queen)
66
- to: 'g1', // ending square of the piece
67
- variants: [...] // moves following Moves format
76
+ "annotations": ["!", "$126"], // optional, annotations for the move
77
+ "capture": false, // optional, indicates if any piece was captured
78
+ "castling": true, // optional, indicates if the move was castling
79
+ "check": false, // optional, indicates if the move put the rival king in check
80
+ "checkmate": false, // optional, indicates if it is a checkmate
81
+ "comment": "Some comment", // optional, comment about the move
82
+ "from": "e", // optional, disambiguation of the move
83
+ "piece": "K", // required, type of piece (P, R, N, B, Q, K)
84
+ "promotion": "Piece", // optional, promotion piece (R, N, B, Q)
85
+ "to": "g1", // required, ending square of the move
86
+ "variants": [...] // optional, array of moves for variations following Moves format
68
87
  }
69
88
  ```
70
89
 
71
- **Example**
90
+ ### Example
91
+
92
+ Here's a sample usage of the `PGN` parser:
72
93
 
73
94
  ```js
74
95
  import { readFileSync } from 'fs';
75
96
  import parse from '@echecs/pgn';
76
97
 
77
- function readFile(path: string): string {
98
+ function readFile(path) {
78
99
  const filename = require.resolve(path);
79
-
80
100
  return readFileSync(filename, 'utf8');
81
101
  }
82
102
 
83
103
  const pgn = parse(readFile('./games/file.pgn'));
84
- // [
85
- // {
86
- // "meta": {
87
- // "Black": "Cordts, Ingo",
88
- // "BlackElo": "2222",
89
- // "Date": "2000.10.29",
90
- // "ECO": "A56",
91
- // "Result": "0-1",
92
- // "Round": "?",
93
- // "Site": "?",
94
- // "White": "Carlsen, Magnus",
95
- // "WhiteElo": "0",
96
- // },
97
- // "moves": [
98
- // [
99
- // 1,
100
- // {
101
- // "piece": "P",
102
- // "to": "d4",
103
- // },
104
- // {
105
- // "piece": "N",
106
- // "to": "f6",
107
- // },
108
- // ],
109
- // [
110
- // 2,
111
- // {
112
- // "piece": "P",
113
- // "to": "c4",
114
- // },
115
- // {
116
- // "piece": "P",
117
- // "to": "c5",
118
- // },
119
- // ],
120
- // [
121
- // 3,
122
- // {
123
- // "piece": "N",
124
- // "to": "f3",
125
- // },
126
- // {
127
- // "capture": true,
128
- // "from": "c",
129
- // "piece": "P",
130
- // "to": "d4",
131
- // },
132
- // ],
133
- // ...
134
- // [
135
- // 6,
136
- // {
137
- // "capture": true,
138
- // "from": "c",
139
- // "piece": "P",
140
- // "to": "d5",
141
- // },
142
- // {
143
- // "piece": "B",
144
- // "to": "c5",
145
- // },
146
- // ],
147
- // [
148
- // 7,
149
- // {
150
- // "from": "5",
151
- // "piece": "N",
152
- // "to": "c3",
153
- // },
154
- // {
155
- // "castling": true,
156
- // "piece": "K",
157
- // "to": "g8",
158
- // },
159
- // ],
160
- // ...
161
- // [
162
- // 21,
163
- // {
164
- // "capture": true,
165
- // "piece": "N",
166
- // "to": "e4",
167
- // },
168
- // {
169
- // "piece": "B",
170
- // "to": "b7",
171
- // },
172
- // ],
173
- // [
174
- // 22,
175
- // {
176
- // "capture": true,
177
- // "piece": "Q",
178
- // "to": "d7",
179
- // },
180
- // {
181
- // "capture": true,
182
- // "piece": "B",
183
- // "to": "e4",
184
- // },
185
- // ],
186
- // [
187
- // 23,
188
- // {
189
- // "piece": "R",
190
- // "to": "h2",
191
- // },
192
- // {
193
- // "capture": true,
194
- // "piece": "B",
195
- // "to": "d6",
196
- // },
197
- // ],
198
- // ...
199
- // [
200
- // 29,
201
- // {
202
- // "capture": true,
203
- // "check": true,
204
- // "piece": "Q",
205
- // "to": "e6",
206
- // },
207
- // {
208
- // "piece": "K",
209
- // "to": "h8",
210
- // },
211
- // ],
212
- // [
213
- // 30,
214
- // {
215
- // "piece": "Q",
216
- // "to": "e7",
217
- // },
218
- // {
219
- // "piece": "B",
220
- // "to": "c7",
221
- // },
222
- // ],
223
- // ],
224
- // "result": 0,
225
- // },
226
- // ];
104
+
105
+ // Output example of parsed `PGN`
106
+ console.log(pgn);
107
+ /*
108
+ [
109
+ {
110
+ "meta": {
111
+ "Event": "Some Tournament",
112
+ "Site": "Some Location",
113
+ "Date": "2023.10.04",
114
+ "Round": "1",
115
+ "White": "Player1",
116
+ "Black": "Player2",
117
+ "Result": "1-0",
118
+ // additional tags...
119
+ },
120
+ "moves": [
121
+ [
122
+ 1,
123
+ { "piece": "P", "to": "e4" },
124
+ { "piece": "P", "to": "e5" }
125
+ ],
126
+ [
127
+ 2,
128
+ { "piece": "N", "to": "f3" },
129
+ { "piece": "N", "to": "c6" }
130
+ ],
131
+ // more moves...
132
+ ],
133
+ "result": "1-0"
134
+ }
135
+ ];
136
+ */
227
137
  ```
228
138
 
229
- ## Warning
139
+ ## Important Notes
230
140
 
231
- **PGN** does not guarantee PGN games are valid. It does only parse the content.
232
- As part of the **ECHECS** project, it is responsability of **@echecs/game** to
233
- verify the validity of the game.
141
+ - `PGN` is a parser and does not verify the validity of the PGN games. It only
142
+ parses the provided content.
143
+ - For game validation, use **@echecs/game** as it is responsible for verifying
144
+ game correctness as part of the **ECHECS** project.
package/dist/index.d.ts CHANGED
@@ -29,5 +29,10 @@ interface PGN {
29
29
  moves: Moves;
30
30
  result: Result;
31
31
  }
32
+ /**
33
+ * Parse a PGN string into an array of games
34
+ *
35
+ * @param input
36
+ */
32
37
  export default function parse(input: string): PGN[];
33
38
  export {};
package/dist/index.js CHANGED
@@ -11,6 +11,11 @@ function tokenize(input) {
11
11
  }
12
12
  return parser.results[0];
13
13
  }
14
+ /**
15
+ * Parse a PGN string into an array of games
16
+ *
17
+ * @param input
18
+ */
14
19
  export default function parse(input) {
15
20
  const games = input.replace(/[\r\uFEFF]/g, '');
16
21
  return tokenize(games);
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,OAAO,MAAM,eAAe,CAAC;AAwCpC,iDAAiD;AACjD,+DAA+D;AAC/D,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;AAEpC,SAAS,QAAQ,CAAC,KAAa;IAC7B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAEzD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEnB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,2CAA2C,MAAM,CAAC,OAAO,CAAC,MAAM,UAAU,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAU,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,KAAa;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAE/C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,OAAO,MAAM,eAAe,CAAC;AAwCpC,iDAAiD;AACjD,+DAA+D;AAC/D,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;AAEpC,SAAS,QAAQ,CAAC,KAAa;IAC7B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;IAEzD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEnB,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,2CAA2C,MAAM,CAAC,OAAO,CAAC,MAAM,UAAU,CAC3E,CAAC;IACJ,CAAC;IAED,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAU,CAAC;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,KAAa;IACzC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAE/C,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzB,CAAC"}
package/package.json CHANGED
@@ -38,7 +38,7 @@
38
38
  "repository": "mormubis/pgn",
39
39
  "type": "module",
40
40
  "types": "dist/index.d.ts",
41
- "version": "3.0.2",
41
+ "version": "3.0.4",
42
42
  "scripts": {
43
43
  "build": "pnpm run build:grammar && pnpm run build:entry",
44
44
  "build:grammar": "pnpm run grammar:compile",
@@ -51,7 +51,7 @@
51
51
  "lint": "pnpm run lint:style && pnpm run lint:types",
52
52
  "lint:ci": "pnpm run lint:style --max-warnings 0 && pnpm run lint:types",
53
53
  "lint:style": "eslint \"src/**/*.{ts,tsx}\" --fix",
54
- "lint:types": "tsc --noEmit --project tsconfig.build.json",
54
+ "lint:types": "tsc --noEmit --project tsconfig.json",
55
55
  "test": "vitest run",
56
56
  "test:coverage": "pnpm run test --coverage",
57
57
  "test:watch": "pnpm run test --watch"