Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/SabakiHQ/sgf
A library for parsing SGF files.
https://github.com/SabakiHQ/sgf
baduk board-game file go parser sgf weiqi
Last synced: 3 months ago
JSON representation
A library for parsing SGF files.
- Host: GitHub
- URL: https://github.com/SabakiHQ/sgf
- Owner: SabakiHQ
- License: mit
- Created: 2018-04-14T19:39:38.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-08-08T01:39:27.000Z (about 1 year ago)
- Last Synced: 2024-05-04T12:20:43.284Z (6 months ago)
- Topics: baduk, board-game, file, go, parser, sgf, weiqi
- Language: JavaScript
- Homepage:
- Size: 288 KB
- Stars: 43
- Watchers: 3
- Forks: 15
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# @sabaki/sgf [](https://travis-ci.org/SabakiHQ/sgf)
A library for parsing SGF files.
## Installation
Use npm to install:
```
$ npm install @sabaki/sgf
```
## Usage
```js
const sgf = require('@sabaki/sgf')
let rootNodes = sgf.parseFile('./game.sgf')
```
`rootNodes` looks like this:
```js
[
{
id: 1,
data: {B: ['dd'], ...},
parentId: null,
children: [
{
id: 2,
data: {W: ['dq']},
parentId: 1,
children: []
},
...
]
},
...
]
```
### Use in the browser
You can use this library in the browser by using a bundler, such as webpack. If
you do, you need to add the following lines to your webpack configuration:
```js
{
...
externals: {
'fs': 'null',
// Add the next lines to disable automatic encoding detection
// and reduce bundle size:
'jschardet': 'null',
'iconv-lite': 'null'
}
}
```
Note that [`parseFile`](#sgfparsefilefilename-options) is not available in the
browser; you have to use [`parse`](#sgfparsecontents-options) instead.
### Integration with [@sabaki/immutable-gametree](https://github.com/SabakiHQ/immutable-gametree)
This library uses the same node structure as
[@sabaki/immutable-gametree](https://github.com/SabakiHQ/immutable-gametree) and
is fully compatible with it. To wrap parsed SGF into game trees, you can write,
for example, something like this:
```js
const sgf = require('@sabaki/sgf')
const GameTree = require('@sabaki/immutable-gametree')
let getId = (id => () => id++)(0)
let rootNodes = sgf.parse(content, {getId})
let gameTrees = rootNodes.map(rootNode => {
return new GameTree({getId, root: rootNode})
})
```
Make sure the id generation function is shared between `@sabaki/sgf` and
`@sabaki/immutable-gametree`.
## Contributors
A big thanks to [@apetresc](https://github.com/apetresc) and
[@fohristiwhirl](https://github.com/fohristiwhirl) for adding decoding and
automatic encoding detection functionalities.
## API
### Node Object
A tree _node_ is represented by an object of the following form:
```js
{
id: ,
data: {
[property]: >
},
parentId: | null,
children: >
}
```
`data` contains node properties which matches their
[SGF property](https://www.red-bean.com/sgf/proplist.html) equivalent.
---
### Basic Functions
#### `*sgf.tokenizeIter(contents)`
- `contents` `` - SGF input
A generator function that yields SGF tokens, objects of the following form:
```js
{
type: ,
value: ,
row: ,
col: ,
pos: ,
progress:
}
```
`type` is one of `"parenthesis"`, `"semicolon"`, `"prop_ident"`,
`"c_value_type"`, `"invalid"`. `row` is the zero-based index of the row where
the token starts, `col` the zero-based index of column where the token starts,
and `pos` denotes the index in `contents` where the token starts. `progress` is
a number between `0` and `1` denoting the percental position of the token.
#### `sgf.tokenize(contents)`
The same as [`sgf.tokenizeIter`](#sgftokenizeitercontents), except this function
will return an array.
#### `*sgf.tokenizeBufferIter(buffer[, options])`
- `buffer` [``](https://nodejs.org/api/buffer.html) - SGF input
- `options` `` _(optional)_
- `encoding` `` _(optional)_
A generator function that yields SGF tokens as in
[`sgf.tokenizeIter()`](#sgftokenizeitercontents). If `encoding` isn't set, we
will automatically choose an encoding. Automatic encoding detection is only
possible if optional dependencies are installed, otherwise UTF-8 will be used.
#### `sgf.tokenizeBuffer(buffer[, options])`
The same as [`sgf.tokenizeBufferIter`](#sgftokenizebufferiterbuffer-options),
except this function will return an array.
#### `sgf.parseTokens(tokens[, options])`
- `tokens` - List of tokens as returned by
[`sgf.tokenize()`](#sgftokenizecontents)
- `options` `` _(optional)_
- `getId` `` _(optional)_
- `dictionary` `` _(optional)_
- `onProgress` `` _(optional)_
- `onNodeCreated` `` _(optional)_
Returns an array of [node objects](#node-object) which represent the root nodes
of each game tree.
`getId` can be specified to control the id generation. It will be called without
any arguments. By default, we will use consecutive integers starting at `0` as
ids.
Pass an object to `dictionary` and it will get filled with references to all the
nodes with their ids as keys.
`onProgress` will be called with an object with the following keys:
- `progress` `` - Between `0` and `1`
`onNodeCreated` will be called when property parsing has been completed for a
node. It will be called with an object with the following keys:
- `node` [``](#node-object)
#### `sgf.parse(contents[, options])`
- `contents` `` - SGF input
- `options` `` _(optional)_ - See
[`sgf.parseTokens()`](#sgfparsetokenstokens-options)
Returns an array of [node objects](#node-object).
#### `sgf.parseBuffer(buffer[, options])`
- `buffer` [``](https://nodejs.org/api/buffer.html) - The buffer
- `options` `` _(optional)_
- `encoding` `` _(optional)_ - See
[`sgf.tokenizeBuffer()`](#sgftokenizebufferbuffer-options)
- `getId` `` _(optional)_ - See
[`sgf.parseTokens()`](#sgfparsetokenstokens-options)
- `dictionary` `` _(optional)_ - See
[`sgf.parseTokens()`](#sgfparsetokenstokens-options)
- `onProgress` `` _(optional)_ - See
[`sgf.parseTokens()`](#sgfparsetokenstokens-options)
Returns an array of [node objects](#node-object).
#### `sgf.parseFile(filename[, options])`
- `filename` `` - Path to an SGF file
- `options` `` _(optional)_ - See
[`sgf.parseBuffer()`](#sgfparsebufferbuffer-options)
Returns an array of [node objects](#node-object). Automatically detects
encoding.
#### `sgf.stringify(nodes[, options])`
- `nodes` [``](#node-object)
- `options` `` _(optional)_
- `linebreak` `` _(optional)_ - Default: `"\n"`
- `indent` `` _(optional)_ - Default: `" "`
Returns an SGF string representing the root nodes `nodes`.
---
### Helper Functions
#### `sgf.escapeString(input)`
- `input` ``
Escapes `\` and `]` characters and returns the new string.
#### `sgf.unescapeString(input)`
- `input` ``
Resolves escaped characters and returns the new string.
#### `sgf.parseVertex(input)`
- `input` ``
Turns an SGF point string into a vertex, an integer array of the form `[x, y]`.
An invalid string will yield `[-1, -1]`.
#### `sgf.stringifyVertex(vertex)`
- `vertex` ``
Turns a vertex into an SGF point string. Returns an empty string if vertex is
invalid.
#### `sgf.parseCompressedVertices(input)`
- `input` ``
Turns an SGF compressed point list into an array of vertices.
#### `sgf.parseDates(input)`
- `input` ``
Parses an SGF date string into an array of date arrays, integer arrays of the
form `[year, month, date]`.
#### `sgf.stringifyDates(dates)`
- `dates` ``
Turns an array of date arrays and returns an SGF date string.