jja 0.3.1

swiss army knife for chess file formats
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169

# jja

This is `jja`, a command line utility to interact with various chess file
formats. It is still in its very early stages of development. The initial
intention of the author was to convert their opening books which were saved with
ChessBase's proprietary CTG format to the free and open PolyGlot format.
Overtime they intend to add support for other chess file formats (cbh, epd,
pgn, si4, si5 and so on).

# Formats

As of version 0.3.1, `jja` supports reading/querying:

- PolyGlot, aka `bin`
- Arena, aka `abk`
- ChessBase, aka `ctg`
- ChessMaster, aka `obk` (version 1 and 2, w\o,with text notes)

opening book files, whereas it supports writing/converting to:

- PolyGlot, aka `bin`
- Arena, aka `abk`

opening book files.

During opening book conversion, `jja` uses the information provided in various input
opening book formats to come up with a **move weight** which accompanies the move in
the PolyGlot opening file. `jja` also writes some custom numbers in the **learn**
field, such as *NAGs* during `ctg` conversion or *priority* during `abk` conversion.
You may disable this custom usage using `--no-learn` as it may confuse other
software making use of this field.

Note, Arena, aka `abk`, opening book file writing support is only supported from
Chessbase, aka `ctg` books. Use the command line flags `--author`, `--comment`,
`--probability-priority`, `--probability-games`, `--probability-win-percent` to
configure ABK header metadata. Game statistics (minimum number of games/wins, win
percentages for both sides) are managed automatically by `jja`.

In-place editing for Arena opening books is also possible using `-i,
--in-place=SUFFIX` command line option. Conversion from PolyGlot, aka `bin`, and
ChessMaster, aka `obk` opening books to Arena, aka `abk` opening book files is
planned for a future release.

# Install

To compile from source, use `cargo install jja`. This requires the rust
toolchain to be installed.

As an alternative, static builds of `jja` are hosted on
[chesswob.org](https://chesswob.org/jja).  These versions are signed by GnuPG, using
key [D076A377FB27DE70](https://keybase.io/alip/pgp_keys.asc). To install, acquire
the latest version from [chesswob.org](https://chesswob.org/jja), verify the
checksum and the GnuPG signature:

```
$> curl https://keybase.io/alip/pgp_keys.asc | gpg --import
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 13292  100 13292    0     0  13535      0 --:--:-- --:--:-- --:--:-- 26584
gpg: key D076A377FB27DE70: public key "Ali Polatel (Caissa AI) <alip@caissa.ai>" imported
gpg: Total number processed: 1
gpg:               imported: 1
$> for f in jja{,.sha512sum,.sha512sum.asc}; do wget -q https://chesswob.org/jja/${f}; done
$> gpg --verify jja.sha512sum.asc jja.sha512sum
gpg: Signature made Sun Mar 19 20:52:41 2023 CET
gpg:                using RSA key 5DF763560390A149AC6C14C7D076A377FB27DE70
gpg: Good signature from "Ali Polatel (Caissa AI) ...
$> sha512sum -c jja.sha512sum
jja: OK
$> sudo install -m755 jja /usr/local/bin
```

# Usage

Use `jja info` to get brief information about the chess file.
Use `jja find` to search for a position in a chess file.
Use `jja edit` to edit opening book files and convert to PolyGlot files.

jja determines the type of the file using its file extension.  Files with the
extension `.bin` are considered PolyGlot books.  Files with the extension `.ctg` are
considered ChessBase books. Files with the extension `.abk` are considered Arena
books.  Files with extension `.obk` are considered ChessMaster books.

By default if the standard output is a TTY, `jja` will display
information using fancy tables. Use `--porcelain` command line
option to get the output in CSV (comma-separated values) format
instead.

# Demo

<img src="https://dev.exherbo.org/~alip/images/jja-intro.gif"
alt="jja intro"
title="jja intro"
/>

# Jin, Jîyan, Azadî

I've started hacking this on International Women's Day 2023, a day to honor the
achievements of women and advocate for their rights worldwide. As a person of
Kurdish heritage, I am particularly moved by the slogan "Woman, Life, Freedom,"
which has become a symbol of resistance against oppression and a call for
equality. In the spirit of free software and free speech, I strive to
contribute to the creation of a more just and inclusive society, where every
human being is granted the freedom to express themselves and pursue their
dreams. I also honor the memory of Mahsa Amini, whose tragic death reminds us
of the urgent need to fight for women's freedom and safety.

More on Wikipedia, [WikiPedia::Woman,_Life,_Freedom](https://en.wikipedia.org/wiki/Woman,_Life,_Freedom)

# ChangeLog

## 0.3.1

- edit learned to calculate & write ABK header game statistics fields
- edit learned to convert CTG book files to ABK book files
- edit learned --author and --comment to specify metadata for Arena opening books
- edit can edit Arena opening book (abk) files in-place with -i, --in-place=SUFFIX
- support for writing Arena (abk) opening books
- open learned to wrap long ECO opening lines into multiple lines
- find no longer panics on some abk books with entries having invalid uci
- edit takes move priority into account for weight on abk to bin conversion
- match learned --move-selection={best\_move,uniform\_random,weighted\_random} to
  pick move selection algoritm for book moves
- fix castle decoding on polyglot read/query
- fix error return when no positions found in abk, obk and ctg find
- fix promotion handling in ctg edit
- many improvements to ctg find (move coloring & sorting, average statistics)
- new merge command to merge two PolyGlot opening books
- new match command to arrange book matches with random playouts

## 0.3.0

- refactor code to unify various opening book reader interfaces
- support obk version 1 as well as 2 (ChessMaster books with and without notes)
- support for reading obk (ChessMaster) books and converting them to polyglot books
- do not display progress bar if standard output is not a TTY
- support for reading abk (Arena) books and converting them to polyglot books
- new play command can be used to make random playouts using opening books

## 0.2.1

- weight conversion in ctg to polyglot edit can be tuned with
  --nag-weight-{good,mistake,hard,blunder,interesting,dubious,forced}=<WEIGHT>
- edit learned --no-scale to avoid scaling weights globally to fit into 16 bits
- the code is now relatively well documented
- edit --in-place now properly deletes the output temp file on interrupt
- edit filters out moves with zero weights, use -0, --null to preserve them

## 0.2.0

- edit window lists position info (key, epd, legal moves) as comment
- edit no longer silently discards illegal moves
- edit can edit PolyGlot files in-place with -i, --in-place=SUFFIX
- edit can convert CTG opening books into PolyGlot opening books
- default to start position when no --fen or --pgn is given for edit and find
- info prints number of total pages in CTG books

## 0.1.1

- new positions can be added to polyglot files
- many bugs fixed with polyglot edit
- quote command added to print a random chess quote
- open command added to query ECO classification

## 0.1.0

- edit polyglot files, only editing present positions work
- read polyglot files
- read ctg files