Difference between revisions of "Manual:DIL Manual/Functions"
(XML import) |
(rewritten against the compiler and interpreter; examples compile) |
||
| Line 1: | Line 1: | ||
| − | < | + | Besides its [[Manual:DIL Manual/Built-In Functions|built-in functions]] and [[Manual:DIL Manual/Built-In Procedures|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 <code>dilbegin ... dilend</code>; zones such as <code>function.zon</code>, <code>quests.zon</code> and <code>randomt.zon</code> 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 [[Manual:DIL Manual/Data Types|types]]. A function ends with <code>return(value);</code>, a value of that type; a procedure with <code>return;</code>. See [[Manual:DIL Manual/return()|return]]. | ||
| + | * Put <code>return</code> on every path. A called template that runs past its closing brace starts again from its first statement instead of going back. | ||
| + | * <code>return(null);</code> doesn't compile in a <code>unitptr</code> 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 <code>vme.log</code>). | ||
| + | * [[Manual:DIL Manual/quit|quit]] inside a called template ends the whole program, the callers too. Use <code>return</code> to go back. | ||
| − | < | + | == Declaring and calling == |
| + | A template calls another after declaring it in its [[Manual:DIL Manual/external|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 <code>name@zone</code>, in the declaration and in the call. One in the same zone can be named without <code>@zone</code>, but it still needs the declaration; without it vmc says "No such variable". | ||
| + | * A procedure is called as a statement: <code>tell_all("...");</code>. A function is called in an expression: <code>n := max@function(a, b);</code>, <code>if (max@function(a, b) > 10)</code>, <code>itoa(max@function(a, b))</code>. 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: <code>f(g(x))</code> doesn't compile. Put <code>g(x)</code> in a variable first. Built-in functions take it: <code>itoa(g(x))</code> is fine. | ||
| + | * A field can't follow a call: <code>get_room(s).title</code> is a syntax error. | ||
| + | * vmc writes a declaration for each template of a zone to <code><zone>.dh</code> 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 <code>addstring()</code> 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 <code>u.hp := 1;</code> 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". <code>null</code> is fine. | ||
| − | + | == What a call shares with its caller == | |
| − | + | A called template runs inside the same program, on the same unit: | |
| − | + | * <code>self</code> is the caller's unit, and <code>activator</code>, <code>argument</code> 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 [[Manual:DIL Manual/global|global]] variables are shared. | |
| + | * It shares the program's [[Manual:DIL Manual/heartbeat|heartbeat]]: a function that changes it for a <code>pause</code> should put it back, as quests.zon's functions do. | ||
| + | * Its [[Manual:DIL Manual/secure()|secures]] and [[Manual:DIL Manual/interrupt()|interrupts]] are its own and end when it returns. When it returns, the caller's secures are tested again. | ||
| + | * It may wait (<code>wait</code>, <code>pause</code>); the whole program waits with it. A program copied with <code>recall</code> 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 [[Manual:DIL Manual/DIL Constructs|DIL Constructs]]). | ||
| − | + | == Recursion == | |
| + | A template can call itself, without declaring itself (declaring itself in its own <code>external</code> 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 <code>external</code> declaration is needed. boards.zon calls a function whose name is kept in an extra this way: <code>(string) u.extra.["$BOARD_P_RES"].descr(self, u)</code>. | ||
| + | * 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. | ||
| − | + | [[Manual:DIL Manual/dilcall()|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 <code>vme/etc/commands.def</code> with <code>func = do_name@zone</code> runs that template when a player (or an NPC with <code>exec()</code>) types it. It takes one string argument, the rest of the line, <code>self</code> is the character who typed it, and it ends with <code>quit</code>. [[Manual:DIL Manual/getword()|getword()]] takes the words off the argument one at a time. | ||
| − | + | == Example == | |
| − | + | <pre> | |
| − | + | dilbegin integer count_items(u : unitptr); | |
| − | + | var | |
| − | + | it : unitptr; | |
| − | + | n : integer; | |
| − | dilend | + | 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 | ||
| + | </pre> | ||
| + | <code>count_items</code> is a recursive function that counts the objects a unit holds, inside containers too; <code>report</code> is a procedure; <code>do_mycount</code> is a player command that calls both, and calls <code>max@function</code> through a string. | ||
| − | + | == See also == | |
| − | + | * [[Manual:DIL Manual/external|external]] | |
| − | + | * [[Manual:DIL Manual/return()|return()]] | |
| − | + | * [[Manual:DIL Manual/dilbegin|dilbegin]] | |
| − | + | * [[Manual:DIL Manual/dilcall()|dilcall()]] | |
| − | + | * [[Manual:DIL Manual/global|global]] | |
| − | + | * [[Manual:DIL Manual/Making a Program|Making a Program]] | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
Latest revision as of 23:54, 14 November 2026
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.
Contents
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
returnon 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 aunitptrfunction: 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
returnto 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. Putg(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).titleis a syntax error. - vmc writes a declaration for each template of a zone to
<zone>.dhnext 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".
nullis fine.
A called template runs inside the same program, on the same unit:
selfis the caller's unit, andactivator,argumentand 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
pauseshould 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 withrecallonly 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.