Our First Program Or An Old Chestnut

In this chapter we'll examine a rather classic program written in MUF. This program will send the text "Hello World!" to whoever runs the program. This example is listable at MUF101/HelloWorld (remember to list use: @list $examples/MUF101/HelloWorld). You can run the example by typing MUF101Ex1. The program is listed below with the line numbers shown:

( A simple hello world program )

: main

( First, we'll pop the unneeded argument string off the stack )

pop( s -- )

( Next, we will find out the player's dbref )

"me"match( s -- d )

( Then we'll send the "hello world" to the player )

"Hello World!"notify( d s -- )

;

The first, third, fifth, and seventh lines of this program are merely comments. The compiler ignores the comments which are there for the programmer(s) to easily understand what the program is doing. When commenting your own programs (and you should be commenting your programs!) pay attention to the usage of the parentheses. Every comment must begin with one and only one parenthesis and end with one and only parenthesis. They cannot overlap and you cannot use parentheses in your comments. Any overlaps will confuse the compiler and generate errors.

As we learned in the previous chapter, the ": main" on line 2 begins the definition of a word called "main". The definition of the word follows until we reach the semi-colon on line 9.

We learn three things from line four:

pop ( s -- )

First is the primitive word "pop". If you remember our "stack of paper" analogy, this is like taking the top piece of paper and throwing it away. "pop" removes the item on the top of the stack.

You may be wondering why we're removing an item from the stack before we've put anything on the stack. The MUF interpreter has put something on the stack for us. Anything that the user typed after the command that ran the program is in a single string on the stack when the program starts. Since our program does not need that string, we're simply removing it when the program starts.

So before the 'pop' the debug output (which includes what is on the stack) looks like this:

Debug> #509 4 ("") POP

And after:Debug> #509 6 () "me"

As you can see, an empty string between the parentheses has been removed. It is worth looking at the debug output briefly here. The database reference #509 is the database reference number of the program that is running. The number in between the reference and the stack is the line number of the program currently being executed. And after the stack is what 'comes next' So when we were on line 4, 'pop' was next, on line 6, "me" is next.

The last thing we learn from line four is that comments can be anywhere, as long as they're fully enclosed in parentheses. This particular comment is commenting on what is happening with the stack when the word "pop" is executed. Before, there is a string on the stack, represented by an s. After the word, which is represented by --, the string is gone, so there is nothing after the --.

We have the important parts of this program in lines 6 and 8. In line 6:

"me" match ( s -- d )

The first thing that happens here is that we push a string on to the top of the stack. Continuing our stack of paper analogy, we'd write "me" on a piece of paper and place it on top of our (currently empty) stack of paper.

Then we use the primitive word 'match'. Match removes the string on top of the stack and searches for a database item that matches that string. It begins by searching the player running the program, then the room they are in, and then follows with their environment by checking the room's parent, the parent's parent, and so on until reaches room #0. When it finds a match, it will push the database reference for that database item onto the stack.

It is important to understand that when a program uses 'me' as something to match, it will match the player that is using the program. So when you run this program, match will return the your database reference number.

Notice that the comment ( s -- d ) shows us what is happening on the stack. A string is removed and replaced with a database reference.

Finally, in line 8, we have our output:

"Hello World!" notify ( d s -- )

We first push the string "Hello World!" on to the stack. Then the primitive word 'notify' goes to work. It removes both the database reference and the string from the top of the stack. Using the database reference, it sends the string to the player represented by the database reference.

The stack before the notify looks like this:

(#555, "Hello World!")

And after it is empty again: ()

It is worthwhile to run the example program once or twice by typing "MUF101Ex1" or "MUF101Ex1 stufftobeignored" just so you can see the the operation and "Debug>" output yourself.