Included gomill framework for SGF and GTP support, and sketched out SGF game-loading code.

2012-04-21 04:27:05 -04:00 · 2012-04-21 04:27:05 -04:00 · 692dc294d6
commit 692dc294d6
parent 700a6a2f32
119 changed files with 27458 additions and 3 deletions
--- a/gomill/docs/boards.rst
+++ b/gomill/docs/boards.rst
@ -0,0 +1,114 @@
+The :mod:`~gomill.boards` module
+--------------------------------
+
+.. module:: gomill.boards
+   :synopsis: Go board representation.
+
+The :mod:`!gomill.boards` module contains Gomill's Go board representation.
+
+Everything in this module works with boards of arbitrarily large sizes.
+
+The implementation is not designed for speed (even as Python code goes), and
+is certainly not appropriate for implementing a playing engine.
+
+The module contains a single class:
+
+
+.. class:: Board(side)
+
+   A :class:`!Board` object represents a legal position on a Go board.
+
+   Instantiate with the board size, as an int >= 1. Only square boards are
+   supported. The board is initially empty.
+
+   Board objects do not maintain any history information.
+
+   Board objects have the following attributes (which should be treated as
+   read-only):
+
+   .. attribute:: side
+
+      The board size.
+
+   .. attribute:: board_points
+
+      A list of *points*, giving all points on the board.
+
+
+The principal :class:`!Board` methods are :meth:`!get` and :meth:`!play`.
+Their *row* and *col* parameters should be ints representing coordinates in
+the :ref:`system <go_related_data_representation>` used for a *point*.
+
+The behaviour of :class:`!Board` methods is unspecified if they are passed
+out-of-range coordinates.
+
+.. method:: Board.get(row, col)
+
+   :rtype: *colour* or ``None``
+
+   Returns the contents of the specified point.
+
+.. method:: Board.play(row, col, colour)
+
+   :rtype: *move*
+
+   Places a stone of the specified *colour* on the specified point.
+
+   Raises :exc:`ValueError` if the point isn't empty.
+
+   Carries out any captures which follow from the placement, including
+   self-captures.
+
+   This method doesn't enforce any ko rule.
+
+   The return value indicates whether, immediately following this move, any
+   point would be forbidden by the :term:`simple ko` rule. If so, that point
+   is returned; otherwise the return value is ``None``.
+
+
+The other :class:`!Board` methods are:
+
+.. method:: Board.is_empty()
+
+   :rtype: bool
+
+   Returns ``True`` if all points on the board are empty.
+
+.. method:: Board.list_occupied_points()
+
+   :rtype: list of pairs (*colour*, *point*)
+
+   Returns a list of all nonempty points, in unspecified order.
+
+.. method:: Board.area_score()
+
+   :rtype: int
+
+   Calculates the area score of a position, assuming that all stones are
+   alive. The result is the number of points controlled (occupied or
+   surrounded) by Black minus the number of points controlled by White.
+
+   Doesn't take any :term:`komi` into account.
+
+.. method:: Board.copy()
+
+   :rtype: :class:`!Board`
+
+   Returns an independent copy of the board.
+
+.. method:: Board.apply_setup(black_points, white_points, empty_points)
+
+   :rtype: bool
+
+   Adds and/or removes stones on arbitrary points. This is intended to support
+   behaviour like |sgf| ``AB``/``AW``/``AE`` properties.
+
+   Each parameter is an iterable of *points*.
+
+   This method applies all the specified additions and removals, then removes
+   any groups with no liberties (so the resulting position is always legal).
+
+   If the same point is specified in more than one list, the order in which
+   the instructions are applied is undefined.
+
+   Returns ``True`` if the position was legal as specified.