Functions

A function is a collection of commands which performs a specific task. It is used primarily to avoid having to repeat a section of code multiple times within a DI page. A function can also return a result which can then be used with other DI commands.

• Commands related to functions
• Calling functions
• Other data returned from a function
• Notes about functions
  • Local variables
• Predefined functions

Commands related to functions

.FUNCTION Name= [Declaration=]

The Name parameter is required. It defines the name you will use in your code to call the function. Note that function names are independent from other variables. You can have a regular variable called foo, as well as a function with this name.

The Declaration is a comma- or space-separated list of parameters this function will accept. Since this is one parameter, you should always surround it with either single- or double-quotes, if it includes more than one value.

When the function is called, the parameters being passed are assigned to the variables named in this list, from left to right. They can also be passed by name, just like with DI commands. If a particular parameter is not passed when the function is called, its value is set to an empty string.

.ENDFUNC

Signifies the end of a function declaration.

.RETURN [Value=]

Immediately exit the function, optionally returning some value to the code which called it. See also, the note about other data returned, below.

Calling functions

There are two ways that a function can be invoked. The first, is by simply referencing it using the & symbol, followed by its name. When using this syntax, you can separate any parameters being passed to the function with spaces or commas:

<!--.
function sum "a, b";
    return $a+$b; 
endfunc;

echo "2+2 is ";
&sum 2 2;
echo " (as if you didn't know)";
-->

2+2 is 4 (as if you didn't know)

The function call could also have been written as &sum 2,2 or even &sum a=2,b=2.

The second way is a little more flexible, because it allows you to get the results of a function and use them in another expression. Here, you precede the name with $&. In this case, the parameters (if any) must be surrounded with () parentheses, so that the DI knows where they end. If no parameters are being passed, the parentheses are optional.

<!--.
function sum2 "a, b";
    return $a+$b; 
endfunc;

echo "2+2 is $&sum2(2,2) (as if you didn't know)";
-->

2+2 is 4 (as if you didn't know)

Other data returned from a function

One way to return a particular value to the calling code is with the .RETURN command. Additionally, any time the code within a DI function does something that would cause some sort of data to be inserted into the output stream, it is appended onto the overall return value for that function. Commands which do this include .ECHO, .DBDUMP, and the various graphics commands. If a .RETURN is encountered, its return value is appended onto the end of all the previous output. For example:

<!--.
function powers;
    echo "2^0=".(2**0)."<br>"; 
    echo "2^1=".(2**1)."<br>"; 
    return "2^2=".(2**2);        # could have also used echo here 
endfunc;

echo "I have the power:<br>$&powers<br>(Are you excited yet?)";
-->

I have the power:
2^0=1
2^1=2
2^2=4
(Are you excited yet?)

Notes about functions

* There are a number of built-in functions, which are already part of the DI.

* If you are creating a number of functions to be reused in a set of pages, consider using the .LIBRARY command to simplify this process.

* Functions can be called recursively, meaning you can call a function within itself. Be careful to use local variables, though (see below). Otherwise, you may get unexpected results.

* Functions can be defined within other functions. However, unlike in other languages, a function declared this way can be called by code in any part of the current document. Its scope is not limited to the function containing the declaration.

Local variables

Any variable created in the DI is available globally. This means that any part of the current DI page can see any variable created within any function, and changes made to that variable will affect the contents for all parts of the code.

This can make writing a program which uses many functions difficult, because you have to worry that any temporary variables you create within your functions might modify the contents of a variable with the same name used elsewhere in the code.

The way around this is to use local variables within your functions. This is achieved by adding the local option to the .DB, .DBARRAY, .DBHASH, or .SET call which defines the variable. Here are two versions of the same program:

<!--.
function multiply "a, b";
    set foo=$a*$b;
    return $foo; 
endfunc;

set foo=12;
echo "At first, foo is $foo<br>";
echo "11 times 23 is: $&multiply(11,23)<br>";
echo "Now, foo is $foo<br>"; 
-->

At first, foo is 12
11 times 23 is: 253
Now, foo is 253

<!--.
function multiply2 "a, b";
    set local foo=$a*$b;
    return $foo; 
endfunc;

set foo=12;
echo "At first, foo is $foo<br>";
echo "11 times 23 is: $&multiply2(11,23)<br>";
echo "Now, foo is $foo<br>"; 
-->

At first, foo is 12
11 times 23 is: 253
Now, foo is 12

In the first version, the variable foo gets changed by the call to multiply. The second version prevents this by declaring foo as local. Think of the local option as meaning "make a copy of the old value of this variable and restore it after the current function returns." The variables defined in the function's declaration are automatically local to that function, so you can always use whatever name you want there.

Top | Next Page