Mercurial > public > m209

comparison docs/library.rst @ 64:72e0bda6df40

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