Key lists
---------

Key lists are represented as a named tuple called ``KeyList``.

.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)

   As a named tuple, ``KeyList`` has the following attributes:

   * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
     the range ``AA`` - ``ZZ``
   * ``lugs`` - a string representing the drum lug settings; see below
   * ``pin_list`` - a list of six strings which represent key wheel pin
     settings; see below
   * ``letter_check`` - a string representing the letter check used to verify
     operator settings; if unknown this can be ``None`` or an empty string
   
Lug settings format
~~~~~~~~~~~~~~~~~~~

Drum lug settings are often conveniently represented as strings consisting of
at most 27 whitespace-separated pairs of integers separated by dashes. For
example::

   lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'

Each integer pair must be in the form ``m-n`` where m & n are integers
between 0 and 6, inclusive. Each integer represents a lug position where
0 is a neutral position, and 1-6 correspond to key wheel positions. If
m & n are both non-zero, they cannot be equal.

If a string has less than 27 pairs, it is assumed all remaining bars have both
lugs in the neutral (0) positions.

Order of the pairs within the string does not matter.

To reduce typing and to aid in readability, an alternate shortcut notation is
supported::

   lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'

Any pair that is suffixed by ``*k``, where k is a positive integer, means there
are ``k`` copies of the preceeding lug pair combination. For example, these two
strings describe identical drum configurations::

   lugs1 = '2-4 2-4 2-4 0-1 0-1'
   lugs2 = '2-4*3 0-1*2'

Key wheel pin settings
~~~~~~~~~~~~~~~~~~~~~~

Key wheel pin settings are represented as iterables of letters whose pins are
slid to the "effective" position (to the right). Letters not appearing in this
sequence are considered to be in the "ineffective" position (to the left). If
None or empty, all pins are set to be ineffective.

Examples::

   all_ineffective = ''
   wheel1 = 'ABDEFHIJMQSUXZ'
   wheel2 = 'EINPQRTVXZ'
   wheel3 = 'DEFGIKNOSUX'
   wheel4 = 'BFGJKRS'
   wheel5 = 'ABCDFGHIJMPS'
   wheel6 = 'ADEFHIJKN'

Key list example
~~~~~~~~~~~~~~~~

An example of using the :class:`~m209.keylist.KeyList` is:

.. code-block:: python

   from m209.keylist import KeyList

   key_list1 = KeyList(
          indicator='AA',
          lugs='0-4 0-5*4 0-6*6 1-0*5 1-2 1-5*4 3-0*3 3-4 3-6 5-6',
          pin_list=[
              'FGIKOPRSUVWYZ',
              'DFGKLMOTUY',
              'ADEFGIORTUVX',
              'ACFGHILMRSU',
              'BCDEFJKLPS',
              'EFGHIJLMNP'
          ],
          letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')

Key list file I/O
~~~~~~~~~~~~~~~~~

Key lists can be stored in files in config file ("INI") style format using
functions found in the ``m209.keylist.config`` module.

.. function:: m209.keylist.config.read_key_list(fname[, indicator=None])

    Reads key list information from the file given by ``fname``.

    Searches the config file for the key list with the given indicator. If
    found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if
    not found.

    If ``indicator`` is ``None``, a key list is chosen from the file at random.

.. function:: m209.keylist.config.write(fname, key_lists)

    Writes the key lists to the file named ``fname`` in config file format.

    ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects.

Key list file format
++++++++++++++++++++

An example key list file in config file format is presented below. The label
for each section of the file is the key list indicator.

::

   [CA]
   lugs = 0-5*5 0-6*2 1-0*7 1-2 1-3*3 1-6 2-0 3-0*3 3-5*2 3-6 4-5
   wheel1 = ABCDFGHJLOPRVWYZ
   wheel2 = BCDEIJKPQSUVX
   wheel3 = ACDGLNQRSTUV
   wheel4 = FGHIJNQRSU
   wheel5 = DEIJOQS
   wheel6 = BCDEILMNOP
   check = RGPRO RTYOO TWYSN GXTPF PNWIH P

   [CD]
   lugs = 0-4*4 0-5 1-0*7 1-2*2 1-4*3 2-0*2 2-4*2 2-6*2 3-0*4
   wheel1 = AEFHIKMPQRSUVZ
   wheel2 = ABFGHINORSUVZ
   wheel3 = BDEHJKLMNOQRSU
   wheel4 = CDEFGHJKMRU
   wheel5 = FGHIJOQS
   wheel6 = EGIJKLP
   check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H

Generating key lists
~~~~~~~~~~~~~~~~~~~~

The ``m209`` library contains a function to pseudo-randomly generate a key list
that is based on the procedure described in the 1944 M-209 manual.

.. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS])

   The only required parameter is ``indicator``, the two-letter indicator for
   the key list.

   If successful, a :class:`~m209.keylist.KeyList` object is returned.

   If a :class:`~m209.keylist.KeyList` could not be generated
   a ``KeyListGenError`` exception is raised.

   The algorithm is heuristic-based and makes random decisions based upon the
   1944 procedure. The actual procedure is loosely specified in the manual, and
   much is left up to the human operator. It is possible that the algorithm
   cannot find a solution to meet the key list requirements specified in the
   manual, in which case it simply tries again up to some set of limits. These
   limits can be tweaked using the optional parameters to the algorithm. If no
   solution is found after exhausting the limits, a ``KeyListGenError`` is
   raised.

   The optional parameters are:

   * ``lug_selection`` - a list of 6 integers used to drive the lug settings
     portion of the algorithm. If not supplied, a list of 6 integers is chosen
     from data tables that appear in the 1944 manual. For more information on
     the requirements for these integers, see the manual.

   * ``max_lug_attempts`` - the maximum number of times to attempt to create
     lug settings before giving up

   * ``max_pin_attempts`` - the maximum number of times to attempt to generate
     key wheel pin settings before giving up