mbuhidar / retrotype Goto Github PK

1.0 1.0 0.0 548 KB

Library of tools for typing-in, debugging, and converting 1980s magazine type-in games and programs.

License: MIT License

Python 54.07% BASIC 4.75% Assembly 41.18%

retrotype's Introduction

retrotype

Tools for typing-in, debugging, and converting 1980s magazine type-in games and programs for use with Commodore emulators and original hardware.

Installation (requires Python 3.8 or later)

pip3 install retrotype --upgrade

Tool: retrotype_cli

The retrotype_cli tool is a command line debugger and converter for Commodore BASIC programs focused on tokenizing magazine type-in programs popular in the 1980s. Given an input text file containing BASIC source code in magazine type-in format, it checks the typed line entries against line checksums that were printed in the magazines to insure program is bug-free. It outputs both the checksums to the terminal and writes a file with the extension '.chk' for comparison with the checksums printed in the magazine or with a '.ref' file containing the line numbers and checksums from the magazine. Finally, it outputs an executable '.prg' file for direct use with an emulator or original hardware.

Usage

After installation, use retrotype_cli directly from the command line - consult the help for the latest usage:

Note: Currently the only implemented options are for Ahoy C64 programs.

retrotype_cli [-l load_address] [-s source_format] [-w] input_file

positional arguments:
  input_file            Specify the input file name, including path.
                        Note:  Output files will use input file basename

optional arguments:
  -h, --help            show this help message and exit

  -l load_address, --loadaddr load_address
                        Specifies the target BASIC memory address when loading:
                        - 0x0801 - C64 (default)
                        - 0x1001 - VIC20 Unexpanded
                        - 0x0401 - VIC20 +3K
                        - 0x1201 - VIC20 +8K
                        - 0x1201 - VIC20 +16
                        - 0x1201 - VIC20 +24K

  -s source_format, --source source_format
                        Specifies the magazine source for conversion and checksum:
                        ahoy1 - Ahoy magazine (Apr-May 1984)
                        ahoy2 - Ahoy magazine (Jun 1984-Apr 1987) (default)
                        ahoy3 - Ahoy magazine (May 1987-)

  -w, --wip             Work in progress, do not output executable binary file.

As an example for an Ahoy! magazine file:

Input:  basename.bas

Outputs:  basename.prg (tokenized file that can be run on a Commodore computer
                        or on an emulator like VICE)
          basename.chk (list of line numbers and checksums, along with the
                        number of lines, for comparision to checksums printed
                        in the magazine)

Notes for entering programs from Ahoy issues prior to November 1984:

In addition to the special character codes contained in braces in the magazine, Ahoy also used a shorthand convention for specifying a key entry preceeded by either the Shift key or the Commodore key as follows:

Underlined characters - preceed entry with Shift key
Overlined characters - preceed entry with Commodore key

Standard keyboard letters should be typed as follows for these two cases.

{s A}, {s B}, {s *} etc.
{c A}, {c B}, {c *}, etc.

There are a few instances where the old hardware has keys not available on a modern keyboard or are otherwise ambiguous. Those should be entered as follows:

{EP} - British Pound symbol
{UP_ARROW} - up arrow symbol
{LEFT_ARROW} - left arrow symbol
{PI} - Pi symbol
{s RETURN} - shifted return
{s SPACE} - shifted space
{c EP} - Commodore-Bristish Pound symbol
{s UP_ARROW} - shifted up arrow symbol

After the October 1984 issue, the over/under score representation was discontinued as was the use of braces as delineators. After October 1984, the braces were replaced by brackets, however, either can be used while typing in the programs for any issue. The special characters can be typed as listed in the magazines after that issue.

Using the output files

You can run the .prg file generated by the retrotype_cli program by running it with the VICE emulator with the following command (must have VICE installed):

x64sc -basicload program_name.prg &

Of course, you can also run the .prg file on original hardware.

retrotype's People

Contributors

Stargazers

Watchers

retrotype's Issues

Add type hints as part of refactor to object oriented approach

Improve how loose brace errors are handled.

Currently, loose brace errors are detected in the ahoy_lines_list function. The way the error is handled is via return of None, making it inconsistent with the form returned when no error exists.

Add command line flag to turn off open bracket checking

Some program listings don't have equal open vs closed bracket count in all lines. The bracket checking feature prevents checksum determination for these lines. It is not clear if unclosed brackets are a syntax error in Commodore BASIC.

Not yielding a matching checksum value for certain unique lines

For Ahoy November 1985 issue, the game Slither has a few unusual remark lines starting with a colon that are not in the program flow.
For lines that contain text corresponding to BASIC tokens, the checksum values produced by the app do not match those printed in the magazine. Examples below:

999 : * ML DATA *
1099 : * CHARACTER DATA *
3099 : * COORDINATE DATA *

Tried a fix by using a leading colon character to set the remark flag to True to prevent tokenizing the BASIC token text in the line. This didn't fix the issue.

Improve matching delimiter (brackets and braces) algorithm by using a stack and by adding an option flag too disable checking

Refactor method line_number_sequence using next() function.

The next() function returns the next item from the iterator.

Add command line option flag to prevent writing binary .prg file for each run.

Split up ahoy_lines_list function into simpler elements

Improve matching delimiter (brackets and braces) detection with algorithm using stacks and add option flag

Improve return value for check_for_loose_braces() method for flexibility

Method currently returns None or the line number upon detection. Propose to have it return error text as string objects and have the main execution flow handle the program exit. This will provide more flexibility for interfaces besides cli.

Improve test coverage in retrotype_cli.py (see coverage report in description for missing coverage)

Notes (check via command sequence below for now - some day, add to ci):

$ coverage erase
$ coverage run -m pytest
$ coverage report -m

Name                             Stmts   Miss  Cover   Missing
--------------------------------------------------------------
src/retrotype/__init__.py            0      0   100%
src/retrotype/char_maps.py           6      0   100%
src/retrotype/retrotype_cli.py      78     12    85%   132-134, 139-140, 144-150, 156-157, 186-187, 220
src/retrotype/retrotype_lib.py     197      0   100%
tests/retrotype_cli_test.py         38      0   100%
tests/retrotype_lib_test.py         86      0   100%
--------------------------------------------------------------
TOTAL                              405     12    97%