Manual:DIL Manual/dilbegin

From DikuMUD Wiki
Jump to navigation Jump to search

dilbegin

Keyword. Starts a DIL program, called a template.

dilbegin [aware] [recall] [unique] [fnpri(n)] [type] name(arg : type, ...);
[external
   declarations]
[var
   declarations]
code
{
   statements
}
dilend

A template is one DIL program. It runs on a unit (a room, object, NPC or player) that has a copy of it, or is called by other templates as a procedure or, when it has a return type, as a function. The parts always come in the order shown: the header, then external, then var, then code, then dilend.

Templates are written in the zone's %dil section, where units use them with dilcopy name@zone(...); in their definition, or with the dilcopy() procedure. A dilbegin written inside a unit's own definition is also a template of the zone, and that unit gets a copy of it, with no arguments, every time it is loaded.

Header

Part Meaning
aware, recall, unique, fnpri(n) Options, in any order, before the type and the name. See their pages.
type The type the template returns: one of the eight types. With a type it is a function and ends with return(value); without one it is a procedure or a program.
name The template's name, at most 15 characters. Its full name is name@zone.
(arg : type, ...) The arguments, separated by commas. They are variables of the template like those in var. The brackets are needed even when there are none, and the header ends with a semicolon.

Notes

  • A name is required: dilbegin (); stops vmc with "All DIL programs must have a name". A longer name than 15 characters gives "Name of dilprogram '...' was too long."
  • Two templates with the same name in one zone stop vmc with "Redefinition of template named 'name@zone'". That includes the ones written inside units.
  • Options go before the name: dilbegin pr() aware; is a syntax error.
  • vmc cuts each program out of the zone from dilbegin to the first ^ character, and dilend is a macro in wmacros.h that adds that ^. So the zone must #include <macros.h> (which includes wmacros.h), and a ^ inside a string in the program ends it early with a syntax error. A ^ in a comment is fine.
  • A template inside a unit's definition should take no arguments. vmc accepts arguments there, but the unit's copy gets none: at boot the zone log says "Template '...' had mismatching argument count 0" and the program never starts. Put templates that take arguments in %dil.
  • A template can call itself without declaring itself; any other template it calls, even one in the same zone, needs an external declaration.
  • vmc writes one declaration line per template (integer dbl@ex (n : integer);) to <zone>.dh next to the zone, ready to copy into another template's external section.
  • Each run of a template, and each call of it, has its own variables, which start empty (0, "", empty lists, null). Only global variables are shared.

Example

dilbegin string plural(n : integer, word : string);
code
{
   if (n == 1)
      return ("1 " + word);
   return (itoa(n) + " " + word + "s");
}
dilend

dilbegin aware count_says();
external
   string plural(n : integer, word : string);
var
   n : integer;
   s : string;
code
{
   :start:
   wait(SFB_CMD, command("say") and (activator == self));
   n := n + 1;
   s := plural(n, "time");
   sendtext("You have spoken " + s + " today.<br/>", self);
   goto start;
}
dilend

A function and a program that uses it. Copied onto a player, count_says counts what the player says; it needs aware because the player is both the owner and the one who acts.

See also