Commit | Line | Data |
---|---|---|
7eeb782e AT |
1 | @cindex SGF files in memory |
2 | ||
3 | @dfn{SGF} - Smart Game Format - is a file format which is used for storing | |
4 | game records for a number of different games, among them chess and | |
5 | go. The format is a framework with special adaptions to each game. This | |
6 | is not a description of the file format standard. Too see the exact | |
7 | definition of the file format, see @url{http://www.red-bean.com/sgf/}. | |
8 | ||
9 | GNU Go contains a library to handle go game records in the SGF format in | |
10 | memory and to read and write SGF files. This library - @code{libsgf.a} - | |
11 | is in the @code{sgf} subdirectory. To use the SGF routines, include the | |
12 | file @file{sgftree.h}. | |
13 | ||
14 | Each game record is stored as a tree of @dfn{nodes}, where each node | |
15 | represents a state of the game, often after some move is made. Each node | |
16 | contains zero or more @dfn{properties}, which gives meaning to the | |
17 | node. There can also be a number of @dfn{child nodes} which are | |
18 | different variations of the game tree. The first child node is the main | |
19 | variation. | |
20 | ||
21 | Here is the definition of @code{SGFNode}, and @code{SGFProperty}, the | |
22 | data structures which are used to encode the game tree. | |
23 | ||
24 | @example | |
25 | @group | |
26 | ||
27 | typedef struct SGFProperty_t @{ | |
28 | struct SGFProperty_t *next; | |
29 | short name; | |
30 | char value[1]; | |
31 | @} SGFProperty; | |
32 | ||
33 | @end group | |
34 | @group | |
35 | ||
36 | typedef struct SGFNode_t @{ | |
37 | SGFProperty *props; | |
38 | struct SGFNode_t *parent; | |
39 | struct SGFNode_t *child; | |
40 | struct SGFNode_t *next; | |
41 | @} SGFNode; | |
42 | ||
43 | @end group | |
44 | @end example | |
45 | ||
46 | Each node of the SGF tree is stored in an @code{SGFNode} struct. It has | |
47 | a pointer to a linked list of properties (see below) called | |
48 | @code{props}. It also has a pointer to a linked list of children, where | |
49 | each child is a variation which starts at this node. The variations are | |
50 | linked through the @code{next} pointer and each variation continues | |
51 | through the @code{child} pointer. Each and every node also has a pointer | |
52 | to its parent node (the @code{parent} field), except the top node whose | |
53 | parent pointer is @code{NULL}. | |
54 | ||
55 | An SGF property is encoded in the @code{SGFPoperty} struct. It is linked | |
56 | in a list through the @code{next} field. A property has a @code{name} | |
57 | which is encoded in a short int. Symbolic names of properties can be | |
58 | found in @file{sgf_properties.h}. | |
59 | ||
60 | Some properties also have a value, which could be an integer, a floating | |
61 | point value, a character or a string. These values can be accessed or | |
62 | set through special functions. | |
63 | ||
64 | @section The SGFTree datatype | |
65 | ||
66 | Sometimes we just want to record an ongoing game or something similarly | |
67 | simple and not do any sofisticated tree manipulation. In that case we | |
68 | can use the simplified interface provided by @code{SGFTree} below. | |
69 | ||
70 | @example | |
71 | @group | |
72 | ||
73 | typedef struct SGFTree_t @{ | |
74 | SGFNode *root; | |
75 | SGFNode *lastnode; | |
76 | @} SGFTree; | |
77 | ||
78 | @end group | |
79 | @end example | |
80 | ||
81 | An @code{SGFTree} contains a pointer to the root node of an SGF tree and | |
82 | a pointer to the node that we last accessed. Most of the time this will | |
83 | be the last move of an ongoing game. | |
84 | ||
85 | Most of the functions which manipulate an @code{SGFTree} work exactly | |
86 | like their @code{SGFNode} counterparts, except that they work on the | |
87 | current node of the tree. | |
88 | ||
89 | All the functions below that take arguments @code{tree} and @code{node} | |
90 | will work on: | |
91 | ||
92 | @enumerate | |
93 | @item | |
94 | @code{node} if non-@code{NULL} | |
95 | @item | |
96 | @code{tree->lastnode} if non-@code{NULL} | |
97 | @item | |
98 | The current end of the game tree. | |
99 | @end enumerate | |
100 | in that order. | |
101 |