Improving PBASIC: Request for Comments

[Greg Ross]

Finally, I have posted the preprocessor in the white papers area.

Sorry it took so long. My computer crashed just before the new year, and I had to reconstruct a lot of what I had done -- losing a lot of momentum in the process.

Here is the description I posted along with the program:

PRECIS:

A BASIC Stamp Preprocessor which simplifies coding for the BASIC Stamp 2 SX/E/P by providing an include file capability, and enabling structured programming constructs.



INTRODUCTION:
Here is the preprocessor I promised way back when. Sorry it took so long. (My computer crashed back at the end of December, and I had to reconstruct a lot of my work.)

I wrote this program to make programming our robot easier. It started when we first got the robot controller with the BASIC Stamp2 SX, and I needed to define the program data area identically in all the project programs. The original incarnation was limited to inserting an include file, and had a command line interface.

Last year, I added the graphical user interface, and this year, the structured programming capabilities.



INSTALLATION:

Copy the program to your hard disk. (That's all!)



USE:
Run the program. It brings up a Windows Explorer like interface. From there, navigate to where your robot programs are stored (or where you want them to be.)

Assuming you already have a program file, find the file you want to edit (or preprocess) in the file list, and press Ctrl-P to preprocess the file or Ctrl-E to launch the BASIC Stamp Editor to edit the file.

To create and edit a new file from the GUI, type the name of the file you want created into the file name edit box, and press Ctrl-E.

The GUI also allows you to rename (Ctrl-N) and delete (Ctrl-D) files.



DIRECTIVE SYNTAX:

All directives appear within curly braces.

All directives are case insensitive. (i.e. $Include and $INCLUDE are equivalent.)

The $Stamp directive is required by the Stamp editor to be within a comment (i.e. preceded by an apostrophe.) All other directives MAY be preceded by apostrophes, although it is not recommended because of the fact that if you forget to preprocess your program, StampW will accept it as syntactically correct, but the program will not run correctly when downloaded to your robot.

The left brace introducing a preprocessor directive must be the first non-blank character on the line (other than an optional label and the optional apostrophe), and the directive (along with its parameters, if any) must be alone inside the braces. Comments may follow the closing brace.



PREPROCESSOR DIRECTIVES:

{$Stamp processor, file2, file3, ..., file8}
Tells the BASIC Stamp editor the version of the Stamp processor the program will run on, and the program files that belong to the project. (The processor parameter is ignored by the preprocessor. Consult the StampW documentation for the $STAMP directive syntax.) The preprocessor uses the file list to determine which files to preprocess.


{$Include file_name}
Inserts file_name (after preprocessing it) into the program file being processed.


{$StampPPDate}
Causes the preprocessor to insert a DATA statement containing the date and time the file was preprocessed (StampPPDate DATA 24, "Mon Mar 19 21:16:40 2001")
When your program starts up, you can display the date the project was preprocessed with the following commands:
stringLength VAR byte
theIndex VAR byte
TheChar VAR byte
debug CLS 'Clear the debug screen
'Print out the source file timestamp:
read StampPPDate, stringLength
for theIndex=1 to stringLength
read StampPPDate+theIndex, theChar
debug theChar
next
debug CR


{$StampProjectPrefix prefix_string}
Specifies to the preprocessor the output file name prefix. By default, the preprocessor prefixes the output file names with the date in the format yyyy.mm.dd. Output files may be directed to another directory by including a directory path in the prefix string.


{$If if_condition}
if_block
{$ElseIf else_condition}
elseif_block
{$Else}
else_block
{$EndIf}
Causes the preprocessor to generate PBASIC code which, when run, will execute if_block if if_condition is true, elseif_block if else_condition is true, and else_block if none of the above are true. (Both the $ElseIf and $Else directives with their accompanying blocks are optional.)


{$While while_condition}
while_block
{$EndWhile}
Causes the preprocessor to generate PBASIC code that will repeatedly execute while_block as long as while_condition is true.


{$Repeat }
repeat_block
{$Until until_condition}
Causes the preprocessor to generate PBASIC code which will repeatedly execute repeat_block until until_condition is true.



Notes:
The preprocessor requires labels in order to generate code for many of the directives. If labels are not provided, the preprocessor will generate them. The generated labels are of the format SPPLnnnn. You may find the generated code more readable if you provide meaningful labels for these directives.