LPC data type: function

A function is a complex data type which points to a function in a particular
object.  This is useful for things like set_search(), where you can define
which function the code should look for when a player types "search".
A function is declared:

function f;

Upon declaration, it has a NULL value and will cause errors if it is
used in operations before getting a value.  Assigning a value to a function
might look like this:

f = (: this_object(), "search_field" :);

This has f pointing to the function search_field() in this_object().
Thus:
(: object, string :)
is the constant expression of a function.  You may use function pointers
to call the functions to which they point.  Using the example
above, we can then make a call to seach_field() in this_object():

What good are these functions anyways?
Well, take set_search() in your room.c for example.  Without the
data type function, you had to have 2 sets of functions, one to handle
search strigns, another to handle search functions.  Otherwise there
was no way for the driver to now whether you mean a search string ot
if the string is the name of a function.  This also tends to confuse
people new to the mudlib, cause different mudlibs would use:
set_search_func() set_search_function(), etc.
The data type function allows you to pass the function in question as an
actual value, thus eliminating the need for redundant set_*() functions.

%^RED%^%^BOLD%^-----< advanced notes >-----

(*f)()

The * says that you are not interested in the value of f, but instead you are
interested in making a call to it.  You enclose it in () so that there
is no confusion as to what the * means (you do not want the compiler to
barf thinking you want to multiply).  And, like with any function call,
the second () would enclose any arguments.  So:

If f == (: this_object(), "search_field" :)

(*f)()
(*(:this_object(), "search_field":))()
this_object()->search_field()
call_other(this_object(), "search_field");

all mean the same thing.

------< Very advanced notes >------

The $() syntax is used when you wish to pass the VALUE of a variable into
a function expression. Normally you may NOT do the following lines;

string x="blarg";
function y=(: x :);

If you attempt the above, you would get an error stating that you may not
use local variables inside the (: :) brackets. The $() operation corrects this.
You use it as follows;

string x="blarg";
function y=(: $(x) :);

The result of this would make y == (: blarg :).

What the $() operator does is copies the VALUE of the variable you encase in it
and not the variable itself.

==============================================================================

%^GREEN%^%^BOLD%^Final notes

The *() and $() operators are very tricky and sensitive. Please do NOT attempt
their use without an archwizard's supervision.

Ironman

