P B S
                               -----

                     A pre-processor for BASIC.
                     --------------------------

                         by Lee David Rimar


              Inspired by PREBAS, a program by G. Wolfe
                PBS stands for PreBas, Small version


PBS is intended as an aid to BASIC programmers.  With it they can 
enter a program in their favorite text editor or word processor, 
while not worrying about line numbers, or the targets for their GOTO 
and GOSUB statements.  PBS then takes the un-numbered ASCII file, 
adds line numbers to it, and resolves references to target labels.

PBS was written in Microsoft BASIC (MBASIC) and was compiled with 
BASCOM.  You should have these files in this library:


  -PBS.DOC       This file

  PBS-O.COM      Stand-alone compiled program, linked with
                 OBSLIB.REL
  
  PBS-S.COM      Small version of compiled program, requires
                 BRUN.COM to run.

  PBS.PBS        Source code ready for PBS processing
                 (yes, PBS can preprocess itself!)

  PBS.BAS        Source code ready for compiler/linker

  CTAIL.REL      Relocatable module needed for compiling.
                 Gets command line from CP/M

  UCASE.REL      Relocatable module needed for compiling.
                 Converts strings to upper case


Because PBS is coded with CALLs to those to RELocatable modules, it 
won't run under the MBASIC interpreter without some modifications.
Remarks in the source code annotate what needs to be changed.


                             RUNNING PBS
                             -----------


First, decide which version of PBS you want to use.  PBS-O.COM will 
run on any CP/M system, and doesn't need any other files.  PBS-S.COM 
is much smaller, but you must have BRUN.COM present on the currently 
logged disk.  Whichever one you decide to use, rename it PBS.COM.


Then from the CP/M command line, just enter:

  A>PBS TEST.BAS

This will take an ASCII (non-document) file called TEST.PBS and make 
a new file called TEST.BAS.  Don't enter the file extents; they 
default to .PBS for the input file and .BAS for the output file.

This new file (TEST.BAS) will have line numbers at the start of each 
line, starting with 1 and incrementing by 1 each time.   If you want 
different line numbers, you can load the resulting file in MBASIC and 
issue a RENUM command.

An "'" will be inserted into any line starting with a label 
(identified by an "@" as its first character).  Any references to 
that label will be translated into references to the actual line 
number.  Appended to the end of any line containing references to 
target labels will be a comment like " ' @LABEL " for each label 
translated to a line number.

PBS also strips out leading and trailing "white space" on a line.  
When working with your .PBS program file with your text editor, you 
can indent lines to make loop structures more evident.  But the extra 
spaces will be stripped from the .BAS output file; this lets programs 
run a bit faster.

For example, Say we had a file called TEST that looked like this:

'------------------------------------------------------------
'       @TEST -- A test for PBS
'
'------------------------------------------------------------
@START -- This is the start of the program.
FOR J = 1 TO 20
    GOSUB @ROUTINE
NEXT J
'
INPUT "DO YOU WANT TO EXIT"; A$
IF A$ = "Y" THEN GOTO @END ELSE GOTO @START
'
@END
'
END
'
'
@ROUTINE
PRINT "INSIDE ROUTINE"
RETURN

The command:
A>PBS B:TEST 
would produce a file called TEST.BAS that looked like this:

10 '------------------------------------------------------------
20 '      @TEST -- A test for PBS
30 '
40 '------------------------------------------------------------
50 '@START -- This is the start of the program.
60 FOR J = 1 TO 20
70 GOSUB 180 ' @ROUTINE
80 NEXT J
90 '
100 INPUT "DO YOU WANT TO EXIT"; A$
110 IF A$ = "Y" THEN GOTO 130 ELSE GOTO 50 ' @END ' @START
120 '
130 '@END
140 '
150 END
160 '
170 '
180 '@ROUTINE
190 PRINT "INSIDE ROUTINE"
200 RETURN


                               LABELS:
                               -------

PBS recognizes labels if, (A): their first character is a @ 
character, and (B): they are whole words.

PBS recognize as a target line any line where the first word, 
(whether preceded by white space, or not), is a label (has the 
marker character as its first char.). If there are duplicate 
labels, the first one will be used as the target.

Compare the PBS.PBS and PBS.BAS files included in this library for a 
better idea of how labels are used.


                         MISCELLANEOUS NOTES
                         -------------------

In 1985, G. Wolfe ("Greywolf") wrote a program called PREBAS.BAS, 
which was distributes as "freeware."  I liked that program, but found 
it somewhat clumsy to use.  It was also quite large, and ran slow.

I didn't use PREBAS very much, until recently when I started doing 
quite a bit of BASIC programming again (who says BASIC is a dead 
language?).  But the problems bothered me so much that I decided I 
would try to modify it.  

After a few false starts, I ended up writing my own program from 
scratch.  So while this program was inspired by the original PREBAS, 
they have not a single line of code in common.

PBS lacks many options which PREBAS offered.  PREBAS had two 
modes of operation:  from CP/M command line, or with prompts.  It 
also had a variety of options:  It could add or STRIP line 
numbers from a file; the user had more flexibility on input and 
output file names; and could also set the starting line number 
and increment size.  But I never used those options.  So I wrote 
PBS to simply emulate PREBAS's defaults in the command line mode.

For my uses, PBS is a better program.  It's simple, small, and fast.
But as it's not as flexible as PREBAS; some people might prefer to 
have that program instead.  It's available on many RCP/Ms.

"Try it; you'll like . . . "



Lee David Rimar                                       1 May, 1988


                              -eof-