Functions in LexiScript

The LexiScript Function system is a powerful system for encapsulating portions of scripts for easy reuse. If a script has similiar pieces of code that are used in multiple places, you could take these portions out and put them in a function.

In addition, you can place functions into a script, and 'import' all the functions into another script.

Syntax

Defining a Function

A function can appear anywhere in a script, but should be kept at the beginning or end for easy readability:

function <Name Of Function>(<Parameters>)
    <Code Here>
end

A function's name must not contain any spaces.

Functions have their own variable space. Specifically, they do not inherit any local variables that the caller had, such as %actor%. Instead, all arguments are passed in as a single line, %arg%, similiar to Call scripts.

When a function is called, it acts just like the script; a 'wait' will cause the whole script to pause, etc. This is different from Call scripts, where when the Called script waits, the script that called it will resume, and after the delay, the Called script will resume as well.

The function returns control to the caller on 'halt' or reaching the end of the function.

Functions CAN call other functions; beware of recursion (a function calling itself, or another function which calls it). There is a MAXIMUM DEPTH of 32 levels of recursion!

Calling a Function

To call a function, you treat it like a built in command:

MyFunction <Arguments>

Alternatively, you can treat it like a built-in function:

if (%MyFunction(Arguments)%)
   do something
end

You can also use it like a built-in function on it's own line:

%MyFunction(Arguments)%

Passing Multiple Arguments - Parameters

Sometimes you may want to pass multiple pieces of information to a function, such as several lists or multi-word phrases.

Simply separate the different parameter names by commas in the function's definition, then when calling the function separate the parameters passed in with commands, and each parameter will be put into it's appropriate variable.

For example:

function Add(first, second, third)
    return %first% + %second% + %third%
end

echo The result will be 6: %Add(1, 2, 3)%

Alternatively, the entire list of parameters is put into one variable, %arg%, as a parameter list.

%eval()% allows for in-line mathematical evaluations where they might not normally be allowed (for example, 'set', function calls, and built-in commands). The comma (,) is a special math operator that creates a new string from the left and ride sides of the operation, separated by a special whitespace character, the 'tab'. Most script code ignores this character, treating it as a regular word separator, and if you send it to a player, it will produce something like an 8-space-wide gap.

To get parameters apart, the .param() variable-function extracts numbered parameters. For example, if you put together a parameter list of 4 parameters:

set paramList %eval(%actor%, %arg%, %obj.shortDesc%, %victim%)%

Then you can later extract these items:

set actor %paramList.param(1)% set arg %paramList.param(2)% set objShort %paramList.param(3)% set victim %paramList.param(4)%

Parameter lists are like regular lists, except that they can contain lists as individual "words" (parameters) in the list. You can get a list-of-lists this way (a paramter list of words, which may be lists), but you cannot have a list-of-lists-of-lists, although this can be worked around with records. The parameter list itself can be treated as a regular list.

Return Values

A function can pass back information via the return command. Any value can be returned, such as a number, a string, a list, a record, etc.

return value

If the function was called as a command, then the caller will have the value put into the variable %result%. Otherwise, the value is passed back to be used in the evaluation it was part of.

Importing Functions

Functions from other scripts can be imported into the current script:

import <vnum>

Functions in imports are only accessible to the script that imports them; they are not available to anything that imports the script. (If A imports B, and B imports C, functions in B can access functions in C, but A cannot access functions in C. In this case, A should import both B and C).

Imports are 'pre-processed'; that is, when the script is compiled, it handles all imports, and the imports are always available for the script's use. They are NOT commands. An import must be a vnum, it cannot be a label or variable.

Example

function SmileAtPerson(person)
    if %person.race% == Alien
        halt
    end
    smile %person%
    wait 1s
end

set people %actor.room.people%
foreach people person
    %SmileAtPerson(%person%)%
done

-- FearItself

z50 - Script Function Library Zone

Function libraries can be compilated in zone 50. Check Function Library Zone for details.

-- LividityAvP - 11 Feb 2005