| 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 | |