Mercurial > public > m209

comparison docs/m209.rst @ 65:256b3f3e35e9

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add M209 class docs.
author Brian Neal <bgneal@gmail.com>
date Sat, 20 Jul 2013 18:52:45 -0500
parents
children a2647b9fe107
comparison
equal deleted inserted replaced
64:72e0bda6df40 65:256b3f3e35e9
1 M209 Class
2 ==========
3
4 Naturally, the ``m209`` library includes a class that simulates a M-209
5 converter. The :class:`~m209.converter.M209` class allows you to experiment
6 with all moving parts of an M-209, including encrypting and decrypting
7 messages. Keep in mind there is a higher level class, StdProcedure, that
8 encapsulates all the steps of the standard encrypting and decrypting
9 operations, including generating indicators and placing or removing them from
10 messages. However if you need lower-level access or you are inventing your own
11 procedures, you would use the M209 class directly.
12
13 .. class:: m209.converter.M209([lugs=None[, pin_list=None]])
14
15 The ``M209`` class takes the following optional arguments.
16
17 :param lugs: either a lug settings list or string as per :meth:`set_drum_lugs`
18 :param pin_list: a list of six strings each formatted as per :ref:`pin-settings`
19
20 ``M209`` objects support the following methods.
21
22 .. method:: set_pins(n, effective_pins)
23
24 Sets the pin settings on the specified key wheel ``n``.
25
26 :param n: an integer between 0-5, inclusive. Key wheel 0 is the
27 left-most wheel and wheel 5 is the right-most.
28
29 :param effective_pins: an iterable of letters whose pins are slid to
30 the "effective" position (to the right). See :ref:`pin-settings`.
31
32 .. method:: set_all_pins(pin_list)
33
34 Sets all key wheel pins according to the supplied pin list.
35
36 :param pin_list: must either be ``None`` or a 6-element list of strings
37 where each string element is as described in :ref:`pin-settings`.
38 If ``None``, all pins in all key wheels are moved to the ineffective position.
39
40 .. method:: set_drum_lugs(lug_list)
41
42 Sets the drum lugs according to the given ``lug_list`` parameter.
43
44 If ``lug_list`` is ``None`` or empty, all lugs will be placed in neutral
45 positions.
46
47 Otherwise, the ``lug_list`` can either be a list or a string.
48
49 If ``lug_list`` is passed a list, it must be a list of 1 or 2-tuple integers,
50 where each integer is between 0-5, inclusive, and represents a 0-based
51 key wheel position. The list can not be longer than 27 items. Only lug
52 bars with lugs in non-neutral positions need be listed. Lug bars with one
53 lug in a non-neutral position are represented by a 1-tuple. Bars with
54 2 non-netural lugs are represented as a 2-tuple.
55
56 If ``lug_list`` is passed as a string, it is assumed to be in key list
57 format as described in :ref:`lug-settings`.
58
59 Example::
60
61 m = M209()
62 m.set_drum_lugs('1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6')
63
64 # or equivalently
65 m.set_drum_lugs([(0, ), (1, ), (1, ), (2, ), (4, ), (4, ), (4, ), (5, ), (1, 3), (2, 5)])
66
67
68 .. method:: set_key_wheel(n, c)
69
70 Set key wheel ``n`` to the letter ``c``.
71
72 :param n: an integer between 0-5 where key wheel 0 is the leftmost key wheel,
73 and 5 is the rightmost
74 :param c: a 1-letter string valid for key wheel ``n``
75 :raises KeyWheelError: if ``c`` is not valid for wheel ``n``
76
77 .. method:: set_key_wheels(s)
78
79 Set the key wheels from left to right to the six letter string ``s``.
80
81 :raises KeyWheelError: if any letter in ``s`` is not valid for the corresponding key wheel
82
83 .. method:: set_random_key_wheels()
84
85 Sets the six key wheels to random letters.
86
87 :returns: a string of length six representing the new key wheel settings
88
89 .. method:: get_settings()
90
91 Returns the current key settings.
92
93 :returns: a named tuple of ``(lugs, pin_list)`` representing the current
94 key settings. ``lugs`` will be in string format.
95
96 .. method:: encrypt(plaintext[, group=True[, spaces=True]])
97
98 Performs an encrypt operation on the given plaintext and returns the
99 encrypted ciphertext as a string.
100
101 :param plaintext: the text string to encrypt
102 :param group: if ``True``, the ciphertext string will be grouped into 5-letter
103 groups, separated by spaces
104 :param spaces: if ``True``, space characters in the input plaintext will
105 automatically be treated as ``Z`` characters. Otherwise spaces in the
106 plaintext will raise an ``M209Error``.
107 :returns: the ciphertext as a string
108
109 .. method:: decrypt(ciphertext[, spaces=True[, z_sub=True]])
110
111 Performs a decrypt operation on the given ciphertext and returns the
112 decrypted plaintext as a string.
113
114 :param ciphertext: the text string to decyrpt
115 :param spaces: if ``True``, spaces will be allowed in the input ciphertext and
116 ignored. Otherwise space characters will raise an ``M209Error``.
117 This is useful if the input ciphertext is in 5-letter groups, separated
118 by spaces.
119 :param z_sub: if ``True``, ``Z`` characters in the output plaintext will be
120 replaced by space characters, just like an actual M-209.
121 :returns: the plaintext as a string
122
123 Example:
124
125 >>> from m209.converter import M209
126 >>> m = M209()
127 >>> m.set_drum_lugs('1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6')
128 >>> pin_list = [
129 ... 'FGIKOPRSUVWYZ',
130 ... 'DFGKLMOTUY',
131 ... 'ADEFGIORTUVX',
132 ... 'ACFGHILMRSU',
133 ... 'BCDEFJKLPS',
134 ... 'EFGHIJLMNP'
135 ... ]
136 >>> m.set_all_pins(pin_list)
137 >>> m.set_key_wheels('FFEGJP')
138 >>> ct = m.encrypt('THE PIZZA HAS ARRIVED')
139 >>> ct
140 'QBCHU WCCDI YFNCH LOZJY G'
141 >>> m.set_key_wheels('FFEGJP')
142 >>> pt = m.decrypt(ct)
143 >>> pt
144 'THE PI A HAS ARRIVED'