Mercurial > public > m209

comparison docs/library.rst @ 62:42d7e5410dbd

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Started the library docs. Added some docs for KeyList.
author Brian Neal <bgneal@gmail.com>
date Thu, 18 Jul 2013 21:09:36 -0500
parents 859dc6624ab7
children a56fca44e0ed
comparison
equal deleted inserted replaced
61:35b5eb90f5ad 62:42d7e5410dbd
1 Library Reference 1 Library Reference
2 ================= 2 =================
3
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
6 the major classes and functions.
7
8 Key lists
9 ---------
10
11 Key lists are represented as a named tuple called ``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 string 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 :py: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')