Notes about programming, volume 1

Functions(1).

The layout of a function is:

[static] <function_name>([<var_name>[,<var_name>][,ect.]]) {
  <body>
}

(Things between [] are optional, that is, they are not always needed. The ,ect.
means that there can be an infinite number of <var_name>'s).

For example:

set_name(str) {
  name=str;
}

Here the <function_name> is 'set_name', the <var_name> is 'str' and the <body>
is 'name=str;'. The <function_name> needs to be unique in one file. Usually the
<var_name> is the type of the variable: if it is supposed to be a string, the
name is 'str' or 'str1', an object is 'obj' or 'obj1' and an integer is 'i' or
'i1' (don't use int here, because that is a reserved command). The variables
thus defined needn't be defined anymore within the function, and can be used
throughout the function (but not outside of it). The <body> is a piece of 
code, just like code you would normally use in your program. The [static] is 
only used in very special cases, and is not very important.

Functions are used for a number of different purposes:
1) To allow the code within the function to be used from different places in
   the program.
2) To make clear what a specific piece of code is supposed to do.
3) To make it possible for other objects to access this object.

Calling functions.

The layout of a function call is:

[<var_name> =] <function_name>([<expr>[,<expr>][,ect.]]);

For example:

set_name("lemon");

<var_name> and <function_name> still mean the same here, and <expr> is an
expression.

Return.

The return statement within the <body> will stop the function, and will resume
execution of the program on the line after the functioncall. When the return
statement is followed by an expression, this expression will be 'returned',
that is, the variable defined in the [<var_name> =] in the call will get the
same value as the result of the expression in the return. Example:

Definition of the function:

query_name() {
  return name;
}

Call of the function:

my_name=query_name();

If one wants to return more than one value from a function, the most common
solution is to make the variables 'common', that is, put the definition of
these variables at the beginning of the sourcecode. Then they will have their
value everywhere, inside and outside a function.

Calling function from other objects.

It is possible to call functions inside other objects. There are a few methods
of doing this:

[<var_name> =] <objexpr> -> <function_name>([<expr>[,<expr>][,ect.]]);

The new thing here is the '<objexpr> ->' construction. The objexpr is an
expression that directs to the object containing the function you want to
call. No error will be displayed if there is no function in that object, only
0 will be returned. The <objexpr> can have two types of variables: an object,
this is the object in which the function will be called, or a string, which is
the filename of the object.

Examples:

playername=this_player()->query_name();

"players/padrone/workroom"->someone_entered(playername);

Another way of calling functions in other objects is using the call_other
function. This is an old and ugly way, use it only if no alternative exists.
Layout:

[<var_name> =] call_other(<objexpr>,<funcexpr>[,<expr>]);

Here the <funcexpr> must be of type string, and is the name of the function
that is called. As you can see, only one parameter can be given to a function
this way.

Example:

playername=call_other(this_player(),"query_name");
-----------------------------------------------------------------------------
Simple example of using functions:

random_flavour(i) {             /* Definition of the function random_flavour */
  if(random(i)) return "lemon"; /* Chance depending on i: returning "lemon" */
  return "orange";              /* Other chance for returning "orange" */
}                               /* End of function definition */

taste_it() {                    /* Definition of the function taste_it */
  say(this_player()->query_name()+" tastes it.\n");
                                /* Call of function query_name the player */
  write("It tastes like "+random_flavour(2)+".\n");
                                /* Call to random_flavour in this object, with
                                   50% chance (i=2) */
}                               /* End of function definition */
-----------------------------------------------------------------------------

I hope this file was of use to anyone. Any bugreports and suggestions for more
files, questions ect. can be send to Cashimor (maarten@einstein.et.tudelft.nl).

Greetings,

Ethereal Cashimor







