|
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@62
|
25 Lug settings string format
|
|
bgneal@62
|
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@62
|
74 Key List Example
|
|
bgneal@62
|
75 ~~~~~~~~~~~~~~~~
|
|
bgneal@62
|
76
|
|
bgneal@62
|
77 An example of using the :py: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')
|
