stbasic Structured-BASIC-Interpreter                   
====================================                   
 Author: Wilfried Waetzig                              
 Structured-BASIC-Interpreter                          
 - using the program-structure and data-structure from 
   "Chipmunk-Basic", an example program with p2c       
   by David Gillespie                                  
 - using the graphic routines SRGP V1.0                
   a "Simple Raster Graphic Package"                   
   by  David Frederick Sklar                           
 - using the functionality of GFA-BASIC on AtariST     
   with GEM/TOS (GFA-BASIC ported to UNIX-environment) 
               
 PREREQUISITES 
 ============= 
 - The p2c (PASCAL-to-C) converter must be installed      
 - SRGP "Simple Raster Graphics Package must be installed 
   For the directories of the include resp. library       
   files see the Makefile.                                
          
 FEATURES 
 ======== 
 Structured-BASIC-Interpreter                     
 - without line-numbers                           
 - GOTO / GOSUB-labels are symbolic names         
 - Structure elements:                            
     WHILE - EXITIF - WEND                        
     REPEAT - EXITIF - UNTIL                      
     DO - EXITIF - LOOP                           
     IF - ELSEIF - ELSE - ENDIF                   
     FOR - EXITIF - NEXT                          
     PROCEDURE - EXITIF - RETURN                  
     FUNCTION - EXITIF - RETURN                   
 - Variable types indicated by appendix to name:  
     varname     REAL (double)                    
     varname%    INTEGER (long)                   
     varname!    BOOLEAN (byte)                   
     varname$    STRING (char* )                  
 - PROCEDURE and FUNCTION can have formal parameters 
             and local variables                  
 - DEFFN defines an inline-function               
 - integrated graphic instructions                
           
List of all internally used UNIX-commands
=========================================
  comedit  = vi -c "set nu" 
  comerase = rm 
  comprint =  | gawk '{ print "   ", $0, "\r" }' | lpr - 
  comcat   = cat 
  comsleep = sleep 

List of all implemented KEYWORDS
================================
Types/Variables   rvar  ivar% bvar! svar$ r.num inum  string
Types/Variables   proc-name func-name def-name lbldef: label
Types/Variables   #unit () & ~let ~local ~fn ~fdef ==> error ( )
Types/Variables   , ; : REM ' !

Operations        + - * / ^ = < > <= >= <> AND OR XOR MOD NOT

Functions         SQA SQR SIN COS TAN ATN LOG LOG10 EXP ABS INT
Functions         SGN FRAC ODD TRUNC PI TRUE FALSE MIN MAX STR$
Functions         VAL CHR$ ASC LEN MID$ LEFT$ RIGHT$ UPPER$
Functions         LOWER$ SPACE$ STRING$

Arithmetic        ADD SUB MUL DIV INC DEC CLR ARRAYFILL SWAP

Structure         GOTO DEFFN FUNCTION RETURN PROCEDURE LOCAL
Structure         RETURN IF ENDIF EXITIF ELSEIF STOP FOR NEXT
Structure         WHILE WEND DO LOOP REPEAT UNTIL GOSUB THEN
Structure         ELSE TO DOWNTO STEP END

Instructions      LET LSET RSET READ DATA RESTORE ON DIM ERASE
Instructions      TRON TROFF CLS

direct commands   TEST EDIT LIST LLIST HELP RUN NEW LOAD SAVE
direct commands   BYE EXIT

I/O-instructions  PRINT AT USING INPUT OPEN CLOSE EOF

System commands   RANDOM INSTR TIMER DATE$ TIME$ EXIST SYSTEM
System commands   PAUSE

Graphic Instr.    TITLEW INFOW OPENW CLEARW CLOSEW COLOR
Graphic Instr.    SETCOLOR GRAPHMODE DEFFILL DEFLINE DEFMARK
Graphic Instr.    DEFTEXT PLOT LINE DRAW TEXT FILL BOX PBOX RBOX
Graphic Instr.    PRBOX CIRCLE PCIRCLE ELLIPSE PELLIPSE DEFMOUSE
Graphic Instr.    HIDEM SHOWM MOUSE MOUSEX MOUSEY MOUSEK
Graphic Instr.    POLYLINE POLYFILL POLYMARK ALERT FILESELECT
Graphic Instr.    MENU ONMENU

FUNCTIONS  
=========  
DEFFN fname(parlist) = expression                 
                    define an inline-function     
              e.g.: DEFFN av(x,y) = SQR(x^2+y^2)  
              e.g.: a = av(b,c)   ! call av       
                    A function defined by DEFFN can be 
                    called in the same way as the other 
                    predefined functions like SIN(x).   
                    Restriction: an inline-function cannot 
                    use another inline-function in DEFFN.  
              e.g.: DEFFN qav(x,y) = (x+y)/av(x,y) ! will not work
FUNCTION fname(parlist)      define a function     
              e.g.: FUNCTION av(x,y)               
                    LOCAL z                        
                      z = SQR(x^2+y^2)             
                    RETURN 2*z                     
NOT                 boolean operation  
SQA (real_expr)     real function: square  
SQR (real_expr)     real function: square-root 
SIN (real_expr)     real function: sinus  
COS (real_expr)     real function: cosinus  
TAN (real_expr)     real function: tangens  
ATN (real_expr)     real function: arcus-tangens  
LOG (real_expr)     real function: logarithm base e  
LOG10 (real_expr)   real function: logarithm base 10  
EXP (real_expr)     real function: exponent base e  
ABS (real_expr)     real function: absolute value  
INT (real_expr)     integer function: convert real value  
TRUNC (real_expr)   integer function: convert real value  
FRAC (real_expr)    real function: non-integer fraction  
SGN (real_expr)     real function: sign-value -1.0|0.0|+1.0 
STR$ (real_expr)    string function: convert real to string 
SPACE$ (int_expr)   string function: make "int_expr" spaces 
STRING$ (int_expr,string_expr)     string function:   
                                   make "int_expr" char's 
PI                  real constant: pi=3.1415....  
TRUE                boolean constant: true  
FALSE               boolean constant: false  
ODD (int_expr)      boolean function: true, if int_expr is odd 
EOF (#device)       boolean function: true, if #device is at END-of-file 
RANDOM (dummy)      real function: random value from 0..1 
TIMER               real function: system time in 1/100 sec 
TIME$               string function: wall time in hh:mm:ss 
DATE$               string function: date in dd.mm.yy 
VAL (string_expr)   real function: read real number from string_expr 
CHR$ (int_expr)     string function: convert int_expr 
                    to one character-string 
ASC (string_expr)   integer function: convert first character 
                    in string_expr to integer 
INSTR (s1$,s2$[,n]) integer function: tests               
                    if s2$ is contained in s1$, then      
                    returns start-position of s2$, else 0.
                    start comparison at pos. n (default=1)
MID$ (st$,int1,int2)  string function: extraxts from string st$ 
                    a string from position int1 
                    with int2 characters          
LEFT$ (st$,int1)    string function: extraxts from string st$  
                    the first (left) int1 characters  
RIGHT$ (st$,int1)   string function: extraxts from string st$ 
                    the last (right) int1 characters  
UPPER$ (string_var) string function: converts  
                    the string to upper-case characters  
LOWER$ (string_var) string function: converts  
                    the string to lower-case characters  
LEN (string_var)  integer function: returns  
                    the length of the string   
MIN (real_expr,real_expr,...)  real function: returns  
                    the smallest value of real_expr 
MAX (real_expr,real_expr,...)  real function: returns  
                    the largest value of real_expr 
MOUSEX              (graphic) integer function: returns  
                    the x-position of the mouse 
MOUSEY              (graphic) integer function: returns  
                    the y-position of the mouse 
MOUSEK              (graphic) integer function: returns  
                    the value of the mouse-keys 
MENU (dummy)        (graphic) integer function: returns  
                    the selected index in the MENU 
EXIST (string_expr) (system) boolean function: returns  
                    TRUE if the file given with full    
                    pathname in string_expr exists      
         
COMMANDS 
======== 
END                 end of BASIC-program   
NEW                 erase BASIC-program   
LIST [n1] [-n2]     lists the BASIC-program              
                    from line n1 to line n2 on the screen
LLIST [n1] [,n2]    writes the BASIC-program-listing   
                    from line n1 to line n2            
                    with linenumbers into              
                    the file "<programname>.list"      
                    and prints it on demand            
LOAD "filename"     loads the BASIC-program "filename.LIS"
                    parses the BASIC-program text         
                    and generates the internal data structures 
SAVE "filename"     writes the BASIC-program into file    
                    with the name "filename.LIS"          
SYSTEM s$           execute UNIX-system-command in string s$     
               e.g. SYSTEM "ls"  prints current directory  
PAUSE n             suspends the program for n/50 seconds       
                 => SYSTEM "sleep xs"  with x=n/50          
CLS                 clear screen                               
                    IF alpha-screen active: print FormFeed     
                    IF graphic-screen actice: => CLEARW 0      
HELP n              prints internal values              
                    n=0: print all implemented keywords 
                    n=1: print all GOTO/GOSUB-labels    
                    n=2: print all variables            
                    n=3: print all PROCEDUREs and FORMAL/LOCAL variables 
                    n=4: print all DEFFNs and FORMAL variables 
                    n=5: print all FUNCTIONs and FORMAL/LOCAL variables 
                    n=6: print all defined labels       
TEST n              performs internal tests                     
                    n=0: tests all label-references             
                    n=1: test blocks: IF-ELSEIF-ELSE-ENDIF      
                    n=2: test blocks: WHILE-EXITIF-WEND         
                    n=3: test blocks: DO-EXITIF-LOOP            
                    n=4: test blocks: REPEAT-EXITIF-UNTIL       
                    n=5: test blocks: PROCEDURE-EXITIF-RETURN   
                                      FUNCTION-EXITIF-RETURN    
                    n=6: test blocks: FOR-EXITIF-NEXT           
                    n=7: set addresses for GOTO-label, GOSUB-label 
                                           ON ... GOTO-label    
                                           ON ... GOSUB-label   
                    n=8: set addresses for inline-function DEFFN 
                    n=9: set addresses for FUNCTION              
RUN              start the BASIC-program                  
EDIT             set edit-mode and perform the following actions
                 - SAVE "name.~~~"   writes the BASIC-program 
                   into a temporary file,                     
                 - calls the editor 'vi'                      
                 - NEW  clears internal values                
                 - READ "name.~~~"   reads the BASIC-program  
                   from the temporary file.                   
PRINT [#unit,] [AT(x,y);] [USING "format",] varlist         
                 #unit  logical device number (OPEN)           
                 AT(x,y);  at screen-position column-x, line-y 
                   if "graphic-screen" then convert output to  
                   TEXT x*8,y*16,textstring                    
                 USING "format"   formatted output             
                 e.g. " #####.###" for a number              
                 e.g. " \.......\" for a string              
                 varlist   list of variables separated by comma
DATA constlist      stores values in  a datastring                 
                    as a list of constants separated by comma      
                      e.g.  DATA Alpha,Beta,Gamma                  
                      stores 3 string-constants "Alpha","Beta","Gamma" 
READ varlist        reads the values stored in DATA-statements.
                      the data values are read from the string     
                      DATASTRING in the same format as with INPUT  
INPUT [#unit,] ["text";] varlist                                
                    read values for variables separated by comma   
                    #unit  logical device number (OPEN)            
                    "text"  is printed before reading the values   
                    varlist:   list of variables separated by comma
                      variable type real       nnn.mmmExxx         
                      variable type integer    nnnnn               
                      variable type boolean    t[rue] / f[alse]    
                      variable type string     sssssss up to comma 
                            or "string": all characters without "" 
LINE INPUT [#unit,] ["text";] varlist                           
                    read values for variables separated by newline 
OPEN "mode", #unit, "filename"                                 
                    mode = "I"   for input file                   
                    mode = "O"   for output file                  
                    #unit:  logical unit in INPUT, PRINT, CLOSE   
                    "filename":  string with filename             
                    special filnames:                             
                    - "CON:" or "" => console: 'input' / 'output' 
                    - "LST:" or "PRN:" => text for printer        
                      store text in temporary file: 'basname.LST:'
                      and print it on demand.                     
CLOSE #unit         close file on unit-number #unit             
CLOSE               close all opened files                      
                    sent a print-file to the printer on demand  
LET varname = expression                                      
                    allows the use of reserved names "varname"   
                    for variable names                           
LSET stringname = stringexpr                                  
                    stores stringexpr to the left in stringname  
                    e.g.: a$="1234567890"   b$="abcd"            
                          LSET a$=b$  results in: a$="abcd      "
RSET stringname = stringexpr                                  
                    stores stringexpr to the right in stringname 
                          RSET a$=b$  results in: a$="      abcd"
IF boolexpr THEN                                         
                    if boolexpr=TRUE execute the following  
                    instructions up to ELSE or ELSEIF       
                    or ENDIF                                
                    structure:  IF boolexpr THEN            
                                  ....statements            
                                ELSEIF boolexpr             
                                  ....statements            
                                ELSE                        
                                  ....statements            
                                ENDIF                       
ELSE                starts alternative block of IF-statement  
ELSEIF boolexpr THEN                 
                    starts alternative block of IF-statement  
ENDIF               END of IF-statement-block           
EXITIF boolexpr     terminates the loops IF boolexpr=TRUE 
                      e.g.  PROCEDURE pname               
                              EXITIF boolexpr             
                            RETURN                        
                      e.g.  WHILE boolexpr                
                              EXITIF boolexpr             
                            WEND                          
                      e.g.  REPEAT                        
                              EXITIF boolexpr             
                            UNTIL boolexpr                
                      e.g.  DO                            
                              EXITIF boolexpr             
                            LOOP                          
                      e.g.  FOR l = l1 TO l2 [STEP l3]    
                              EXITIF boolexpr             
                            NEXT l                        
ADD var[()] [, expr]                           
                    calculates:  var = var + expr 
SUB var[()] [, expr]                           
                    calculates:  var = var - expr 
MUL var[()] [, expr]                           
                    calculates:  var = var * expr 
DIV var[()] [, expr]                           
                    calculates:  var = var / expr 
                    default value for expr:  1.0  
                    if var is an array(), the operations  
                    are performed with all array-elements 
INC var             calculates:  var = var + 1  
DEC var             calculates:  var = var - 1  
                    var can be an array-element 
FOR var = expr1 [DOWN]TO expr2 [ STEP expr3 ]             
                    counting loop from FOR .. NEXT           
                    expr1:  start-value of the loop-variable 
                    expr2:  end-value of the loop-variable   
                    expr3:  increment/decrement              
NEXT var            end of FOR-block                 
WHILE boolexpr      ...  WEND                              
                    if boolexpr=TRUE then execute all      
                    instructions up to WEND                
WEND                end of WHILE-loop                   
DO                  perform all instructions in the loop
                    until LOOP                          
LOOP                end of  | DO .. LOOP |  loop        
REPEAT              start of REPEAT / UNTIL block     
UNTIL boolexpr      end of REPEAT / UNTIL block       
GOTO lbl            continues processing in the line  
                    marked with a label "lbl:"        
GOSUB procname [ (expr1 [,expr2] ... )]              
                    calls the PROCEDURE procname        
                    with transfer of expr<n> to the formal 
                    parameters of the PROCEDURE         
               e.g. GOSUB prval (l%+1, "a", 3.14)  
                    PROCEDURE prval (i%, s$, v)    
                      PRINT i%,s$,v                
                    RETURN                         
ON intexpr GOTO l1, l2, ...  lm                    
                    branch to label l<n> if intexpr=n 
                    error if n=0 OR n>m               
ON intexpr GOSUB p1, p2, ... lm                    
                    call PROCEDURE p<n> if intexpr=n  
                    error if n=0 OR n>m               
PROCEDURE procname [(p1 [,p2] ... )]                             
                    defines the PROCEDURE "procname"              
                    with the optional formal parameters p1, p2, ..
                    Type of the formal parameters:                
                      the VAL parameter accepts a value           
                      the VAR parameter returns a value           
                      the ARRAY parameter is of VAR parameter type
                    - inttype%    integer variable type: VAL parameter  
                    - realtype    real variable type   : VAL parameter  
                    - booltype!   boolean variable type: VAL parameter  
                    - string$     string variable type : ARRAY parameter
                    - '&' preceeding the name of the parameter => VAR   
                    - arrays() of these types are ARRAY parameters      
              e.g.  PROCEDURE proc (v1, v2%, v3!, v4$)                  
                      LOCAL lv1, lv2%, lv3!, lv4$                       
                      Attention: strings are not copied, they are treated
                      implicitely as variable parameters.               
                      Arrays are not permitted as LOCAL variables.      
                      () is the array indicator for a formal parameter  
              e.g.  DIM a(3,4)                     
                    GOSUB compute (n, a())         
                    PROCEDURE compute (m, b())     
                      b(1,1)=1                     
                    RETURN                         
                    In this example the array b() has the size b(3,4).  
                    The type of each formal parameter in the PROCEDURE  
                    declaration must agree with the type of the actual  
                    parameter in the PROCEDURE-call.                    
RETURN              define the end of a PROCEDURE          
RETURN expr         define the end of a FUNCTION          
RESTORE [label]     resets pointer for READ-statement to "label" 
DIM var (intexpr) [, var (intexpr)]                       
                    defines the variables var to be arrays   
                    with the length of "intexpr" data-values 
                    A maximum of 4 dimensions is allowed.    
                    e.g.:  DIM a(3,4,5)                      
ARRAYFILL var (), expr                                 
                    fills all elements of the array var() 
                    with the value from expr              
SWAP  var1[()], var2[()]                          
                    exchanges the values of          
                    the variables var1 and var2      
                    or arrays var1() and var2()      
ERASE var() [, var()]                                         
                    erases the array-variables var ()            
                    DIM var(expr) must be given to use it again  
CLR varlist         set variables in varlist to zero          
                    e.g. xreal = 0.0;      xint% = 0          
                         xbool! = FALSE;   xstr$ = ""         
TRON [n]            switch TRACE ON             
                    n=0: print lines processed  
                    n=1: print lines and next line-number  
                    n=2: print address tests    
                    n=3: print internal subroutines passed 
                    n>0: wait for input,        
                    if input-character = "|" then set n=0. 
TROFF [n]           switch off TRACE and DEBUG-printout   
                    n > 0  print the tokens in line #n of the program 
BYE                 terminates the BASIC-interpreter 
EXIT                terminates the BASIC-interpreter 
                 
GRAPHIC Commands 
================ 
TITLEW n,title      set title in window #n      
                    title    text in title-line 
INFOW n,info        set info-line FOR window #n     
                    not yet implemented due to limitations in SRGP
OPENW n,x,y         open window #n with size (x,y)            
                    OPENW 0,0,0   initiate the graphic screen 
                      with the size 640*400 pixels            
                      and enable the graphic instructions     
                    Only the window #0 is visible; this is    
                      a feature of the SRGP-Package           
CLEARW n            clear window #n      
CLOSEW n            close window #n       
COLOR cdraw, cback  set colour for drawing and background     
                    cdraw: colour for BOX, CIRCLE, DRAW, ELLIPSE,
                                      LINE, PLOT, RBOX           
                    cback: colour for background in pattern      
SETCOLOR i,r,g,b    set colours for the display         
                    i        # of colour-register       
                    r,g,b    red-green-blue value (0..7)
GRAPHMODE mode      set graphic-mode                 
                    mode: 1=replace 2=transparent    
                          3=xor 4=reverse transparent
DEFFILL c,a,b       define colour and texture             
                    c      colour for filling             
                    a,b    select pattern for FILL, PBOX, 
                                  PCIRCLE, PELLIPSE, PRBOX
DEFLINE s,b         define: linestile and width      
                    s    linestile                   
                    s=1 continuous, s=2 dashed       
                    s=3 dotted, s=4 dot-dashed       
                    b    width of line               
                    for BOX, CIRCLE, DRAW, ELLIPSE, LINE, RBOX
DEFMARK c,a,g       define: colour, size, type (POLYMARK)        
                    c     colour                         
                    a     type of marker                 
                          (1=. 2=+ 3=* 4=[] 5=+ 6=#)     
                    g     size of marker (0,20,40,60,80,100) 
                          FOR POLYMARK                       
DEFTEXT c,s,r,g     colour,type,stile,rotation (TEXT)     
                    c       colour                        
                    s       stile (1=bold 2=light 4=cursiv
                            8=underline 16=outlined)      
                    r       rotation angle in 1/10 degree 
                    g       size of text (4,6,13,32)      
                    not yet fully implemented due to      
                    limitations in SRGP                   
PLOT x0,y0          draw a point on the screen       
                    equivalent to DRAW x0,y0         
LINE x0,y0,x1,y1    line from (x0,y0) to (x1,y1)     
DRAW x0,y0 TO x1,y1 line from (x0,y0) to (x1,y1)     
                    (x0,y0)        start-coordinate  
                    (x1,y1)        END-coordinate    
TEXT x,y,s$         draw string s$ at (x,y)                
FILL x,y            fill pattern into an areal          
                    (x,y)   coordinate to start filling 
                    not yet impmented due to limitations in SRGP 
BOX x0,y0,x1,y1     draw rectangle                    
PBOX x0,y0,x1,x1    draw filled box                   
RBOX x0,y0,x1,y1    draw rounded box                  
PRBOX x0,y0,x1,y1   draw rounded filled box           
                    (x0,y0)        lower left corner  
                    (x1,y1)        upper right corner 
CIRCLE x,y,r,p0,p1  draw circle at (x,y) radius r          
PCIRCLE x,y,r,p1,p2 draw filled circle                     
                    (x,y)    center                        
                    r        radius                        
                    p0,p1    arc angle p0..p1 in 1/10 degree
ELLIPSE x,y,rx,ry   draw ellipse at (x,y)                   
PELLIPSE x,y,rx,ry  draw filled ellipse                     
                    (x,y)    center coordinate              
                    rx,ry    x/y-axis                       
                    p0,p1    arc angle p0..p1 in 1/10 degree
DEFMOUSE n          define mouse symbol              
                    n        mouse-sysmbol (0..7)    
HIDEM               hide mouse symbol                
                    SRGP: de-activate the locator    
SHOWM               show mouse symbol                
                    SRGP: activate the locator       
MOUSE x,y,k         return mouse-position (x,y) and key k   
                    k   status of mouse-key 1=left, 2=right 
POLYLINE n,x(),y()  draw polygon in (x(),y())        
                    the first point = last point to draw
                      a closed polygon
POLYFILL n,x(),y()  draw filled polygon                
                    connects first point with last point
                      and fills the resulting polygon with
                      pattern defined in DEFFILL
POLYMARK n,x(),y()  draw polygon points                
                    type of points defined in DEFMARK
                    n        # of points
                    x(),y()  arrays with (x,y)-values of points
ALERT a,tx$,b,b$,var       display an ALERT-BOX              
                    a      sign: 1=! 2=? 3=STOP        
                    tx$    textstring (max. 4 lines) L1|L2|L3|L4 
                    b      button frame (0,1,2,3)      
                    b$     string for buttons 1|2|3    
                    var    return # of button selected 
FILESELECT s$,n$,x$      display a fileselector-box            
                    s$   (string) search-path + selector  
                    n$   (string) filename                
                    x$   (string) return selected filename
MENU array$()       read text for menu-header from array$() 
                    the string-array contains the text      
                    for menu-line and menu-rows             
                    - end of row: empty string ""           
                    - end of menu-text: empty string ""     
MENU n,x            change menu-point #n with value x       
                    x=0  ' '  normal, reset marker '^'      
                    x=1  '^'  set marker                    
                    x=2  '='  set menu-point non selectable 
                    x=3  ' '  set menue-point selectable    
                         '-'  permanent non selectable      
MENU STOP           switch off the menu                     
ONMENU GOSUB p1     define PROCEDURE p1 to handle an action   
                    if a menue-point was selected             
ONMENU              execute the menu and                      
                    wait for menue-events  
--------------------------------------------------------------------
                   
