Mercurial > public > m209
changeset 62:42d7e5410dbd
Started the library docs. Added some docs for KeyList.
author | Brian Neal <bgneal@gmail.com> |
---|---|
date | Thu, 18 Jul 2013 21:09:36 -0500 (2013-07-19) |
parents | 35b5eb90f5ad |
children | a56fca44e0ed |
files | docs/index.rst docs/library.rst |
diffstat | 2 files changed, 94 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/index.rst Fri Jul 12 14:32:51 2013 -0500 +++ b/docs/index.rst Thu Jul 18 21:09:36 2013 -0500 @@ -42,10 +42,11 @@ Contents: .. toctree:: + :maxdepth: 3 + tutorial commandline library - :maxdepth: 2 Requirements
--- a/docs/library.rst Fri Jul 12 14:32:51 2013 -0500 +++ b/docs/library.rst Thu Jul 18 21:09:36 2013 -0500 @@ -1,2 +1,94 @@ Library Reference ================= + +This section of the documentation is aimed at developers who wish to use the +``m209`` library as part of their own application. This documentation covers +the major classes and functions. + +Key lists +--------- + +Key lists are represented as a named tuple called ``KeyList``. + +.. class:: m209.keylist.KeyList(indicator, lugs, pin_list, letter_check) + + As a named tuple, ``KeyList`` has the following attributes: + + * ``indicator`` - the string name for the ``KeyList``; must be 2 letters in + the range ``AA`` - ``ZZ`` + * ``lugs`` - a string representing the drum lug settings; see below + * ``pin_list`` - a list of six strings which represent key wheel pin + settings; see below + * ``letter_check`` - a string representing the letter check used to verify + operator settings; if unknown this can be ``None`` or an empty string + +Lug settings string format +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Drum lug settings are often conveniently represented as strings consisting of +at most 27 whitespace-separated pairs of integers separated by dashes. For +example:: + + lugs = '1-0 2-0 2-0 0-3 0-5 0-5 0-5 0-6 2-4 3-6' + +Each integer pair must be in the form ``m-n`` where m & n are integers +between 0 and 6, inclusive. Each integer represents a lug position where +0 is a neutral position, and 1-6 correspond to key wheel positions. If +m & n are both non-zero, they cannot be equal. + +If a string has less than 27 pairs, it is assumed all remaining bars have both +lugs in the neutral (0) positions. + +Order of the pairs within the string does not matter. + +To reduce typing and to aid in readability, an alternate shortcut notation is +supported:: + + lugs = '1-0 2-0*2 0-3 0-5*3 0-6 2-4 3-6' + +Any pair that is suffixed by ``*k``, where k is a positive integer, means there +are ``k`` copies of the preceeding lug pair combination. For example, these two +strings describe identical drum configurations:: + + lugs1 = '2-4 2-4 2-4 0-1 0-1' + lugs2 = '2-4*3 0-1*2' + +Key wheel pin settings +~~~~~~~~~~~~~~~~~~~~~~ + +Key wheel pin settings are represented as iterables of letters whose pins are +slid to the "effective" position (to the right). Letters not appearing in this +sequence are considered to be in the "ineffective" position (to the left). If +None or empty, all pins are set to be ineffective. + +Examples:: + + all_ineffective = '' + wheel1 = 'ABDEFHIJMQSUXZ' + wheel2 = 'EINPQRTVXZ' + wheel3 = 'DEFGIKNOSUX' + wheel4 = 'BFGJKRS' + wheel5 = 'ABCDFGHIJMPS' + wheel6 = 'ADEFHIJKN' + +Key List Example +~~~~~~~~~~~~~~~~ + +An example of using the :py:class:`m209.keylist.KeyList` is: + +.. code-block:: python + + from m209.keylist import KeyList + + key_list1 = KeyList( + indicator='AA', + 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', + pin_list=[ + 'FGIKOPRSUVWYZ', + 'DFGKLMOTUY', + 'ADEFGIORTUVX', + 'ACFGHILMRSU', + 'BCDEFJKLPS', + 'EFGHIJLMNP' + ], + letter_check='QLRRN TPTFU TRPTN MWQTV JLIJE J')