# HG changeset patch # User Brian Neal # Date 1338858351 18000 # Node ID e7b2424704c177608b8c0f969f42541077f8218a # Parent e328fcb6659b8e0d32e13c0563ac9df2914246a7 Document pyenigma.py. Fix bug in keyfile.py. diff -r e328fcb6659b -r e7b2424704c1 enigma/docs/source/pyenigma.rst --- a/enigma/docs/source/pyenigma.rst Mon Jun 04 19:25:50 2012 -0500 +++ b/enigma/docs/source/pyenigma.rst Mon Jun 04 20:05:51 2012 -0500 @@ -1,2 +1,121 @@ pyenigma command-line application ================================= + +Py-Enigma includes a simple application, *pyenigma.py*, to let you perform +Enigma text transformations on the command-line. This allows for quick +experimentation and scripting of operations. + +Getting help +------------ + +To get help and see all the available options, invoke pyenigma.py with the +``--help`` option:: + + $ python pyenigma.py --help + + usage: pyenigma.py [-h] [-k KEY_FILE] [-d DAY] [-r ROTOR [ROTOR ...]] + [-i RING_SETTING [RING_SETTING ...]] + [-p PLUGBOARD [PLUGBOARD ...]] [-u REFLECTOR] [-s START] + [-t TEXT] [-f FILE] [-x REPLACE_CHAR] [-z] [-v] + + Encrypt/decrypt text according to Enigma machine key settings + + optional arguments: + -h, --help show this help message and exit + -k KEY_FILE, --key-file KEY_FILE + path to key file for daily settings + -d DAY, --day DAY use the settings for day DAY when reading key file + -r ROTOR [ROTOR ...], --rotors ROTOR [ROTOR ...] + rotor list ordered from left to right; e.g III IV I + -i RING_SETTING [RING_SETTING ...], --ring-settings RING_SETTING [RING_SETTING ...] + ring setting list from left to right; e.g. A A J + -p PLUGBOARD [PLUGBOARD ...], --plugboard PLUGBOARD [PLUGBOARD ...] + plugboard settings + -u REFLECTOR, --reflector REFLECTOR + reflector name + -s START, --start START + starting position + -t TEXT, --text TEXT text to process + -f FILE, --file FILE input file to process + -x REPLACE_CHAR, --replace-char REPLACE_CHAR + if the input text contains chars not found on the + enigma keyboard, replace with this char [default: X] + -z, --delete-chars if the input text contains chars not found on the + enigma keyboard, delete them from the input + -v, --verbose provide verbose output; include final rotor positions + + Key settings can either be specified by command-line arguments, or read + from a key file. If reading from a key file, the line labeled with the + current day number is used unless the --day argument is provided. + + Text to process can be supplied 3 ways: + + if --text=TEXT is present TEXT is processed + if --file=FILE is present the contents of FILE are processed + otherwise the text is read from standard input + + Examples: + + $ pyenigma.py --key-file=enigma.keys -s XYZ -t HELLOXWORLDX + $ pyenigma.py -r III IV V -i 1 2 3 -p AB CD EF GH IJ KL MN -u B -s XYZ + $ pyenigma.py -r Beta III IV V -i A B C D -p 1/2 3/4 5/6 -u B-Thin -s WXYZ + +There are numerous options, but most are hopefully self-explanatory. There are +two ways to invoke *pyenigma.py*: + +#. Explicitly specifying all initial key settings +#. Using a key file to initialize the Enigma machine + + +Specifying all key settings +--------------------------- + +Here are some examples of specifying all the key settings on the command-line:: + + $ python pyenigma.py --rotors I IV V --ring-settings 5 17 8 \ + --plugboard AV BS CG DL FU HZ IN KM OW RX --reflector C \ + --start=DRX + + $ python pyenigma.py -r I IV V -i 5 17 8 \ + -p AV BS CG DL FU HZ IN KM OW RX -u C -s DRX + +These two invocations create the same settings, the first uses long form +option names, while the second uses short form. + +If no ``--text`` or ``--file`` options are provided, *pyenigma.py* will prompt +for input:: + + $ python pyenigma.py -r I IV V -i 5 17 8 -p AV BS CG DL FU HZ IN KM OW RX -u C -s DRX + --> THIS IS MY SECRET MESSAGE + QAWYWZBVCDEZWOHPVCKFMMFLY + + +Using a key file for settings +----------------------------- + +It is often unwieldy to type so many options on the command-line, so +*pyenigma.py* provides a way to store key settings in a simulated key sheet +file:: + + $ python pyenigma.py --key-file keyfile --start='AAB' --day=29 --text='HERE IS MY MESSAGE' + OCJNFADTCMQIBJLYWW + + +If the ``--day`` option is omitted, the day is determined from the current date. + +The format of the key sheet file is described in :doc:`keyfile`. + + +Verbose output +-------------- + +The ``--verbose`` or ``-v`` option is useful if you wish to view the final rotor +positions and view how many times the rotors stepped while processing your +text:: + + $ python pyenigma.py --key-file keyfile --start='XHC' --day=29 --file msg.txt --verbose + Final rotor positions: YXY + Rotor rotation counts: [1, 16, 412] + Output: + TOSCKAVFTVPONPBJZQPZFBFJXNMCLCZEVDHNEGNPGBWTYTRXJUVOKWBCBFVXIMURRDWNQTHEWTBHMPLKLPLVSJLNLNUOZDCSWAOYQTVFCNLERRWGJPOZMCIMVNVZBYQCVOQEXXFBJKFEEVKTLYNUMRBNHEQMIZXESQBFFSTNXWGMGIHDCAWFDBQRQRJCMOVDVQEEZGIFNPMGAGDVBIIYMZJYDVPIUOFHXSHTZBKCEOZABDPBOMXDZJUNIIMBCLTGZLQCTHAGUNBWMQUNYRJVEIOIHIQWCVJWPXBMVWHMSALPBPTENSLASKQUTJTCDYSCVJSXFANCCRGWAZVKJJOXXJOESZLRQKUEKZNYJNZMYQSAZVNPFRWFFZIWXSNZGNMWMACVOFSAGRJZCLDZEFATXNLVBBUA + diff -r e328fcb6659b -r e7b2424704c1 enigma/keyfile.py --- a/enigma/keyfile.py Mon Jun 04 19:25:50 2012 -0500 +++ b/enigma/keyfile.py Mon Jun 04 20:05:51 2012 -0500 @@ -75,6 +75,7 @@ settings['plugboard_settings'] = ' '.join(cols[-11:-1]) settings['reflector'] = cols[-1] + return settings else: raise KeyFileError('no entry for day %d found' % day) diff -r e328fcb6659b -r e7b2424704c1 enigma/main.py --- a/enigma/main.py Mon Jun 04 19:25:50 2012 -0500 +++ b/enigma/main.py Mon Jun 04 20:05:51 2012 -0500 @@ -31,7 +31,7 @@ Examples: $ %(prog)s --key-file=enigma.keys -s XYZ -t HELLOXWORLDX - $ %(prog)s -r III IV V -i 0 1 2 -p AB CD EF GH IJ KL MN -u B -s XYZ + $ %(prog)s -r III IV V -i 1 2 3 -p AB CD EF GH IJ KL MN -u B -s XYZ $ %(prog)s -r Beta III IV V -i A B C D -p 1/2 3/4 5/6 -u B-Thin -s WXYZ """ @@ -71,7 +71,7 @@ parser.add_argument('-k', '--key-file', help='path to key file for daily settings') parser.add_argument('-d', '--day', type=int, default=None, - help='use the settings for day DAY when reading keysheet') + help='use the settings for day DAY when reading key file') parser.add_argument('-r', '--rotors', nargs='+', metavar='ROTOR', help='rotor list ordered from left to right; e.g III IV I') parser.add_argument('-i', '--ring-settings', nargs='+', @@ -97,7 +97,7 @@ if args.key_file and (args.rotors or args.ring_settings or args.plugboard or args.reflector): - parser.error("Please specify either a keysheet or command-line key " + parser.error("Please specify either a key file or command-line key " "settings, but not both") if args.start is None: