Mercurial > public > m209

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