bgneal@57: Library Reference
bgneal@57: =================
bgneal@62: 
bgneal@62: This section of the documentation is aimed at developers who wish to use the
bgneal@62: ``m209`` library as part of their own application. This documentation covers
bgneal@62: the major classes and functions.
bgneal@62: 
bgneal@62: Key lists
bgneal@62: ---------
bgneal@62: 
bgneal@62: Key lists are represented as a named tuple called ``KeyList``.
bgneal@62: 
bgneal@62: .. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
bgneal@62: 
bgneal@62:    As a named tuple, ``KeyList`` has the following attributes:
bgneal@62: 
bgneal@62:    * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
bgneal@62:      the range ``AA`` - ``ZZ``
bgneal@62:    * ``lugs`` - a string representing the drum lug settings; see below
bgneal@62:    * ``pin_list`` - a list of six strings which represent key wheel pin
bgneal@62:      settings; see below
bgneal@62:    * ``letter_check`` - a string representing the letter check used to verify
bgneal@62:      operator settings; if unknown this can be ``None`` or an empty string
bgneal@62:    
bgneal@62: Lug settings string format
bgneal@62: ~~~~~~~~~~~~~~~~~~~~~~~~~~
bgneal@62: 
bgneal@62: Drum lug settings are often conveniently represented as strings consisting of
bgneal@62: at most 27 whitespace-separated pairs of integers separated by dashes. For
bgneal@62: example::
bgneal@62: 
bgneal@62:    lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
bgneal@62: 
bgneal@62: Each integer pair must be in the form ``m-n`` where m & n are integers
bgneal@62: between 0 and 6, inclusive. Each integer represents a lug position where
bgneal@62: 0 is a neutral position, and 1-6 correspond to key wheel positions. If
bgneal@62: m & n are both non-zero, they cannot be equal.
bgneal@62: 
bgneal@62: If a string has less than 27 pairs, it is assumed all remaining bars have both
bgneal@62: lugs in the neutral (0) positions.
bgneal@62: 
bgneal@62: Order of the pairs within the string does not matter.
bgneal@62: 
bgneal@62: To reduce typing and to aid in readability, an alternate shortcut notation is
bgneal@62: supported::
bgneal@62: 
bgneal@62:    lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
bgneal@62: 
bgneal@62: Any pair that is suffixed by ``*k``, where k is a positive integer, means there
bgneal@62: are ``k`` copies of the preceeding lug pair combination. For example, these two
bgneal@62: strings describe identical drum configurations::
bgneal@62: 
bgneal@62:    lugs1 = '2-4 2-4 2-4 0-1 0-1'
bgneal@62:    lugs2 = '2-4*3 0-1*2'
bgneal@62: 
bgneal@62: Key wheel pin settings
bgneal@62: ~~~~~~~~~~~~~~~~~~~~~~
bgneal@62: 
bgneal@62: Key wheel pin settings are represented as iterables of letters whose pins are
bgneal@62: slid to the "effective" position (to the right). Letters not appearing in this
bgneal@62: sequence are considered to be in the "ineffective" position (to the left). If
bgneal@62: None or empty, all pins are set to be ineffective.
bgneal@62: 
bgneal@62: Examples::
bgneal@62: 
bgneal@62:    all_ineffective = ''
bgneal@62:    wheel1 = 'ABDEFHIJMQSUXZ'
bgneal@62:    wheel2 = 'EINPQRTVXZ'
bgneal@62:    wheel3 = 'DEFGIKNOSUX'
bgneal@62:    wheel4 = 'BFGJKRS'
bgneal@62:    wheel5 = 'ABCDFGHIJMPS'
bgneal@62:    wheel6 = 'ADEFHIJKN'
bgneal@62: 
bgneal@62: Key List Example
bgneal@62: ~~~~~~~~~~~~~~~~
bgneal@62: 
bgneal@62: An example of using the :py:class:`m209.keylist.KeyList` is:
bgneal@62: 
bgneal@62: .. code-block:: python
bgneal@62: 
bgneal@62:    from m209.keylist import KeyList
bgneal@62: 
bgneal@62:    key_list1 = KeyList(
bgneal@62:           indicator='AA',
bgneal@62:           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',
bgneal@62:           pin_list=[
bgneal@62:               'FGIKOPRSUVWYZ',
bgneal@62:               'DFGKLMOTUY',
bgneal@62:               'ADEFGIORTUVX',
bgneal@62:               'ACFGHILMRSU',
bgneal@62:               'BCDEFJKLPS',
bgneal@62:               'EFGHIJLMNP'
bgneal@62:           ],
bgneal@62:           letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')