====================
GADDAG Documentation
====================

GADDAG is a Python wrapper around cGADDAG_.

A GADDAG data structure provides rapid word lookups for prefixes, suffixes and
substrings, making it ideal for use in applications such as move generation in
word games such as Scrabble_.

GADDAG currently only supports the ASCII alphabet.

.. toctree::
   :hidden:

   index

Installation
============

From PyPI_::

   $ pip install gaddag

Usage
=====

::

   >>> import gaddag
   >>> words = ["foo", "bar", "foobar", "baz"]
   >>> gdg = gaddag.GADDAG(words)
   >>> "foo" in gdg
   True
   >>> "bor" in gdg
   False
   >>> gdg.contains("ba")
   ['bar', 'foobar', 'baz']

Words stored in the GADDAG can be iterated over::

   >>> for word in gdg:
   ...     print(word)
   ...
   foobar
   foo
   baz
   bar

Searching
---------

More advanced searching features are available, such as finding words starting
with, ending with, or containing a given substring::

   >>> gdg.starts_with("foo")
   ['foobar', 'foo']

   >>> gdg.ends_with("bar")
   ['foobar', 'bar']

   >>> gdg.contains("ba")
   ['bar', 'foobar', 'baz']

Low level access
----------------

Low level access is provided, which allows for the GADDAG to be traversed
manually.

The root node of the GADDAG can be accessed::

   >>> root_node = gdg.root
   >>> root_node.edges
   ['a', 'b', 'f', 'o', 'r', 'z']

Edges can be followed::

   >>> a_node = root_node["a"]
   >>> a_node.edges
   ['b']

Following an edge which does not exist throws `KeyError`::

   >>> a_node["f"]
   Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     File ".../gaddag/node.py", line 73, in __getitem__
       raise KeyError(char)
   KeyError: 'f'

Following edges in succession can become tedious, so a method is provided for
ease of use::

   >>> root_node.follow("ab") == root_node["a"]["b"]
   True

The "+" character is the *break* character, which signifies that the start of
the word has been reached and that the subsequent edges (if any) now form the
suffix. A node's letter set shows the characters which will end a word::

   >>> break_node = root_node.follow("ab+")
   >>> break_node.letter_set
   ['r', 'z']

The words "bar" and "baz" have been found.

Using these features, **GADDAG** can be used for more specialised applications,
such as move generation in word games.

API
===

.. autofunction:: gaddag.load

.. autoclass:: gaddag.GADDAG
   :members:

.. autoclass:: gaddag.Node
   :members:

License
=======

Licensed under the MIT License, see LICENSE_.

.. _cGADDAG: https://github.com/jorbas/cGADDAG
.. _Scrabble: https://en.wikipedia.org/wiki/Scrabble
.. _PyPI: https://pypi.python.org/pypi/GADDAG
.. _LICENSE: https://github.com/jorbas/GADDAG/blob/master/LICENSE