yucca

Version 1.0, June 10 2012

IT SO HAPPENS in the course of human events that one may find oneself cross-developing an 8-bit BASIC program from a modern development environment.

IN THESE CASES it behoves one to take advantage of the aforementioned modern development environment to increase one's confidence that the cross-developed code is correct.

IT IS FOR THIS PURPOSE that yucca was developed. It is a small Python program which can perform static analysis on 8-bit BASIC programs. Specifically, it can, at present, check that every line number which is a target of a jump is actually present in the program. If it is not, an error message describing the inconsistency is given.

WITH GENERAL APPLICABILITY in mind, yucca recognizes the common forms of jumps available in BASIC (GOTO, GOSUB, ON ... GOTO, ON ... GOSUB, IF ... GOTO, and IF ... THEN followed by a line number) while ignoring any constructs it does not understand. This allows it to be dialect-agnostic, with the unavoidable limitation that it cannot recognize (and thus will not check) computed GOTOs or any dialect-specific command that involves line numbers.

THE BASIC PROGRAM to be analyzed must be present in a textual form. Some emulators allow such text to be pasted in, to simulate entering it at the 8-bit computer's keyboard; other tools are available to convert a tokenized BASIC program to a textual form and back. yucca handles both styles of text file; it can even analyze and manipulate commands in immediate mode, in the case of the listing being a 'session transcript.'

Case Studies

yucca has been successfully used on:

• The editor for Apple Befunge -- this is a 'session transcript';
• The original version of Bubble Escape -- this is the textual conversion of the tokenized program.

Usage

yucca program.bas

Python's fileinput module is used, so the BASIC source can also be piped into yucca, and so forth.

By default, yucca checks that the target of each jump in the program is an existing line number. This includes any jumps that may occur in immediate mode commands (i.e. commands with no line number) given in the text file. If this check fails, further transformations may not be performed on the program. To suppress this check, pass the -L option to yucca.

yucca cannot analyze the validity of any computed line number in a BASIC program which contains computed GOTOs or GOSUBs. To reduce the chance of an computed line number going unnoticed and unanalyzed, yucca's default behavior is to report an error if it finds any computed GOTOs or GOSUBs in the input program. To acknowledge that you are aware that the program contains computed jumps that yucca will not be able to analyze, pass the -C option to have yucca suppress these errors.

The -o option may be given to dump a copy of the program to the standard output. This option is implied by the following two options.

The -I option strips all immediate mode commands from the program before analyzing and outputting it.

The -R option strips all remarks (REM statements) from the program before analyzing and outputting it. Note that this happens before analysis, so that any jumps to lines which contain only a REM will be found and reported.

The -p option causes all program transformations to act only on program lines, not on immediate mode lines. Thus, in combination with -R, REMs on immediate mode lines are not removed. It does not affect -I at all.

The -t option runs yucca through its internal test suite and exits immediately.

TODO

• Show errors in the order they occur in the program.
• Handle duplicate and deleted lines (line number then nothing.)
• Support GO TO form of GOTO found in some BASICs.

Plans

yucca could be easily extended to warn about "code smells" such as a redundant GOTO to the next line, a line containing another GOTO, and so forth.

yucca can dump the input program with (as far as I can tell) total fidelity; it retains case and spacing of all lines, even leading and trailing whitespace.

This facility could be built upon to give yucca the ability to renumber a program, or to supply missing line numbers, or even transform a program with textual labels into one with line numbers.