tanks

forf.md

  1The Forf Language
  2=================
  3
  4Welcome to Forf!  *PUNCH*
  5
  6Forf is a simple, postfix, stack-based programming language.  It was
  7designed to be used as an extension language for games.  Forf programs
  8run in fixed size memory and can be time-constrained.
  9
 10Forf was heavily influenced by the PostScript programming language.
 11
 12
 13About Stacks
 14============
 15
 16Central to the operation of Forf is the notion of a stack.  A stack is a
 17last-in-first-out (LIFO) list, like a stack of dishes.  Items can be
 18"pushed" onto the top of the stack, or "popped" off the top of the stack. 
 19Items may only be pushed or popped, meaning the top stack element is the
 20only element that can be accessed.  To get to the third item down in a
 21stack, it is necessary to first pop two items off.
 22
 23
 24Data Types
 25==========
 26
 27There are three data types in Forf: Integers, Substacks, and Procedures.
 28
 29
 30Integers
 31--------
 32
 33Integers are stored as the "long" type and have whatever boundaries the
 34host CPU and C compiler enforce.  They may be entered in decimal (12),
 35octal (014), or hex (0xC), and may be positive or negative.
 36
 37The following are valid integers:
 38
 39* 58
 40* -58
 41* 0x3A (hex)
 42* 072  (octal)
 43
 44
 45Procedures
 46----------
 47
 48Data is read one by one from your program and either pushed onto the
 49data stack (integers and substacks) or evaluated (procedures).  When a
 50procedures is evaluated, it pops zero or more elements off the data
 51stack, does something with them, and then pushes zero or more elements
 52back onto the stack.
 53
 54The "+" procedure, for instance, pops two values, adds them, and pushes
 55the result.  The following data stack:
 56
 57    [bottom] 58 88 5 [top]
 58
 59When given to the "+" procedure, would yield:
 60
 61    [bottom] 58 93 [top]
 62
 63
 64Substacks
 65---------
 66
 67Substacks are groups of data on the data stack.  They are used only by
 68the "if" and "ifelse" procedures, and are denoted by "{" (start
 69substack) and "}" (end substack).  Substacks may be nested.
 70
 71The following will result in 58 on the top of the stack:
 72
 73    5 8 < { 50 8 + } { 50 8 - } ifelse
 74
 75
 76Comments
 77--------
 78
 79Anything inside parenthesis is ignored by the forf interpreter. 
 80
 81
 82
 83Built-in Procedures
 84===================
 85
 86The following procedures are built in to Forf.  Since the language was
 87designed to be extended, your game provides additional procedures.
 88
 89
 90Unary Operations
 91----------------
 92
 93These procedures pop one value and push one.
 94
 95* `x ~`   (bitwise invert)
 96* `x !`   (logical not)
 97* `x abs` (absolute value)
 98
 99
100Binary Operations
101-----------------
102
103The following procedures pop two values and push one.  They work as in
104an RPN calculator, meaning that `8 4 /` yields `2`.  
105
106* `y x +`  (y + x)
107* `y x -`  (y - x)
108* `y x *`  (y * x)
109* `y x /`  (y / x)
110* `y x %`  (y modulo x)
111* `y x &`  (y and x)
112* `y x |`  (y or x)
113* `y x ^`  (x xor x)
114* `y x <<` (y shifted left by x)
115* `y x >>` (y shifted right by x)
116
117
118Comparison
119----------
120
121These procedures pop two numbers and compare them, pushing `1` if the
122comparison is true, `0` if false.  For instance, `5 3 >` yields `1`.
123
124* `y x >`  (y greater than x)
125* `y x >=` (y greater than or equal to x)
126* `y x <`  (y less than x)
127* `y x <=` (y less than or equal to x)
128* `y x =`  (y equal to x)
129* `y x <>` (y not equal to x)
130
131
132Conditional Procedures
133----------------------
134
135* `x { i ... } if`                (if x, evaluate i)
136* `x { i ... } { e ... } ifelse`  (if x, evaluate i, otherwise evaluate e)
137
138
139Stack Manipulation
140------------------
141
142* `x pop`    (discard x)
143* `x dup`    (duplicate x)
144* `y x exch` (exchange x and y on the stack)
145
146
147Memory
148------
149
150Your game may provide you with one or more memory slots.  These are like
151variables in other languages, and may persist across invocations of your
152program.
153
154* `y x mset` (store y in slot x)
155* `x mget`   (retrieve value in slot x)
156
157
158Examples
159========
160
161Compute 58²:
162
163    58 58 *
164
165Compute 58³:
166
167    58 58 58 * *
168
169Another way to compute 58³:
170
171    58 dup dup * *
172
173
174The ifelse example, which does a comparison and puts 58 on the stack:
175
176    5 8 < { 50 8 + } { 50 8 - } ifelse
177
178Another way to do that:
179
180    50 5 8 < { 8 + } { 8 - } ifelse
181
182Yet another way:
183
184    50 8 5 8 < { + } { - } ifelse
185
186Is memory slot 3 greater than 100?
187
188    3 mget 100 >
189
190Given x, if x² is greater than 100 yield x², otherwise 0:
191
192    dup dup * 100 > { dup * } { pop 0 } ifelse
193
194Another way to do the same thing:
195
196    dup * dup 100 < { pop 0 } if
197
198Given coordinates (x, y) on the stack, is the distance to (x, y) less
199than 88?  This compares x²+y² against 88².
200
201    dup * exch dup * + 88 88 * <
202
203Perform different actions given some number between 0 and 3:
204
205    dup 0 = { action0 } if
206    dup 1 = { action1 } if
207    dup 2 = { action2 } if
208    dup 3 = { action3 } if
209    pop
210
211