Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / rascal.arc / RASCAL.DOC < prev next >

Wrap

Text File | 1980-01-01 | 27.9 KB | 901 lines

November 1983 This document tells how to use the Rascal BASIC preprocessor program, RASCAL.EXE, and tells how to write programs for the IBM PC in the Rascal language. This manual assumes you are familiar with MS DOS and Microsoft BASIC. RASCAL USER'S MANUAL RASCAL USER'S MANUAL Manual version: 1.05 Software version: 1.05 Marty Franz 525 W. Walnut St., Kalamazoo, MI 49007 (616) 344-1821 (C) Copyright 1983 Marty Franz - All rights reserved 111483105 Rascal Preprocessor User's Manual INTRODUCTION INTRODUCTION RASCAL.EXE is a preprocessor program for Microsoft BASIC on the IBM PC. It takes a program containing special Rascal statements and translates it into a program containing BASIC statements. Using Rascal helps you write more concise, better structured BASIC programs, because the preprocessor lets you take advantage of these features: - you now have the ability to write free-form, indented statements without line numbers. - you can now include statements from many separate files into a single BASIC program. This lets you write and maintain your programs in small modules. - you can organize your subroutines into procedures, each with its own alphanumeric name. - you can use structured programming statements similar to those found in programming languages like Pascal and C. Before using RASCAL.EXE, please take the time to read these instructions carefully. When using it, bear in mind that this is version 1.05 of the program, and there may be bugs in it. If there is, or you have suggestions on improving Rascal, please contact me: Marty Franz 525 W. Walnut St. Kalamazoo, MI 49007 (616) 344-1821 One more thing: the program, and this manual, are copyrighted materials. They may be freely distributed only for private, noncommercial use. Please read the copyright notice on your diskette. A SAMPLE PROGRAM A SAMPLE PROGRAM Before describing Rascal in too much detail, let's first look at a typical program. This will help you understand what RASCAL.EXE does. The file LC.RAS on the Rascal diskette is a good example. It asks for the name of a text file and counts the number of lines in it. You can make a listing of LC.RAS on your printer with the PRINT program supplied on the diskette: A>llist lc.ras (See the LLIST program instructions for more information on the LLIST program.) Page 2 111483105 Rascal Preprocessor User's Manual Your listing of LC.RAS should look like this: 'Sample Rascal program to count the lines in an ASCII file. PROCEDURE MAIN ON ERROR GOTO CHECK.FOR.EOF INPUT "File Name"; FILE.NAME$ OPEN FILE.NAME$ FOR INPUT AS #1 LINE.COUNT = 0 : DONE.SW = 0 REPEAT LINE INPUT #1, L$ LINE.COUNT = LINE.COUNT+1 UNTIL DONE.SW = 1 PRINT "There are";LINE.COUNT-1;"lines in ";FILE.NAME$ ENDPROC CHECK.FOR.EOF| ERROR.CODE = ERR : ERROR.LINE = ERL IF ERROR.CODE = 62 DONE.SW = 1 RESUME NEXT ELSE PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE STOP 'Immediately halt program ENDIF END This file (called a source file in this manual) was created ______ ____ using the RED.EXE program. For more information about RED, see the separate file about it on the diskette. Don't worry at this point about the details of each statement in the program; we'll be covering them shortly. For now, notice only that a Rascal program, unlike a BASIC program, has line-number-free, neatly indented statements, and empty lines to separate blocks of statements. In fact, it resembles those Pascal programs you've seen in magazines more than BASIC. Because the program looks more structured than BASIC, it ought to be easier to understand and maintain. Unfortunately, this program cannot be executed directly by BASIC. We need to convert this program into one with everyday BASIC statements in it before we can run it. This is what RASCAL.EXE does. To build a BASIC program out of LC.RAS, we enter: A>rascal lc.ras lc.bas and these messages appear: Page 3 111483105 Rascal Preprocessor User's Manual Rascal BASIC preprocessor, version 1.05 (C) Copyright 1983 Marty Franz 60KB to spare Done with pass 2, 0 error(s) found. 22 lines processed, 147 lines/minute. A> After the RASCAL.EXE is done, if we then type the output file, LC.BAS, we see: A>type lc.bas 10 'LC.RAS 10-14-83 5:48a 22 lines 20 GOSUB 50 30 END 40 'Sample Rascal program to count the lines in an ASCII file 50 'PROCEDURE MAIN 60 ON ERROR GOTO 150 70 INPUT "File Name"; FILE.NAME$ 80 OPEN FILE.NAME$ FOR INPUT AS #1 90 LINE.COUNT = 0 : DONE.SW = 0 100 LINE INPUT #1, L$ 110 LINE.COUNT = LINE.COUNT+1 120 IF NOT(DONE.SW = 1) THEN 100 130 PRINT "There are";LINE.COUNT-1;"lines in ";FILE.NAME$ 140 RETURN 150 'CHECK.FOR.EOF| 160 ERROR.CODE = ERR : ERROR.LINE = ERL 170 IF NOT(ERROR.CODE = 62) THEN 210 180 DONE.SW = 1 190 RESUME NEXT 200 GOTO 230 210 PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE 220 STOP 'Immediately halt program 230 END A> This is a conventional BASIC program that can now be run using ____ BASIC or BASICA. Page 4 111483105 Rascal Preprocessor User's Manual To summarize our example, which demonstrated the process of creating a Rascal program: 1. We first use a text editor to write the program. The program contains special Rascal statements (which we'll cover soon), is free of line numbers, has lots of blank lines and indenting, and is easier to read and maintain than regular BASIC. 2. We then use the Rascal preprocessor program, RASCAL.EXE, to translate the Rascal program into one with everyday BASIC statements in it. 3. The translated BASIC program is now run and debugged as usual from BASIC. PROGRAM REQUIREMENTS PROGRAM REQUIREMENTS To preprocess Rascal programs, you need an IBM PC or XT with: - at least 64KB of memory, - at least one single-sided diskette drive, - a color or monochrome adapter, with a monitor capable of displaying 80-character lines. - MS DOS version 1.1 or 2.0, and - BASIC.COM or BASICA.COM You also need the files: RASCAL.EXE RAS.BAT available on the diskette with BASIC or BASICA. Page 5 111483105 Rascal Preprocessor User's Manual THE RAS.BAT FILE THE RAS.BAT FILE The file RAS.BAT has been included to make processing Rascal source files easier. Instead of using RASCAL.EXE and completely specifying the input and output file names, RAS.BAT gives you a command called RAS that assumes a .RAS extension on the Rascal program's filename and a .BAS extension on the output BASIC filename. The format of the RAS command is simply: A>ras {filename} The word "filename" in { }s means you have to supply your filename (without specifying the extension) for the command to work properly. To preprocess the file LC.RAS, for example, we'd use: A>ras lc Now that we've covered how to preprocess Rascal programs, let's delve into how to write them. RASCAL STATEMENTS RASCAL STATEMENTS Your Rascal source program is composed of Rascal statements. A Rascal statement is similar to a BASIC statement, except the line number is missing: Rascal supplies this for you when it builds the BASIC program from your Rascal program. If 10 PRINT "Hello, world" is a BASIC statement, then PRINT "Hello, world" is the matching Rascal statement. Only the line number is missing. You can have any number of blanks and tab characters in your Rascal statements. In fact, this is encouraged since this helps make your Rascal programs easier to read. Page 6 111483105 Rascal Preprocessor User's Manual LABELS LABELS Without line numbers in front of statements, you need another way to mark the places in a program where control is to go during its execution. You can do this in Rascal with alphanumeric labels instead of line numbers. In a BASIC program, we might write two statements as: 960 GOTO 1030 and 1030 STOP 'End the program In Rascal, these two statements would be written instead as: GOTO THE.END and THE.END| STOP Labels can be from 1 to 32 characters in length. Only the characters 0-9, A-Z, a-z, and "." (period) can be in a label. This is to keep labels from conflicting from other BASIC keywords. The "|" (vertical bar) is used only where the label is defined; notice that it's not there in the GOTO statement. It's used to set the label off from the rest of the line. Another example of labels in a Rascal program is in LC.RAS. The statements: ON ERROR GOTO CHECK.FOR.EOF and CHECK.FOR.EOF| also demonstrate how labels are referenced (the ON GOTO statement) and defined (the CHECK.FOR.EOF| statement) in Rascal. The Rascal statements that can use labels are: ON ERROR GOTO {label} ON n GOTO {label1},{label2},... RESTORE {label} RESUME {label} RETURN {label} Page 7 111483105 Rascal Preprocessor User's Manual PROCEDURES PROCEDURES Rascal provides procedures to help organize your programs. Procedures are similar to BASIC subroutines, except they are identified by and called with an alphanumeric name. Procedures in Rascal look like this: PROCEDURE {procname} ____ statements making up the procedure ENDPROC ____ (You don't have to spell out the word PROCEDURE; PROC will do, as will ENDP for ENDPROC. In this manual, the underlines show which part is required.) To GOSUB to a procedure you can use either: GOSUB {procname} ____ or DO {procname} __ with the rules for procedure names being the same as for label names. The other Rascal statements that can call procedures are: ON n DO {procname1},{procname2},... ON COM(n) DO {procname} ON KEY(n) DO {procname} ON PEN DO {name} ON PLAY(n) DO {procname} ON STRIG(n) DO {procname} ON TIMER(n) DO {procname} Every Rascal program requires at least one procedure, called MAIN. Control is always given to MAIN with a GOSUB when the program is started (see lines 10-50 of LC.BAS). So, our "Hello, world" example needs three statements to work properly: PROCEDURE MAIN PRINT "Hello, world" ENDPROC Like white space, you should liberally use procedures in your Rascal programs. They help break your program into mind-size chunks for better organization. Even a single statement deserves its own procedure if doing so will make the program easier to read. Page 8 111483105 Rascal Preprocessor User's Manual IF BLOCKS IF BLOCKS The only place in your Rascal programs where you can't freely use a label to stand for a line number is in an IF statement. Instead, a special form of IF is used in Rascal, called an "IF block". It looks like this: IF {condition} __ statements executed if {condition} is true ELSE ____ statements executed if {condition} is false ENDIF ____ An example of an IF block is in LC.RAS: IF ERROR.CODE = 62 DONE.SW = 1 RESUME NEXT ELSE PRINT "BASIC error ";ERROR.CODE;"at";ERROR.LINE STOP 'Immediately halt program ENDIF Briefly, IF the variable ERROR.CODE has the value 62 then the statements DONE.SW = 1 and RESUME NEXT will be executed. This will occur if we have reached the end of the file we are reading. If ERROR.CODE is not 62, then another, more sinister BASIC error has occurred that we don't know how to handle. The statements after the ELSE display the error code and line number and stop the program. Why should you use IF blocks in a Rascal program instead of BASIC's IF {condition} THEN {line number} statement? Because the IF block gives you the advantage of always knowing exactly where control begins and ends: with no GOTO statements in the IF and ELSE parts of the block, execution beginning at the IF statement will always resume after the ENDIF statement, regardless of what happens in between. With BASIC's IF statement, you can picture control splitting into two separate paths with each THEN. Pretty soon, as patches and revisions are made, your program becomes a mess of "spaghetti code". If you faithfully use the IF block for your program's logic you should seldom find the need for a GOTO statement. GOTOs should be saved only for unusual conditions that require special processing, such as errors. Page 9 111483105 Rascal Preprocessor User's Manual REPEAT AND WHILE BLOCKS REPEAT AND WHILE BLOCKS Right now, many of your program loops in BASIC are written using IFs and GOTOs. To help make these more structured, Rascal provides a REPEAT block for executing a group of statements over and over until a terminating condition is reached. It looks like this: REPEAT ____ statements to keep repeating UNTIL {condition} ____ A REPEAT block is used in LC.RAS: REPEAT LINE INPUT #1, L$ LINE.COUNT = LINE.COUNT+1 UNTIL DONE.SW = 1 Remember that REPEAT is like any loop you might make with GOTOs in BASIC: you need to change something at some point in the statements you're repeating to stop the loop or you'll continue forever. Besides meeting the condition for termination, you can use a BREAK statement in the REPEAT block to transfer control immediately outside the loop. To use a BREAK statement, simply specify BREAK ____ Besides REPEAT, Rascal provides a WHILE loop similar to the one already in Microsoft BASIC: WHILE {condition} ____ statements to repeat while {condition} is true ENDWHILE ____ When using the WHILE block, remember that the {condition} is tested before the statements in the body of the loop are ever executed, so it's possible to not do them at all. Also, be sure you use ENDWHILE instead of WEND in Rascal, or RASCAL.EXE will give you an error message. When the BASIC program is generated, a WHILE block will not have any Microsoft WHILE statements in it. Instead, IFs and GOTOs are used to make the loop, so the program can be converted to computers that don't have as advanced a version of BASIC. You can also use BREAK to get out of a WHILE loop. Page 10 111483105 Rascal Preprocessor User's Manual INCLUDE FILES INCLUDE FILES A useful technique in programming is designing a program as a set of small, independent modules. This makes programs easier to change, since revisions (like a changing the layout of a file) only affect a small component (the subroutines that read or write the file). Modular programming is hard to do with BASIC because all the pieces of your program must be present in a single file, with one set of line numbers. To help you develop your programs as small modules, Rascal has an INCLUDE statement. Before telling you what it does, here's what it looks like: INCLUDE {filename.ext} INCLUDE is used to bring statements into a program from a completely separate file during preprocessing, to be part of the program when it's translated into BASIC. The statements in the "included" file are also Rascal statements. They can define and reference labels, procedures, and blocks exactly as if they were in the original source file. In fact, the INCLUDEd file can itself have INCLUDE statements in it. INCLUDE is an extremely useful feature of Rascal, because now you can write frequently-used pieces of programs, such as input routines and screen formatters, once as sets of Rascal procedures and just INCLUDE them into each new program that you write. When you edit these new programs you don't have to manually APPEND the pieces, since RASCAL.EXE will automatically take care of the line numbering for you. (But not the variables.) MULTIPLE STATEMENTS MULTIPLE STATEMENTS In BASIC programs, you can write several statements on a single line by separating them with the {:} character. Since RASCAL.EXE creates a BASIC program from the statements you give it, the {:} character will work just as it does in BASIC, but with an important exception: the special Rascal statements mentioned here cannot be used in multiple lines. Instead, they ______ must have their own line whenever you use them. This restriction may change in another version of RASCAL.EXE. Page 11 111483105 Rascal Preprocessor User's Manual ERROR MESSAGES ERROR MESSAGES When RASCAL.EXE processes your program, it makes two sweeps or "passes" across it. The first pass checks for errors. There aren't very many that you can make, since most of your program will be passed through, untouched except for the addition of line numbers, to BASIC. There are, however, a few ways to produce an error message. The possible messages that you can get are listed below, along with an explanation of how to fix the statement that caused them. All of these messages will begin with the name of the file being processed (since the error might be in an INCLUDEd file) and the offending line number. label {name} defined previously at {file} line {n} If this error message is displayed it means you have defined the label {name} twice (or more...) in your program. A good candidate for the source of this problem is an INCLUDEd file with a duplicate of a label you are using in your program. label {name} referenced at {file} line {n} undefined This error message is saying that you have forgotten to define the label {name} in your program. Possible causes of this are forgetting an INCLUDE file (especially likely if you see a lot of these messages) or misspelling the label. label {name} type mismatch with {file} line {n} This error message is displayed when you try to GOTO a procedure name or DO a LABEL|. {type} block not active You used an ENDIF, ENDWHILE, or UNTIL statement in your program without first using IF, WHILE, or REPEAT. {type} block already begun at {file} line {n} You tried to put two ELSE statements in one IF block. You have probably forgotten an IF statement somewhere. procedure {name} already begun at {file} line {n} You cannot have two procedures started at the same time. You must end the first procedure, {name}, with an ENDPROC statement before you can begin your new procedure. Page 12 111483105 Rascal Preprocessor User's Manual procedure not begun first This error message means that an ENDPROC statement was found in your program when no PROCEDURE statement was active. no WHILE or REPEAT for BREAK This error message is displayed when you use a BREAK statement outside a WHILE or REPEAT blocks. Remember that a BREAK transfers control to the statement immediately after the nearest ENDWHILE or UNTIL. RASCAL.EXE ABORTS RASCAL.EXE ABORTS If you specify a source or object filename that can't be read or written to for some reason (such as the name being misspelled, the diskette having its write-protect notch covered, etc.) the preprocessor program will print the message: ABORT- can't open file {filename.ext} If this happens, you should check to make sure that the source file can be read, that any INCLUDEd files it uses can be read, and that the object file can be written to. Page 13 111483105 Rascal Preprocessor User's Manual PREPROCESSOR SPEED PREPROCESSOR SPEED This version of RASCAL.EXE can process your programs at the rate of 120-300 lines per minute. As you can see, this rate is highly variable and is based on a number of factors, such as the speed of your disk drives, the version of MS DOS you are using, even the location of the files on the diskette. If you have frequently-used INCLUDE files you might want to consider putting them on a RAM disk if you aren't going to change them often. This should improve processing time a lot. RASCAL VS. BASIC RASCAL VS. BASIC Once you've mastered the Rascal statements, there aren't many reasons to continue entering and debugging BASIC programs the old way. You'll probably find that with a little practice Rascal programs really are easier to write and maintain. The only reasons to modify the translated BASIC programs directly are: 1. Quick "patches" or minor changes to the BASIC program when the Rascal source code isn't available or there isn't time to edit it again. (Such as when you're at the customer's office and the payroll program isn't working.) 2. "Fine tuning" for better performance, to straighten out Rascal's "inside out" IF statements and extra GOTOs in programs where speed and memory size are crucial. Page 14 111483105 Rascal Preprocessor User's Manual STATEMENT REFERENCE STATEMENT REFERENCE Here's a list of all the special statements available to you in this version of RASCAL.EXE. For a complete description of how to use them, see the individual sections in this manual. BREAK DO {procname} ELSE ENDIF ENDPROC ENDWHILE IF {condition} GOSUB {procname} GOTO {label} INCLUDE {d:filename.ext} ON n DO {procname1},{procname2},... ON COM(n) DO {procname} ON KEY(n) DO {procname} ON PEN DO {name} ON PLAY(n) DO {procname} ON STRIG(n) DO {procname} ON TIMER(n) DO {procname} ON n GOTO {label1},{label2},... ON ERROR GOTO {label} REPEAT RESTORE {label} RESUME {label} RETURN {label} UNTIL {condition} WHILE {condition} Page 15 111483105