-------------------------------------------------------------------
Turtle graphics interpreter by Nigel Salt
-------------------------------------------------------------------

TURGRA requires a  VGA that supports 16 colours at a resolution of
640 x 480. It is designed to run under DOS 3 or above  on  an  IBM
compatible

Source code to drive the turtle has to be text edited into a  file
before running the program. If you do not specify a source file on
the  command  line  then  TURGRA  will  look  for  a  file  called
turgra.dat. Files must not exceed 32000 characters. Duplicate spaces
between commands are trimmed out so do not be afraid to space out
your source code so that it can be easily understood.

When the program begins the screen will be cleared to bright white
on  blue.  The turtle will be at coordinates 320,240 which is  the
centre  of  the screen. 0,0 is top left and 639,479 is bottom right. 

The angle of movement will be set to 0 degrees  which is  pointing
to  the  bottom side of   the  screen. Angles increase in an anti-
clockwise fashion such that an angle of 90 points to the right  of
the screen and one of 270 points to the left.

The  pen   will  be  down which means that the turtle will leave a 
white trail behind it.

Angles  must  be specified in degress all other arguments  are  in
integers  (range -32768 to +32768).  Where  screen coordinates are 
required  x coordinates should be in the range 0-639 whilst y coor-
dinates should be in the range 0-479. 

Every  command,  argument,  and  symbol  in  the  source  must  be
separated from others by spaces, tabs, or a new line.

All  names  must be less than or equal to 16 characters  long  and
must begin with a letter or $ symbol.

Two versions of TURGRA are supplied:
	TURGRA.EXE produces screen graphics
	TURDEB.EXE produces a list of the actions that would result
	           from executing your source. This is  useful  for
	           debugging source files

-------------------------------------------------------------------
Comments
-------------------------------------------------------------------
Comments may be included in your programs by enclosing them in 
square brackets thus
    [this is a comment]

-------------------------------------------------------------------
Commands
-------------------------------------------------------------------

TURN n

Turns your turtle through n degrees.

POINT n

Sets the angle of movement of your turtle to n degrees.

PENUP

Raises the pen held by the turtle so that it will no longer  leave
a trail behind it.

PENDN

Lowers the pen held by the turtle so that it will begin to leave a
trail.

FORWARD n

Moves the turtle forward n pixels in the current direction.

FG n

Sets the foreground colour to a colour as follows

  0   BLACK,
  1   BLUE,
  2   GREEN,
  3   CYAN,
  4   RED,
  5   MAGENTA,
  6   BROWN,
  7   WHITE,
  8   GRAY,
  9   LIGHTBLUE,
  10  LIGHTGREEN,
  11  LIGHTCYAN,
  12  LIGHTRED,
  13  LIGHTMAGENTA,
  14  LIGHTYELLOW,
  15  BRIGHTWHITE


BG n

Sets  the backgound colour to one of the colours as specified  for
FG above.

CLS 

Clears  the  screen but does not affect the  position,  angle,  or
colour of the turtle.

GOTO x y

Positions the turtle at the x and y coordinates specified.

CIRCLE radius

Draws  a  circle centred at your current turtle  position  with  a
radius as specified.

ARC radius degrees

Draws  an  arc  centred  on  the  turtle's  current  position  and
beginning  at  the turtle's current angle.  the  degrees  argument
determines how long the arc will be.

WAIT

Waits for a key to be pressed

ELLIPSE xrad yrad

Draws  an  ellipse centred on the turtle's current  position.  The
xrad  argument determines how wide the ellipse will be whilst  the
yrad argument determines how tall the ellipse will be.

-------------------------------------------------------------------
Variables
-------------------------------------------------------------------

You may have up to 100 variables in your turtle program. Variables
are  created  with the ASSIGN command and may be used  wherever  a
number is required.

Commands to manipulate variables are:

ASSIGN var n

Assigns the number n to the variable var where var is the name  of
one of your variables. n may be negative.

ADD var n

Adds the number n to your variable.

SUB var n

Subtracts n from your variable.

MUL var n

Multiplies variable by n.

DIV var n

Div  sets  your var to the result of an integer  division  of  the
current value of your variable divided by n.

MOD var n

Mod  sets your variable to the result of taking modulus n  of  the
current value of your variable. For example 
If myvar holds 13 then
mod myvar 3
will set myvar to 1

GETX var

Sets variable to the current x coordinate of the turtle

GETY var

Sets variable to the current y coordinate of the turtle

GETANG var

Sets variable to the current angle of the turtle.

RAND var limit                

Sets var to a random number between 0 and (limit-1)
Limit should be between 1 and 32767.

POWN var pow

Raises variable to the powth power. Since variables are 
integers a result greater than 32767 becomes negative.

ROOTN var n

Sets var to the nth root of var. The contents of var are
automatically made positive. Variables are integers so
the result is rounded to the nearest integer. 

-------------------------------------------------------------------
Conditions
-------------------------------------------------------------------

TURGRA supports an IF THEN ELSE construct. The syntax is

( x op y ? action if true ! action if false )

x and y may be any number or variable.
op may be
=    tests for equality of x and y
<>   test whether x is not equal to y
<    tests whether x is less than y
>    tests whether x is greater than y

-------------------------------------------------------------------
Loops
-------------------------------------------------------------------

TURGRA supports a type of WHILE loop. The syntax is

{ x op y ? action if true }

The action if true clause will be executed until the condition  is
false.

-------------------------------------------------------------------
Subroutines
-------------------------------------------------------------------

You can define up to 100 subroutines. The syntax is

: subname action1 action2 ... actionn ;

You can use variables in subroutines but there is no other
provision for arguments to be passed to them.

SUBROUTINE DEFINITIONS MUST BE AT THE TOP OF THE FILE AND BEFORE
ANY DIRECT COMMANDS.

-------------------------------------------------------------------
Examples
-------------------------------------------------------------------

-------------------------------------------------------------------
CIRCLES
-------------------------------------------------------------------
: hex ASSIGN times 6 
  { times > 0 ?
    PENUP
    TURN 60
    FORWARD 50
    PENDN
    CIRCLE 50
    SUB times 1
  }
;
GOTO 320 190
POINT 90
BG 7
FG 10
hex
PENUP
TURN -90
FORWARD 50
FG 14
hex
PENUP
TURN -90
FORWARD 50
FG 13
hex
PENUP
TURN -90
FORWARD 50
FG 12
hex

-------------------------------------------------------------------
FLOWER
-------------------------------------------------------------------
: square ASSIGN times 4 
  { times > 0 ?
    FORWARD side 
    TURN 90
    SUB times 1
  } ;
: flower ASSIGN ang 0
  { ang < 365 ?
    POINT ang
    square
    ADD ang 30
  } ;
ASSIGN side 50
GOTO 160 236
flower
GOTO 480 236
flower
GOTO 320 118
flower
GOTO 320 354
flower

-------------------------------------------------------------------
RECTANGLE
-------------------------------------------------------------------
: rect ASSIGN times 4 ASSIGN side 0
  { times > 0 ?
    ASSIGN side times
    MOD side 2
    ( side = 0 
      ? FORWARD xside
      ! FORWARD yside
    )
    TURN 90
    SUB times 1
  }
;
ASSIGN xside 100
ASSIGN yside 200
rect

-------------------------------------------------------------------
Copyright
-------------------------------------------------------------------

This program was written by Nigel Salt. You may write to me at the
following address

25 Lower Station Rd
Crayford 
KENT
DA1 3PY
The copyright of this program belongs to me.

I am happy for it to be freely distributed providing that noone
makes a commercial gain from it. Any attempt to market my program
will be pursued in the courts.
