Mercurial > public > m209

annotate docs/library.rst @ 63:a56fca44e0ed

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added more key list docs.
author Brian Neal <bgneal@gmail.com>
date Fri, 19 Jul 2013 20:29:45 -0500
parents 42d7e5410dbd
children 72e0bda6df40
rev   line source
bgneal@57 1 Library Reference
bgneal@57 2 =================
bgneal@62 3
bgneal@62 4 This section of the documentation is aimed at developers who wish to use the
bgneal@62 5 ``m209`` library as part of their own application. This documentation covers
bgneal@62 6 the major classes and functions.
bgneal@62 7
bgneal@62 8 Key lists
bgneal@62 9 ---------
bgneal@62 10
bgneal@62 11 Key lists are represented as a named tuple called ``KeyList``.
bgneal@62 12
bgneal@62 13 .. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check)
bgneal@62 14
bgneal@62 15 As a named tuple, ``KeyList`` has the following attributes:
bgneal@62 16
bgneal@62 17 * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in
bgneal@62 18 the range ``AA`` - ``ZZ``
bgneal@62 19 * ``lugs`` - a string representing the drum lug settings; see below
bgneal@62 20 * ``pin_list`` - a list of six strings which represent key wheel pin
bgneal@62 21 settings; see below
bgneal@62 22 * ``letter_check`` - a string representing the letter check used to verify
bgneal@62 23 operator settings; if unknown this can be ``None`` or an empty string
bgneal@62 24
bgneal@63 25 Lug settings format
bgneal@63 26 ~~~~~~~~~~~~~~~~~~~
bgneal@62 27
bgneal@62 28 Drum lug settings are often conveniently represented as strings consisting of
bgneal@62 29 at most 27 whitespace-separated pairs of integers separated by dashes. For
bgneal@62 30 example::
bgneal@62 31
bgneal@62 32 lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6'
bgneal@62 33
bgneal@62 34 Each integer pair must be in the form ``m-n`` where m & n are integers
bgneal@62 35 between 0 and 6, inclusive. Each integer represents a lug position where
bgneal@62 36 0 is a neutral position, and 1-6 correspond to key wheel positions. If
bgneal@62 37 m & n are both non-zero, they cannot be equal.
bgneal@62 38
bgneal@62 39 If a string has less than 27 pairs, it is assumed all remaining bars have both
bgneal@62 40 lugs in the neutral (0) positions.
bgneal@62 41
bgneal@62 42 Order of the pairs within the string does not matter.
bgneal@62 43
bgneal@62 44 To reduce typing and to aid in readability, an alternate shortcut notation is
bgneal@62 45 supported::
bgneal@62 46
bgneal@62 47 lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6'
bgneal@62 48
bgneal@62 49 Any pair that is suffixed by ``*k``, where k is a positive integer, means there
bgneal@62 50 are ``k`` copies of the preceeding lug pair combination. For example, these two
bgneal@62 51 strings describe identical drum configurations::
bgneal@62 52
bgneal@62 53 lugs1 = '2-4 2-4 2-4 0-1 0-1'
bgneal@62 54 lugs2 = '2-4*3 0-1*2'
bgneal@62 55
bgneal@62 56 Key wheel pin settings
bgneal@62 57 ~~~~~~~~~~~~~~~~~~~~~~
bgneal@62 58
bgneal@62 59 Key wheel pin settings are represented as iterables of letters whose pins are
bgneal@62 60 slid to the "effective" position (to the right). Letters not appearing in this
bgneal@62 61 sequence are considered to be in the "ineffective" position (to the left). If
bgneal@62 62 None or empty, all pins are set to be ineffective.
bgneal@62 63
bgneal@62 64 Examples::
bgneal@62 65
bgneal@62 66 all_ineffective = ''
bgneal@62 67 wheel1 = 'ABDEFHIJMQSUXZ'
bgneal@62 68 wheel2 = 'EINPQRTVXZ'
bgneal@62 69 wheel3 = 'DEFGIKNOSUX'
bgneal@62 70 wheel4 = 'BFGJKRS'
bgneal@62 71 wheel5 = 'ABCDFGHIJMPS'
bgneal@62 72 wheel6 = 'ADEFHIJKN'
bgneal@62 73
bgneal@63 74 Key list example
bgneal@62 75 ~~~~~~~~~~~~~~~~
bgneal@62 76
bgneal@63 77 An example of using the :class:`~m209.keylist.KeyList` is:
bgneal@62 78
bgneal@62 79 .. code-block:: python
bgneal@62 80
bgneal@62 81 from m209.keylist import KeyList
bgneal@62 82
bgneal@62 83 key_list1 = KeyList(
bgneal@62 84 indicator='AA',
bgneal@62 85 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 86 pin_list=[
bgneal@62 87 'FGIKOPRSUVWYZ',
bgneal@62 88 'DFGKLMOTUY',
bgneal@62 89 'ADEFGIORTUVX',
bgneal@62 90 'ACFGHILMRSU',
bgneal@62 91 'BCDEFJKLPS',
bgneal@62 92 'EFGHIJLMNP'
bgneal@62 93 ],
bgneal@62 94 letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')
bgneal@63 95
bgneal@63 96 Key list file I/O
bgneal@63 97 ~~~~~~~~~~~~~~~~~
bgneal@63 98
bgneal@63 99 Key lists can be stored in files in config file ("INI") style format using
bgneal@63 100 functions found in the ``m209.keylist.config`` module.
bgneal@63 101
bgneal@63 102 .. function:: m209.keylist.config.read_key_list(fname[, indicator=None])
bgneal@63 103
bgneal@63 104 Reads key list information from the file given by ``fname``.
bgneal@63 105
bgneal@63 106 Searches the config file for the key list with the given indicator. If
bgneal@63 107 found, returns a :class:`~m209.keylist.KeyList` object. Returns ``None`` if
bgneal@63 108 not found.
bgneal@63 109
bgneal@63 110 If ``indicator`` is ``None``, a key list is chosen from the file at random.
bgneal@63 111
bgneal@63 112 .. function:: m209.keylist.config.write(fname, key_lists)
bgneal@63 113
bgneal@63 114 Writes the key lists to the file named ``fname`` in config file format.
bgneal@63 115
bgneal@63 116 ``key_lists`` must be an iterable of :class:`~m209.keylist.KeyList` objects.
bgneal@63 117
bgneal@63 118 Key list file format
bgneal@63 119 ++++++++++++++++++++
bgneal@63 120
bgneal@63 121 An example key list file in config file format is presented below. The label
bgneal@63 122 for each section of the file is the key list indicator.
bgneal@63 123
bgneal@63 124 ::
bgneal@63 125
bgneal@63 126 [CA]
bgneal@63 127 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
bgneal@63 128 wheel1 = ABCDFGHJLOPRVWYZ
bgneal@63 129 wheel2 = BCDEIJKPQSUVX
bgneal@63 130 wheel3 = ACDGLNQRSTUV
bgneal@63 131 wheel4 = FGHIJNQRSU
bgneal@63 132 wheel5 = DEIJOQS
bgneal@63 133 wheel6 = BCDEILMNOP
bgneal@63 134 check = RGPRO RTYOO TWYSN GXTPF PNWIH P
bgneal@63 135
bgneal@63 136 [CD]
bgneal@63 137 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
bgneal@63 138 wheel1 = AEFHIKMPQRSUVZ
bgneal@63 139 wheel2 = ABFGHINORSUVZ
bgneal@63 140 wheel3 = BDEHJKLMNOQRSU
bgneal@63 141 wheel4 = CDEFGHJKMRU
bgneal@63 142 wheel5 = FGHIJOQS
bgneal@63 143 wheel6 = EGIJKLP
bgneal@63 144 check = ZRLWL YRMIZ RZOPN UWMVZ DVGPM H
bgneal@63 145
bgneal@63 146 Generating key lists
bgneal@63 147 ~~~~~~~~~~~~~~~~~~~~
bgneal@63 148
bgneal@63 149 The ``m209`` library contains a function to pseudo-randomly generate a key list
bgneal@63 150 that is based on the procedure described in the 1944 M-209 manual.
bgneal@63 151
bgneal@63 152 .. function:: m209.keylist.generate.generate_key_list(indicator[, lug_selection=None, max_lug_attempts=MAX_LUG_ATTEMPTS, max_pin_attempts=MAX_PIN_ATTEMPTS])
bgneal@63 153
bgneal@63 154 The only required parameter is ``indicator``, the two-letter indicator for
bgneal@63 155 the key list.
bgneal@63 156
bgneal@63 157 If successful, a :class:`~m209.keylist.KeyList` object is returned.
bgneal@63 158
bgneal@63 159 If a :class:`~m209.keylist.KeyList` could not be generated
bgneal@63 160 a ``KeyListGenError`` exception is raised.
bgneal@63 161
bgneal@63 162 The algorithm is heuristic-based and makes random decisions based upon the
bgneal@63 163 1944 procedure. The actual procedure is loosely specified in the manual, and
bgneal@63 164 much is left up to the human operator. It is possible that the algorithm
bgneal@63 165 cannot find a solution to meet the key list requirements specified in the
bgneal@63 166 manual, in which case it simply tries again up to some set of limits. These
bgneal@63 167 limits can be tweaked using the optional parameters to the algorithm. If no
bgneal@63 168 solution is found after exhausting the limits, a ``KeyListGenError`` is
bgneal@63 169 raised.
bgneal@63 170
bgneal@63 171 The optional parameters are:
bgneal@63 172
bgneal@63 173 * ``lug_selection`` - a list of 6 integers used to drive the lug settings
bgneal@63 174 portion of the algorithm. If not supplied, a list of 6 integers is chosen
bgneal@63 175 from data tables that appear in the 1944 manual. For more information on
bgneal@63 176 the requirements for these integers, see the manual.
bgneal@63 177
bgneal@63 178 * ``max_lug_attempts`` - the maximum number of times to attempt to create
bgneal@63 179 lug settings before giving up
bgneal@63 180
bgneal@63 181 * ``max_pin_attempts`` - the maximum number of times to attempt to generate
bgneal@63 182 key wheel pin settings before giving up
bgneal@63 183