@echecs/pgn 3.0.2 → 3.0.9

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 +96 -189
  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,129 @@ 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
+ ```typescript
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
+ ```typescript
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
+ ```typescript
60
+ [moveNumber, Move, Move];
48
61
  ```
49
62
 
50
- Notice that half move are available for variations of if the last move of the
51
- game was white.
63
+ Note: Half moves are included for variations or in cases where the last move was
64
+ made by white.
52
65
 
53
- **Move** format:
66
+ #### Move Object
54
67
 
55
- ```
68
+ Each move is represented by the following structure:
69
+
70
+ ```typescript
56
71
  {
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
72
+ "annotations": ["!", "$126"], // optional, annotations for the move
73
+ "capture": false, // optional, indicates if any piece was captured
74
+ "castling": true, // optional, indicates if the move was castling
75
+ "check": false, // optional, indicates if the move put the rival king in check
76
+ "checkmate": false, // optional, indicates if it is a checkmate
77
+ "comment": "Some comment", // optional, comment about the move
78
+ "from": "e", // optional, disambiguation of the move
79
+ "piece": "K", // required, type of piece (P, R, N, B, Q, K)
80
+ "promotion": "Piece", // optional, promotion piece (R, N, B, Q)
81
+ "to": "g1", // required, ending square of the move
82
+ "variants": [...] // optional, array of moves for variations following Moves format
68
83
  }
69
84
  ```
70
85
 
71
- **Example**
86
+ ### Example
72
87
 
73
- ```js
88
+ Here's a sample usage of the `PGN` parser:
89
+
90
+ ```typescript
74
91
  import { readFileSync } from 'fs';
75
92
  import parse from '@echecs/pgn';
76
93
 
77
- function readFile(path: string): string {
94
+ function readFile(path) {
78
95
  const filename = require.resolve(path);
79
-
80
96
  return readFileSync(filename, 'utf8');
81
97
  }
82
98
 
83
99
  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
- // ];
100
+
101
+ // Output example of parsed `PGN`
102
+ console.log(pgn);
103
+ /*
104
+ [
105
+ {
106
+ "meta": {
107
+ "Event": "Some Tournament",
108
+ "Site": "Some Location",
109
+ "Date": "2023.10.04",
110
+ "Round": "1",
111
+ "White": "Player1",
112
+ "Black": "Player2",
113
+ "Result": "1-0",
114
+ // additional tags...
115
+ },
116
+ "moves": [
117
+ [
118
+ 1,
119
+ { "piece": "P", "to": "e4" },
120
+ { "piece": "P", "to": "e5" }
121
+ ],
122
+ [
123
+ 2,
124
+ { "piece": "N", "to": "f3" },
125
+ { "piece": "N", "to": "c6" }
126
+ ],
127
+ // more moves...
128
+ ],
129
+ "result": "1-0"
130
+ }
131
+ ];
132
+ */
227
133
  ```
228
134
 
229
- ## Warning
135
+ ## Important Notes
230
136
 
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.
137
+ - `PGN` is a parser and does not verify the validity of the PGN games. It only
138
+ parses the provided content.
139
+ - For game validation, use **@echecs/game** as it is responsible for verifying
140
+ 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.9",
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"