Metadata-Version: 2.1
Name: nimgame
Version: 0.1.2
Summary: Play the Game of Nim, interactively or using the API
Keywords: nim,game,heap,coin
Author: netcreator
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Dist: valid8
Project-URL: Home, http://bitbucket.org/netcreator/nimgame

About
=====

This package implements the game called Nim. The game can be played
interactively in the CLI or using a web browser as a GUI. By using the API, it
can also be embedded in other applications and played from other GUI.


Game Rules:
===========

For the general description of the Nim and similar games, see the
`Wikipedia page`_.

This game is played by 2 palyers (the computer can be a player).
There are coins arranged in heaps.
There may be any number of heaps and any number of coins in a heap.

Players take turns. In each turn, a player takes coins from a heap (only 1
heap). It must be at least 1 coin. There is no upper limit (but the heap size).

There are 2 types of the game:

- the "normal" game is where the player, who takes the last coin, wins
- the "misère_" game is where the player, who has to take the last coin, loses


Usage:
======

After instantiating the Nim class, you need to get the heaps set up. The
starting heaps then can analysed and the starting player set. If it is the
Computer, it automatically does the 1st move. Then the Player is to do the next
move, then the Computer moves, and so on. When no more coins left, the game
ends.

Example::

    import nimgame
    nim = nimgame.Nim(error_rate=10)  # Request 10% error rate from the Computer
    nim.setup_heaps()  # Create heaps randomly
    nim.set_start(myturn=True)  # Indicate that the Player wants to start
    nim.do_move(nim.Move('b', 4))  # From heap 'B', remove 4 coins
    ...
    if nim.game_end():
        exit(0)


Available objects in the package
================================

While different objects are defined in the source at different levels (e.g. the
Nim class in the source/core.py module), the necessary ones are made available
at the package level, i.e. after importing nimgame, the nimgame.Nim refers to
that class.

:Nim: The main class of the game
:play_CLI: A function that interactively plays the game in CLI
:Move: namedtuple with "heapdesig" and "removecount" fields for defining a move.
    "heapdesig" can be an int (heap numbers start from zero), or a letter (case
    insensitive). E.g. 1 is the sames as "B" or "b".
:ErrorRate: namedtuple with "Computer" and "Player" fields for defining the
    required error rates in % for the players when both of them are simulated
:HeapCoinRange: namedtuple with "min" and "max" fields for defining numbers of
    heaps and heap sizes for automatic heap creation


Package content
===============

:source/core: It provides the Nim class and its public methods
:source/calculations: A mixin of the Nim class with calculation methods
:modules in "playing": Functions to play the game
:modules in "tests": They play several games automatically and gather statistics
:play: It provides some interactions for executing automatic runs or interactive
    games. This module is called too, when
    
    - the package itself is called (see the "__main__.py" module), e.g.
      :code: python -m nimgame
    
    - the nimgame.exe (in Scripts) is executed. NB, the python Scripts dir
      is usually in the execution path, i.e. the nimgame.exe should be
      available from anywhere in the CLI prompt.


.. _Wikipedia page: https://en.wikipedia.org/wiki/Nim
.. _misère: https://en.wikipedia.org/wiki/Mis%C3%A8re#Mis%C3%A8re_game


.. Modules
.. =======

..  .. autosummary::
   :toctree: modules
    
   dummy
   .. why the hell this fails on importing source ??
   .. when running "sphinx-autogen docs/index.rst" in the nimgame dir, it says: no module named source.core

.. Indices and tables
.. ==================

.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`

