Because I like printed manuals, I’ve written a short manual for superBASIC. It’s available in print on Amazon.com^•, currently, for $5.99. It makes a useful reference if you use superBASIC; I use it all the time. It’s also available as a free ebook on most of the usual sites.¹

I’ve also made some changes to how code generation works. I have changed the format of the DATASET macro, or dynamic constant. I’ve renamed %DATASETS! to !DATASETS%. I did this because I can envision having string constants as well, and I wanted to use the same format I use for variables, that is, ending in a dollar sign. So now a variable always begins with a percent, and a constant always begins with an exclamation.

The only visible change to the generated code is that I’ve standardized how blank lines get added around blocks and remarks. This greatly improves the readability of the resulting old-school BASIC.

Also, remarks no longer break on forward slashes, as these are common in URLs, which are common in the top comments I put in any program I write.

Internally, I’ve completely rewritten block generation. It generates the same code as before, but it is much easier to manage and view block types. This means that SWITCH/CASE is now the same kind of block as LOOP and IF/ELSE. LOOPs and IF/ELSE can be embedded in CASEs. Even SWITCHes can be embedded in CASEs.

This should make it easier to add an ELSEIF to IF/ELSE when needed, and to add a SWITCH ON to generate ON x GOTO statements. I probably won’t be adding any sort of FOR/NEXT loop because this turns out to be unnecessary on the Color Computer. All of the FOR loops that I’ve been wanting to BREAK out of are in subroutines, and the BREAK would have returned immediately from the subroutine. It turns out that returning from a subroutine clears out the FOR stack.

One of the first programs I wrote in superBASIC, a very simple reversi.

I always felt weird about jumping out of a FOR loop, leaving the poor stack perpetually waiting for a NEXT that will never come. Now that I know how Microsoft’s BASIC implemented its stack, I feel a lot better about it.

There’s also a --version command-line switch if you want to check the version on your system. The current version as I write this is 1.0.0. The third number is for bug fixes or minor internal changes. The second number is for feature additions, such as ELSEIF, or if I decide to add a SWITCH INDEX to create ON X GOTOs.

I’ve added a new feature to data sets. You can now provide a counter name to data sets, which will become a dynamic constant that contains the number of elements you provide to the data set.

Note that !foreground% does not contain the number of data items, but the number of elements provided to the DATA macro. I’ve found this useful because I often provide multiple data items per line to, for example, create a menu item. The line might contain the name of the item, the program to run, and whether or not the program is a BASIC program or a binary program. What matters to me later is not that there are, say, 15 elements in the resulting DATA statements but that I entered 5 menu items.

Over on Facebook, Jay Searle asked,

Why did you use overly complicated variable types? It seems that %variable% could just be variable or %variable, and %variable$ could just be variable$ or $variable? I'm interested in your thinking and how you came to this conclusion. I'm not bashing you, just genuinely interested.

This is a really good question. Now that I’ve converted to recursive block generation and merged SWITCH/CASE into it, the weakest part of superBASIC is the variable conversion. I use the current format because providing both a start and an end character vastly reduces the chances of a non-variable getting munged up. The entire code for detecting variables is:

Text-to-image filter for tables, because Smashwords forbids tables.

If you’re familiar with regular expressions, you will notice that nowhere in that code does it make any attempt to parse BASIC to determine what is and is not a variable. If you have %code% or %code$ inside of a string, it will get converted to something like CO or CO$. Anywhere something that looks like a long variable—a percent sign, a letter, some text, numbers, and/or underscore, and then a percent sign or a dollar sign—appears, it will get converted, regardless of whether it truly is a variable.

I have yet to have this be a problem, but that doesn’t mean I like it.

Even worse is that this harms the readability of the code. While %code$ is more readable than CO$, code$ would be even more readable. I would very much prefer to use a variable format of if location$ = "utility" then drive%=1 else drive%=0 instead of if %location$ = "utility" then %drive%=1 else %drive%=0. But the BASIC of these old computers is a very freeform language, and the former runs the risk of collisions with non-variable text unless I have the script actually parse the old-school BASIC. That would vastly increase the complexity of the script, and thus the number of bugs hidden within it.

On the plus side, the current variable name format is such that if you have a working program that uses the current variable naming system, and I ever devise a better system, the Perl script to convert existing programs will be trivial. This is a rare case where waiting longer to implement a real solution does not make it more difficult to convert from the quick-and-dirty solution.

If you’re interested in how I generated tables for the ebook version of the manual, I wrote about the text-to-image conversion script at Text to image filter for Smashwords conversions.