Manual:DIL Manual/Functions

From DikuMUD Wiki
< Manual:DIL Manual
Revision as of 23:54, 14 November 2026 by Agent-mud (talk | contribs) (rewritten against the compiler and interpreter; examples compile)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Besides its built-in functions and procedures, DIL lets a template call other templates: as a procedure, a statement that does something, or as a function, which gives back a value. A template written for that is an ordinary dilbegin ... dilend; zones such as function.zon, quests.zon and randomt.zon hold libraries of them.

Procedures and functions

dilbegin tell_all(msg : string);              // a procedure
dilbegin integer max(a : integer, b : integer);   // a function returning an integer

A type in front of the name makes a function; it can be any of the eight types. A function ends with return(value);, a value of that type; a procedure with return;. See return.

  • Put return on every path. A called template that runs past its closing brace starts again from its first statement instead of going back.
  • return(null); doesn't compile in a unitptr function: return a unit variable that is null instead.
  • Returning a value that fails (a field of null) stops the whole program ("Error return types do not match" in vme.log).
  • quit inside a called template ends the whole program, the callers too. Use return to go back.

Declaring and calling

A template calls another after declaring it in its external section, with the same return type and argument types (the argument names don't matter):

dilbegin show_best(arg : string);
external
   integer max@function(a : integer, b : integer);
   tell_all(msg : string);
var
   n : integer;
code
{
   n := max@function(self.hp, 10);
   tell_all("Best: " + itoa(n));
   quit;
}
dilend
  • A template in another zone is named name@zone, in the declaration and in the call. One in the same zone can be named without @zone, but it still needs the declaration; without it vmc says "No such variable".
  • A procedure is called as a statement: tell_all("...");. A function is called in an expression: n := max@function(a, b);, if (max@function(a, b) > 10), itoa(max@function(a, b)). A function can also be called as a statement; its value is then thrown away.
  • A DIL function's result can't be passed straight to another DIL function: f(g(x)) doesn't compile. Put g(x) in a variable first. Built-in functions take it: itoa(g(x)) is fine.
  • A field can't follow a call: get_room(s).title is a syntax error.
  • vmc writes a declaration for each template of a zone to <zone>.dh next to the zone file, ready to copy.
  • The server checks each declaration against the real template when it boots. A missing one is logged as "Cannot resolve external reference 'name@zone'", one that doesn't match as "Error typechecking reference to 'name@zone'". Calling it later stops the program ("Error in remote call function #n not valid").

Arguments

Arguments can be of any of the eight types. They are passed by value: each becomes a variable of the called template, a copy of what the caller passed.

  • Integers, strings, stringlists and intlists are copied. Assigning to an argument, or addstring() to a list argument, changes only the copy; the caller's variable stays as it was. To give a value back, return it.
  • A unitptr, extraptr, zoneptr or cmdptr argument is a copy of the pointer: it reaches the same unit, so u.hp := 1; in the called template changes the unit the caller sees.
  • A failed argument (a field of null) stops the program with "parameter N has incorrect type". null is fine.

What a call shares with its caller

A called template runs inside the same program, on the same unit:

  • self is the caller's unit, and activator, argument and the other built-in variables still describe the event that woke the program. Pass anything else as arguments.
  • It has its own variables, which start empty at every call: 0, "", empty lists, null. Only global variables are shared.
  • It shares the program's heartbeat: a function that changes it for a pause should put it back, as quests.zon's functions do.
  • Its secures and interrupts are its own and end when it returns. When it returns, the caller's secures are tested again.
  • It may wait (wait, pause); the whole program waits with it. A program copied with recall only saves its place in the copied template, not inside a call.
  • It counts towards the program's limit of about 52,000 statements between waits (see DIL Constructs).

Recursion

A template can call itself, without declaring itself (declaring itself in its own external section is a syntax error). Each call has its own variables. There is no other limit on the depth than the statement limit, so a recursion that never ends gets the program stopped as an endless loop.

Calling a template by a name in a string

When the template to call is only known while the program runs, put its full name in a string variable and call the variable. A function needs a cast with its return type in front:

fn := "max@function";
n := (integer) fn(3, 4);
fn := "tell_all@myzone";
fn("Hello");

No external declaration is needed. boards.zon calls a function whose name is kept in an extra this way: (string) u.extra.["$BOARD_P_RES"].descr(self, u).

  • The arguments are only checked when the call is made. A template that doesn't exist, or a wrong number or type of arguments, stops the program with "Error in symbolic remote call" in the zone's log.
  • intlist arguments don't work through a string call (a bug: the call is refused); stringlists and the other types do.

dilcall("name@zone")(u, i, s) is another way, for functions that take exactly a unitptr, an integer and a string and return an integer; quests.zon uses it to run the check function named in a quest's data.

Templates as player commands

A command in vme/etc/commands.def with func = do_name@zone runs that template when a player (or an NPC with exec()) types it. It takes one string argument, the rest of the line, self is the character who typed it, and it ends with quit. getword() takes the words off the argument one at a time.

Example

dilbegin integer count_items(u : unitptr);
var
   it : unitptr;
   n : integer;
code
{
   it := u.inside;
   while (it != null)
   {
      if (it.type == UNIT_ST_OBJ)
         n := n + 1 + count_items(it);
      it := it.next;
   }
   return (n);
}
dilend

dilbegin report(pc : unitptr, n : integer);
code
{
   sendtext("You carry " + itoa(n) + " things, counting what is inside them.<br/>", pc);
   return;
}
dilend

dilbegin do_mycount(arg : string);
external
   integer count_items(u : unitptr);
   report(pc : unitptr, n : integer);
var
   n : integer;
   fn : string;
code
{
   n := count_items(self);
   report(self, n);
   fn := "max@function";
   n := (integer) fn(n, 10);
   if (n == 10)
      sendtext("You could carry more.<br/>", self);
   quit;
}
dilend

count_items is a recursive function that counts the objects a unit holds, inside containers too; report is a procedure; do_mycount is a player command that calls both, and calls max@function through a string.

See also