Beta release of SGFGrove.js

[anazawa]

Hi,

I'm releasing SGFGrove.js, a type-ware SGF parser/composer intended for the browser.

https://github.com/anazawa/sgfgrove

Features:

- no dependencies, while the tests require Node.js
- convert a SGF property value to the appropriate JavaScript type
- extendable, i.e. you can add game-specific properties other than go
- supports old FF[1]-FF[3] formats via the extension
- JSON-aware, i.e. the data structure can be converted into JSON without any modifications
- accepts malformed SGF as possible, generate strict SGF (it's not enough at this time)
- fun to use

This is a beta release, and so implementation details of this module are still
very much in flux. Feedback is welcome!

[quantumf]

Thanks! Excellent readme.md.

[anazawa]

I released the version 0.0.2 (beta).

Changes from 0.0.1:

(diff / changes)

* add .jshintrc
* add .travis.yml
* remove jsdoc.conf
* add "argg" and "jshint" to package.json as "devDependencies"
* SGFGrove.stringify's replacer callback is applied to the given data recursively
* (regexp) use [\s\S] instead of .
* fix FF[4] Compose type bug (the right value was invalid)
* add sgfgrove/collection.js that is an iterator/manimulator for SGF colleciton
* add tests for SGFGrove.collection
* lint everything to satisfy jshint

[README]
* add Travis CI status image
* add more links to SEE ALSO
* update examples

Branches:

* master - https://github.com/anazawa/sgfgrove
* develop - https://github.com/anazawa/sgfgrove/tree/develop

Current state:

* The basic data structure of SGF collection/game tree/property will not be changed any more
* The number of test cases is insufficient

Enjoy!

[anazawa]

Frequently asked questions:

# How can I clone the repository?

Install git and execute the following command:

Code: Select all

$ git clone https://github.com/anazawa/sgfgrove.git

# How can I run the tests?

Install Node.js and run the following command:

Code: Select all

$ npm test

Note that "tape", "argg" and "jshint" packages are required.

...

[anazawa]

(Introduction to toSGF method)

The toSGF method allows you to convert a used-defined object into SGF.
This method is invoked implicitly as a method on the object when you generate a SGF string:

Code: Select all

SGFGrove.stringify([[
    [
        { FF: 4 },
        {
            B: {
                toSGF: function () {
                    return "pd";
                }
            }
        }
    ],
    []
]]);
// => "(;FF[4];B[pd])"

What happened? The B property (black move) of the second node was replaced with the return value of the toSGF method ("pd").

Since B/W property (black/white move) is frequently used in SGF, it's a good idea to define a Move class:

Code: Select all

var Move = function (x, y) {
    this.x = x; // => "p"
    this.y = y; // => "d"
};

Move.prototype.toSGF = function () {
    return this.x + this.y; // => "p"+"d" => "pd"
};

The Move class has "x" and "y" attributes and implements an object method "toSGF".
While the "x" or "y" attribute in the above definition is-a string, you can also define them as a number.
You can use any coordinate system in your JavaScript if you define how to convert your Move object into SGF.

Using the Move class, the above example can be rewritten as follows:

Code: Select all

SGFGrove.stringify([[
    [
        { FF: 4 },
        {
            B: new Move("p", "d")
        }
    ],
    []
]]);
// => "(;FF[4];B[pd])"

You can also add toSGF methods to SGF collection/game tree/node to absract those data.
The toSGF method helps you write reusable code.

[anazawa]

Unfortunately, I have no time to update this module these days.
Thus 0.0.2 (beta) will become 1.0.0 without code changes.

I wrote this module to replace WGo.js's built-in SGF reader in my project.
I think the latest version of SGFGrove.js is stable enough for that purpose.

I you discover a bug in SGFGrove.js, please open a new issue on GitHub.
Patches are very welcome.

Thanks!

[anazawa]

Released the version 1.0.2.

Changes from 1.0.1 (diff):

- add a table of contents to README.md
- add "SGF Property Types" to README.md
- add "Limitations" to README.md
- add scripts/test.psgi
- add sgfgrove/validator.js
- add test/test.stringify.js
- #stringify does not throw an exception anymore but simply ignores properties that have invalid values

Branches:

* master - https://github.com/anazawa/sgfgrove
* develop - https://github.com/anazawa/sgfgrove/tree/develop

New Features:

SGF validator (alpha)

Code: Select all

var collection = SGFGrove.parse("(;FF[4])");
var validator = SGFGrove.validator(...);

validator.validate(collection, {
    onRootPropNotInRootNodeError: function (error) {
        delete this.node[this.propIdent]; // this error is acceptable, so fix it
    },
    onTwoMovesInNodeError: function (error) {
        throw error; // this SGF does not make sense, so reject it
    },
    onGameInfoAlreadySetError: function (error) {
        // do nothing (ignore this error)
    },
    ...
});

Browser Tests

Code: Select all

$ plackup scripts/test.psgi
$ open http://localhost:5000/

Enjoy!