Welcome

Welcome to the world of Funge. If you are new to Funge, then this tutorial is for you. This tutorial will teach you all the capabilites of Funge in general and Rc/Funge-98 in particular. This tutorial makes no assumptions about your programming skill and is therefore good for even the beginning programmer. All you need is a desire to learn this unique language.

Prerequisits

In order to actually do the examples contained within this documents you will need a basic text editor as well as a Funge-98 compatable interpreter. Any Funge-98 interpreter should do for most of the examples in this tutorial, but there will be some more advanced topics that will require Rc/Funge-98.

Most Funge interpreters require the program to be created using a standard text editor, programs like Microsoft Word put all kinds of extra codes into the file and will not be suitable for input files for Funge intrpreters. On Windows platforms, notepad will create files in the correct format, for Unix, vi works nicely.

Hello World

Most people when they learn a new computer language, the first thing they try is the classic "Hello World" program. So lets go ahead and try it:

"dlrow olleh"bk,@

At first look, this looks very confusing, but by the end of this tutorial you will understand exactly what this program is doing. For now just bask in the glory of seeing your first Funge program run.

First Steps: Working with numbers

It is time to take our first steps into actually learning how to program in Funge. First, all commands in Funge are a single character! Each printable ascii character from ! to ~ all have a function within the Funge language. A program consists of combining the function characters together to do something useful.

Next it is important to know what an IP or Instruction Pointer is and what it does. The IP for a given program is always located at the next instruction to be executed. During each cycle of the Funge interpreter, the instruction pointed to by the IP will be retrieved from Funge-space and executed. The IP will then be moved forward to the next instruction.

The next important concept to understand is the stack. Each instruction pointer has a stack associated with it. The stack is a location where temperary data can be stored. The data on the stack is available in a last in first out mode, meaning the last item that is pushed onto the stack, will the first item popped off of it.

Lets start with a really simple program:

5.@

When this program starts the IP will be pointing at the '5', since it is the first character on the first line of the program, this is always where the IP will start from. An important distinction between Funge and other languages, that 5 does NOT represent the number 5! It is actually a command! In this case this command will take the number 5 and push it onto the stack. the Commands: 0,1,2,3,4,6,7,8,9 work in a similar fashion, each pushing the respective number on the stack

After executing the 5 command the IP will be moved forward to point at the next instruction, the . instruction. A quick note about the movement of the IP. The IP has a delta associated with it that tells it how to move. When a program first starts the delta for an IP will set it to move left to right.

The next instruction to be executed is now the . instruction. This command will take the top value of the stack and print it out as a number. Since the 5 instruction put a 5 onto the stack, the . command will take the number 5 off of the stack, leaving it empty, and print out its value.

The final command is the @ command. This command terminates the execution of an IP. For now, think of this command as being the end of the program and will cause the Funge intrpeter to exit

Now that you have had the explanation for the program, try it out on your Funge interpreter. What do you expect to see? After running it, did you get what you expected? If not, then reread this section.

Lets try another program:

25.@

Before running this, try to predict what it will do, then run the program before continuing to read

Did you predict correctly? If so, then you had a solid grasp of the last section. If you did not predict correctly, then reread the last section and see if you can see why the program did what it did.

Remember each character is a command that is separate from all other commands being executed, so the 2 and the 5 are separate commands and execute independently, so first the 2 command executes putting the number 2 on the stack, then the 5 command executes to put the number 5 on the stack. So 2 separate numbers were pushed, NOT the number 25, therefore the . command only printed the top of the stack, the 5.

Now I am sure you have a question, if the 0 through 9 commands each put their numbers on the stack independently, how do you get other numbers?

The answer is: math

By using Funge's mathematics capabilites we can build the numbers that we need. So if you really did want 25 on the stack, try this program:

55*.@

Running this program will print 25 as the answer. the only new command here is the * command. This command will take the top 2 values on the stack and multiply them together and then take the answer and push it back onto the stack. Note, the * will remove both 5s from the stack in order to do its work. See how we got the 25 now? Two 5s were pushed onto the stack and then the multiply * command was executed, taking both of the 5s off and multipying them: 5 times 5 equals 25. The answer is then put back onto the stack for the the . to print.

Funge supports the 4 basic math functions: +, -, *, and /. Give these a try using your own programs to generate different numbers

Look at this program:

555**.@

Try to predict what this program will do before running it, did you get the result you expected? If so, then good for you! You have a good grasp on how to create any number within Funge.

An important point is that the mathematical functions do NOT need to be directly next to the numbers they are going to work on. Remember, they work from the stack. So, the 3 5 commands place 3 separate 5s on the stack, then the first * will remove 2 of the 5s, leaving 1 behind, performing the multiplication to get 25 and then put it back on the stack. Now there are 2 numbers still on the stack, the first 5 and the 25 from the first * command. Now the second * command will take the 25 and 5 off the stack and multiply them together to create 125, which is then put back on the stack. The rest you know.

This concludes part 1 of the Funge-98 tutorial. Use what you have learned and write several Funge programs to create various numbers. Part 2 will give some additional instruction on how to create and manipulate numbers and introduce you to character data within Funge

Commands learned in this part:
Command What it does
0Push the number 0 onto the stack
1Push the number 1 onto the stack
2Push the number 2 onto the stack
3Push the number 3 onto the stack
4Push the number 4 onto the stack
5Push the number 5 onto the stack
6Push the number 6 onto the stack
7Push the number 7 onto the stack
8Push the number 8 onto the stack
9Push the number 9 onto the stack
+Add the top 2 numbers on the stack
-Subtract the top 2 number on the stack
*Multiply the top 2 numbers on the stack
/Divide the top 2 numbers on the stack
.Print the top value on the stack as a number
@End program