git @ Cat's Eye Technologies Befunge-93 / a9e6a20
Convert documentation from HTML to Markdown. --HG-- rename : doc/befunge93.html => doc/Befunge-93.markdown catseye 9 years ago
4 changed file(s) with 285 addition(s) and 294 deletion(s). Raw diff Collapse all Expand all
00 The Befunge-93 specification is not open-source (yet), but it is freely
11 redistributable unmodified for non-commercial purposes.
22
3 The contributed example sources are each copyrighted by their respective
3 The contributed Befunge-93 example sources are copyrighted by their respective
44 authors. Except where otherwise noted, they are not open-source works,
55 but their contributors' willingness to allow them to be included in this
66 distribution implies that they are all freely redistributable unmodified for
7 non-commercial purposes.
7 non-commercial purposes. If you wish to base your next best-selling novel
8 on one of them, you should seek out and contact its author for permission
9 first. There is one exception: all Befunge-93 example sources in this
10 distribution which were written by Chris Pressey is in the public domain.
811
912 The source code for the reference interpreter and supporting tools (in the
1013 `src` subdirectory) is covered under the following BSD-style license:
00 Welcome to the NEW Befunge-93 Reference Distribution
11 ====================================================
2
3 Since `bef` is a reference implementation (so far as it goes) of Befunge-93,
4 we saw fit to once again combine the specification and implementation into a
5 single distribution.
6
7 About Befunge-93
8 ----------------
9
10 Befunge-93 is an esoteric programming language where the program exists in a
11 two-dimensional grid of cells, where each cell contains a single instruction,
12 and execution can proceed in any cardinal direction across this grid -- not
13 just left-to-right, but also right-to-left, top-to-bottom, and bottom-to-top.
14
15 For more information, see the Befunge-93 specification in the `doc` directory.
216
317 Contents
418 --------
519
620 * `README.markdown`: these post-modernist existential rants
721 * `LICENSE`: a bedtime story written to give your lawyer sweet dreams
8 * `doc/befunge93.html`: the specification for Befunge-93, such as it is
22 * `doc/Befunge-93.markdown`: the specification for Befunge-93, such as it is
923 * `src/bef.c`: Befunge-93 reference interpreter/debugger v2.22 source code
1024 * `src/bef2c.c`: Befunge-93 to ANSI C compiler v0.94 source code
1125 * `src/befprof.c`: Befunge-93 profiler v0.94 source code
0 Befunge-93 Documentation
1 ========================
2
3 *A Twisted, Deranged Programming Language in the Tradition of
4 [brainfuck][] and [FALSE][]*
5
6 [brainfuck]: http://esolangs.org/wiki/Brainfuck
7 [FALSE]: http://esolangs.org/wiki/FALSE
8
9 Chris Pressey, Cat's Eye Technologies
10 *Original document September, 1993*
11 *Updated December, 1996*
12 *Updated Yet Again September, 2004*
13
14 ### The Basics of Befunge-93 ###
15
16 Most likely the most unique element of Befunge-93 programming is the
17 Program Counter (PC.) In almost all computer programming languages, the
18 program counter is continually moving forward through the program,
19 occassionally jumping to another spot in the code (but continuing
20 forward thereafter, nonetheless.)
21
22 The PC in Befunge-93, however, is subject to different rules. It may go
23 *forward, backward, left, or right*. A Befunge-93 program is treated as
24 an 80x25 torus (a page which wraps around on the edges) of ASCII text.
25 Certain commands change the direction of the progress of the PC. By
26 default, the PC points to the upper-left corner of the program, and is
27 oriented to travel left-to-right.
28
29 Each command in Befunge-93 is a single character, as is the largest data
30 unit that can be specified in the program source; Befunge-93 programs
31 have a maximum size of 80x25 total commands and data bytes. There are no
32 run-time variables, only a single run-time stack. Befunge-93 programs
33 allow for self-modification. Due to the 2-dimensional nature of the PC,
34 they also allow for some extremely quirky code.
35
36 ### The Stack ###
37
38 Something like Forth and PostScript, Befunge-93 supports a LIFO, Reverse
39 Polish Notation (RPN or *postfix*) stack of signed long integers (that
40 is, each cell of the stack can hold as much as a C language
41 `signed long int` on the same platform.) The act of placing a value on
42 the stack is called *pushing*, and the act of taking a value off the
43 stack is called *popping*. The digits from `0` to `9` are valid
44 Befunge-93 commands which push their respective values onto the stack. A
45 double quote `"`, when encountered, toggles *stringmode*, and while
46 stringmode is active, all character cells will have their ASCII value
47 pushed onto the stack until another `"` is located.
48
49 There are a few basic calculation commands:
50
51 - `+` addition
52 - `-` subtraction
53 - `/` integer division
54 - `*` multiplication
55 - `%` modulo
56 - `!` logical negation
57
58 These are explained in greater detail in the Commands section.
59
60 In order to push a number greater than 9 on the stack, calculations must
61 be done with numbers less than or equal to 9. In any other language this
62 would be a pain. In Befunge-93 it is a joy. For example, to push '123'
63 onto the stack, one might push 9, then 9, then multiply (leaving 81),
64 then push 7, then 6, then multiply (leaving 81 and 42,) then add
65 (leaving 123.) In Befunge, this would look something like :
66
67 99*76*+
68
69 This is, of course, assuming that the PC starts at or before the first
70 `9` and is working towards the right. If this snippet represents a
71 entire Befunge-93 program, this assumption is correct: the PC starts at
72 the upper-left of the torus and is initially oriented to execute
73 rightward.
74
75 NB. If the stack is be empty when you pop something off, be warned that
76 this will *not* generate an underflow! It will simply push a 0 value
77 onto the stack. Hope you can live with it!
78
79 ### The Program Counter in Detail ###
80
81 There are 5 commands which unconditionally control the PC direction:
82 `>`, `<`, `v`, `^`, and `?`. `>` makes the PC travel to the right; `<`
83 to the left; `v` down; `^` up; and `?` in a *random* direction. So, the
84 following example is an infinite loop:
85
86 ><
87
88 As is:
89
90 >v
91 ^<
92
93 As is:
94
95 >v>v
96 >^
97 ^ <
98
99 Note that ` ` (space) is a null command which does nothing.
100
101 Should the PC encounter the 'edge' of the program, such as if you were
102 to try to execute:
103
104 <
105
106 The PC will 'wrap around' to the other 'edge' of the program. This
107 example, then, is an infinite loop as well.
108
109 ### Decision Making ###
110
111 The standard 'if' statement in Befunge-93 is either `_` or `|`,
112 depending on how you want to branch. Both of these instructions pop a
113 value off the stack and check to see if it is true (non-zero,) and
114 change the direction of the PC accordingly:
115
116 - `_` acts like `<` if the value is true or `>` if it is false; and
117 - `|` acts like `^` if the value is true or `v` if it is false.
118
119 'While' loops can be made by sticking an 'if' in an infinite loop. For
120 example,
121
122 >_@
123
124 (This program fragment pops all of the non-zero values off the stack,
125 and the first zero value, then exits [`@` is the exit command.])
126
127 ### Input ###
128
129 The `&` (ampersand) command will get a numeric value (in decimal) from
130 the standard input and push it on the stack. `~` (tilde) will get the
131 next ASCII character from standard input and push it on the stack.
132
133 For example,
134
135 &,
136
137 ...prints out "A" if the user types "65 ", and...
138
139 ~.
140
141 ...prints out "65 " if the user types "A".
142
143 ### Output ###
144
145 The `.` command will pop a value off the stack and output it as a
146 decimal integer, followed by a space, somewhat like Forth. `,` will pop
147 a value, interpret it as the ASCII value of a character, and output that
148 character (not followed by a space.)
149
150 For example,
151
152 665+*1-,
153
154 ...prints out ASCII 65 ("A".), and...
155
156 665+*1-.
157
158 ...prints out "65 ".
159
160 ### Special Commands ###
161
162 `#` is the 'bridge' command... it causes the next command which would
163 normally be executed to be skipped over, and not executed. For example,
164
165 >123...@
166
167 would output "3 2 1 ", but
168
169 >123#...@
170
171 would output "3 2 " with one of the '.''s being skipped. Judicious use
172 of `#` can make for very interesting code!
173
174 `:` is the duplication command. It makes a copy of the top element of
175 the stack. This is useful, as demonstrated in the following program:
176
177 v.<>:| @
178
179 This program makes duplicates of each value on the stacked, which is
180 checked, and if non-zero, printed.
181
182 `$` pops a value off the stack, but does nothing with it. So,
183
184 123.$.@
185
186 results in "3 1 ".
187
188 `\` swaps the top two elements of the stack. So,
189
190 123\...@
191
192 results in "2 3 1 ".
193
194 `` ` `` (back-quote) is the 'greater-than' command. It compares the top
195 two values on the stack, and returns '1' if the first is greater than
196 the second. For example,
197
198 65`.
199
200 ...outputs "1 " and...
201
202 25`.
203
204 ...outputs "0 ".
205
206 ### Self-Modification ###
207
208 The last two commands that need to be explained are the ones that allow
209 you to examine and change the contents of the torus where the program is
210 stored. This 'playfield' can be used for auxilliary storage when the
211 stack alone will not suffice, but keep in mind that it also contains the
212 running program.
213
214 The `g` command examines the contents of the playfield. It pops a *y*
215 coordinate off the stack, then an *x* coordinate. It pushes the value
216 found at (*x*, *y*) onto the stack. If the thing at (*x*, *y*) is a
217 Befunge-93 instruction, the value pushed will be the ASCII value of that
218 character. From the point of view of the program text, *x* determines
219 the column and *y* determines the row; (0, 0) refers to the first
220 (leftmost) column and the first (topmost) row of the program source.
221
222 The `p` command alters the contents of the playfield. It pops a *y*
223 coordinate off the stack, then an *x* coordinate, and then a value. It
224 places the value into the torus at (*x*, *y*). If the program, at some
225 later point, executes the instruction at (*x*, *y*), it will be the
226 interpreted as the Befunge instruction in the ASCII character set with
227 the same value as was put there with the `p` instruction.
228
229 ### Appendix A. Command Summary ###
230
231 COMMAND INITIAL STACK (bot->top)RESULT (STACK)
232 ------- ------------- -----------------
233 + (add) <value1> <value2> <value1 + value2>
234 - (subtract) <value1> <value2> <value1 - value2>
235 * (multiply) <value1> <value2> <value1 * value2>
236 / (divide) <value1> <value2> <value1 / value2> (nb. integer)
237 % (modulo) <value1> <value2> <value1 mod value2>
238 ! (not) <value> <0 if value non-zero, 1 otherwise>
239 ` (greater) <value1> <value2> <1 if value1 > value2, 0 otherwise>
240 > (right) PC -> right
241 < (left) PC -> left
242 ^ (up) PC -> up
243 v (down) PC -> down
244 ? (random) PC -> right? left? up? down? ???
245 _ (horizontal if) <boolean value> PC->left if <value>, else PC->right
246 | (vertical if) <boolean value> PC->up if <value>, else PC->down
247 " (stringmode) Toggles 'stringmode'
248 : (dup) <value> <value> <value>
249 \ (swap) <value1> <value2> <value2> <value1>
250 $ (pop) <value> pops <value> but does nothing
251 . (pop) <value> outputs <value> as integer
252 , (pop) <value> outputs <value> as ASCII
253 # (bridge) 'jumps' PC one farther; skips
254 over next command
255 g (get) <x> <y> <value at (x,y)>
256 p (put) <value> <x> <y> puts <value> at (x,y)
257 & (input value) <value user entered>
258 ~ (input character) <character user entered>
259 @ (end) ends program
260
261 ### The People Who Helped Make the Dream Reality ###
262
263 Special thanks to Curtis Coleman, Jason Goga, Kalyna Zazelenchuk, Shawn
264 Vincent, Mike Veroukis, Urban Müller, and Wouter van Oortmerssen.
+0
-291
doc/befunge93.html less more
0 <html><head><title>Befunge-93 Documentation</title></head>
1 <body>
2 <center><H1>Befunge-93 Documentation</H1>
3 <hr><font size=+1>
4 <i>Twisted, Deranged Programming Language in the
5 Tradition of </i><a href="http://www.muppetlabs.com/~breadbox/bf/">Brainf*ck</a>
6 <i>and</i> <a href="http://wouter.fov120.com/false/">False</a></font><p>
7 Chris Pressey, Cat's Eye Technologies<br>
8 <i>Original document September, 1993</i><br>
9 <i>Updated December, 1996</i><br>
10 <i>Updated Yet Again September, 2004</i><br>
11 </center>
12 <h3>The Basics of Befunge-93</h3>
13
14 <p>Most likely the most unique element of Befunge-93 programming is the
15 Program Counter (PC.) In almost all computer programming languages,
16 the program counter is continually moving forward through the program,
17 occassionally jumping to another spot in the code (but continuing
18 forward thereafter, nonetheless.)</p>
19
20 <p>The PC in Befunge-93, however, is subject to different rules. It
21 may go <i>forward, backward, left, or right</i>. A Befunge-93 program
22 is treated as an 80x25 torus (a page which wraps around on the edges)
23 of ASCII text. Certain commands change the direction of the progress
24 of the PC. By default, the PC points to the upper-left
25 corner of the program, and is oriented to travel left-to-right.</p>
26
27 <p>Each command in Befunge-93 is a single character, as is the largest
28 data unit that can be specified in the program source; Befunge-93 programs
29 have a maximum size of 80x25 total commands and data bytes. There are
30 no run-time variables, only a single run-time stack. Befunge-93 programs
31 allow for self-modification. Due to the 2-dimensional nature of the PC,
32 they also allow for some extremely quirky code.</p>
33
34 <h3>The Stack</h3>
35
36 <p>Something like Forth and PostScript, Befunge-93 supports a LIFO,
37 Reverse Polish Notation (RPN or <i>postfix</i>) stack of signed long
38 integers (that is, each cell of the stack can hold as much as a C language
39 <code>signed long int</code> on the same platform.) The act of
40 placing a value on the stack is called
41 <i>pushing</i>, and the act of taking a value off the stack is
42 called <i>popping</i>. The digits from <code>0</code> to <code>9</code> are valid
43 Befunge-93 commands which push their respective values
44 onto the stack. A double quote <code>"</code>, when encountered, toggles
45 <i>stringmode</i>, and while stringmode is active, all character
46 cells will have their ASCII value
47 pushed onto the stack until another <code>"</code> is located.</p>
48
49 <p>There are a few basic calculation commands:
50 <ul>
51 <li><code>+</code> addition</li>
52 <li><code>-</code> subtraction</li>
53 <li><code>/</code> integer division
54 <li><code>*</code> multiplication
55 <li><code>%</code> modulo
56 <li><code>!</code> logical negation
57 </ul>
58 These are explained in greater detail in the Commands section.</p>
59
60 <p>In order to push a number greater than 9 on the stack, calculations
61 must be done with numbers less than or equal to 9. In any other
62 language
63 this would be a pain. In Befunge-93 it is a joy. For example, to
64 push '123' onto the stack, one might push 9, then 9, then multiply
65 (leaving 81), then push 7, then 6, then multiply (leaving 81 and
66 42,) then add (leaving 123.) In Befunge, this would look something
67 like :
68 <ul>
69 <code>99*76*+</code>
70 </ul>
71 This is, of course, assuming that the PC starts at or
72 before the first <code>9</code> and is working towards the right.
73 If this snippet represents a entire Befunge-93 program, this
74 assumption is correct: the PC starts at the upper-left of the
75 torus and is initially oriented to execute rightward.</p>
76
77 <p>NB. If the stack is be empty when you pop something off,
78 be warned that this will <i>not</i> generate an underflow! It will
79 simply push a 0 value onto the stack. Hope you can live with it!</p>
80
81 <h3>The Program Counter in Detail</h3>
82
83 <p>There are 5 commands which unconditionally control the PC direction:
84 <code>&gt;</code>, <code>&lt;</code>, <code>v</code>, <code>^</code>,
85 and <code>?</code>. <code>&gt;</code> makes the PC travel to the right;
86 <code>&lt;</code> to the left; <code>v</code> down; <code>^</code> up;
87 and <code>?</code> in a <i>random</i> direction. So, the following
88 example is an infinite loop:
89 <ul>
90 <code>&gt;&lt;</code>
91 </ul>
92 As is:
93 <ul>
94 <code>&gt;v<br>^&lt;</code>
95 </ul>
96 As is:
97 <ul>
98 <code>&gt;v&gt;v<br>&nbsp;&gt;^<br>^&nbsp;&nbsp;&lt;</code>
99 </ul>
100 Note that <code>&nbsp;</code> (space) is a null command which does nothing.</p>
101
102 <p>Should the PC encounter the 'edge' of the program, such as if
103 you were to try to execute:
104 <ul>
105 <code>&lt;</code>
106 </ul>
107 The PC will 'wrap around' to the other 'edge' of the program. This example,
108 then, is an infinite loop as well.</p>
109
110 <h3>Decision Making</h3>
111
112 <p>The standard 'if' statement in Befunge-93 is either
113 <code>_</code> or <code>|</code>, depending
114 on how you want to branch. Both of these instructions
115 pop a value off the stack and check to
116 see if it is true (non-zero,) and change the direction of the PC
117 accordingly:
118
119 <ul>
120 <li><code>_</code> acts like <code>&lt;</code> if the value is true or <code>&gt;</code> if it is false; and</li>
121 <li><code>|</code> acts like <code>^</code> if the value is true or <code>v</code> if it is false.</li>
122 </ul>
123 </p>
124
125 <p>'While' loops can be made by sticking an 'if' in an infinite loop.
126 For example,
127 <ul>
128 <code>&gt;_@</code>
129 </ul>
130 (This program fragment pops all of the non-zero values off the
131 stack, and the first zero value, then exits [<code>@</code> is the exit command.])</p>
132
133 <h3>Input</h3>
134
135 <p>The <code>&amp;</code> (ampersand) command will get a numeric value (in decimal)
136 from the standard input and
137 push it on the stack. <code>~</code> (tilde) will get the next ASCII character from
138 standard
139 input and push it on the stack.</p>
140
141 <p>For example,
142 <ul>
143 <code>&,</code>
144 </ul>
145 ...prints out "A" if the user types "65 ", and...
146 <ul>
147 <code>~.</code>
148 </ul>
149 ...prints out "65 " if the user types "A".</p>
150
151 <h3>Output</h3>
152
153 <p>The <code>.</code> command will pop a value off the stack and output it as
154 a decimal integer, followed by a space, somewhat like Forth. <code>,</code> will
155 pop a value, interpret it as the ASCII value of a character, and output that character
156 (not followed by a space.)</p>
157
158 <p>For example,
159
160 <ul>
161 <code>665+*1-,</code>
162 </ul>
163 ...prints out ASCII 65 ("A".), and...
164 <ul>
165 <code>665+*1-.</code>
166 </ul>
167 ...prints out "65 ".</p>
168
169 <h3>Special Commands</h3>
170
171 <p><code>#</code> is the 'bridge' command... it causes the next command which would
172 normally be executed to be skipped over, and not executed. For
173 example,
174
175 <ul>
176 <code>&gt;123...@</code>
177 </ul>
178
179 would output "3 2 1 ", but
180
181 <ul>
182 <code>&gt;123#...@</code>
183 </ul>
184
185 would output "3 2 " with one of the '.''s being skipped. Judicious
186 use of <code>#</code> can make for very interesting code!</p>
187
188 <p><code>:</code> is the duplication command. It makes a copy of the top element
189 of the stack. This is useful, as demonstrated in the following program:
190
191 <ul>
192 <code>v.&lt;&gt;:| @</code>
193 </ul>
194
195 This program makes duplicates of each value on the stacked, which is checked,
196 and if non-zero, printed.</p>
197
198 <p><code>$</code> pops a value off the stack, but does nothing with it. So,
199
200 <ul>
201 <code>123.$.@</code>
202 </ul>
203
204 results in "3 1 ".</p>
205
206 <p><code>\</code> swaps the top two elements of the stack. So,
207
208 <ul>
209 <code>123\...@</code>
210 </ul>
211
212 results in "2 3 1 ".</p>
213
214 <p><code>`</code> (back-quote) is the 'greater-than' command. It compares the top two
215 values on the stack, and returns '1' if the first is greater than the
216 second. For example,
217
218 <ul>
219 <code>65`.</code>
220 </ul>
221
222 ...outputs "1 " and...
223
224 <ul>
225 <code>25`.</code>
226 </ul>
227
228 ...outputs "0 ".</p>
229
230 <h3>Self-Modification</h3>
231
232 <p>The last two commands that need to be explained are the ones that allow you to
233 examine and change the contents of the torus where the program is stored. This
234 'playfield' can be used for auxilliary storage when the stack alone will not suffice,
235 but keep in mind that it also contains the running program.</p>
236
237 <p>The <code>g</code> command examines the contents of the playfield.
238 It pops a <i>y</i> coordinate off the stack, then an <i>x</i> coordinate. It pushes the
239 value found at (<i>x</i>, <i>y</i>) onto the stack. If the thing at (<i>x</i>, <i>y</i>)
240 is a Befunge-93 instruction, the value pushed will be the ASCII value of that
241 character. From the point of view of the program text, <i>x</i> determines
242 the column and <i>y</i> determines the row; (0, 0) refers to the first (leftmost)
243 column and the first (topmost) row of the program source.</p>
244
245 <p>The <code>p</code> command alters the contents of the playfield.
246 It pops a <i>y</i> coordinate off the stack, then an <i>x</i> coordinate, and then
247 a value. It places the value into the torus at (<i>x</i>, <i>y</i>). If the program,
248 at some later point, executes the instruction at (<i>x</i>, <i>y</i>), it will be the
249 interpreted as the Befunge instruction in the ASCII character set with the same
250 value as was put there with the <code>p</code> instruction.</p>
251
252 <h3>Appendix A. Command Summary</h3>
253
254 <pre>COMMAND INITIAL STACK (bot->top)RESULT (STACK)
255 ------- ------------- -----------------
256 + (add) &lt;value1&gt; &lt;value2&gt; &lt;value1 + value2&gt;
257 - (subtract) &lt;value1&gt; &lt;value2&gt; &lt;value1 - value2&gt;
258 * (multiply) &lt;value1&gt; &lt;value2&gt; &lt;value1 * value2&gt;
259 / (divide) &lt;value1&gt; &lt;value2&gt; &lt;value1 / value2&gt; (nb. integer)
260 % (modulo) &lt;value1&gt; &lt;value2&gt; &lt;value1 mod value2&gt;
261 ! (not) &lt;value&gt; &lt;0 if value non-zero, 1 otherwise&gt;
262 ` (greater) &lt;value1&gt; &lt;value2&gt; &lt;1 if value1 &gt; value2, 0 otherwise&gt;
263 &gt; (right) PC -&gt; right
264 &lt; (left) PC -&gt; left
265 ^ (up) PC -&gt; up
266 v (down) PC -&gt; down
267 ? (random) PC -&gt; right? left? up? down? ???
268 _ (horizontal if) &lt;boolean value&gt; PC-&gt;left if &lt;value&gt;, else PC-&gt;right
269 | (vertical if) &lt;boolean value&gt; PC-&gt;up if &lt;value&gt;, else PC-&gt;down
270 " (stringmode) Toggles 'stringmode'
271 : (dup) &lt;value&gt; &lt;value&gt; &lt;value&gt;
272 \ (swap) &lt;value1&gt; &lt;value2&gt; &lt;value2&gt; &lt;value1&gt;
273 $ (pop) &lt;value&gt; pops &lt;value&gt; but does nothing
274 . (pop) &lt;value&gt; outputs &lt;value&gt; as integer
275 , (pop) &lt;value&gt; outputs &lt;value&gt; as ASCII
276 # (bridge) 'jumps' PC one farther; skips
277 over next command
278 g (get) &lt;x&gt; &lt;y&gt; &lt;value at (x,y)&gt;
279 p (put) &lt;value&gt; &lt;x&gt; &lt;y&gt; puts &lt;value&gt; at (x,y)
280 & (input value) &lt;value user entered&gt;
281 ~ (input character) &lt;character user entered&gt;
282 @ (end) ends program</pre>
283
284 <h3>The People Who Helped Make the Dream Reality</h3>
285
286 <p>Special thanks to Curtis Coleman, Jason Goga, Kalyna Zazelenchuk, Shawn Vincent,
287 Mike Veroukis, Urban Mueller, and Wouter van Oortmerssen.</p>
288
289 </body>
290 </html>