BEE Script:      function name [name=value ...] { statement; ... }

BEE Tag:     <beefunction name [name=value ...]>

                  tag

                  ...

            </beefunction>

BEE Function is a block of code between the "function" command and the closing curly bracket.  In BEE Tag, it is the block between <beefunction [function_name]> and </beefunction>.  It is not executed at the time of declaration.  Instead, the code is executed at the time of "calling".  The "calling" syntax is exactly the same as calling a BEE Script statement or a BEE Tag, except that the command name is substituted with the function name.

Unlike in other programming languages, a BEE Function does not return a value syntactically.  Instead, it passes out values through the "result", "status" and "message" classes.  This enables the caller to receive from the function an array, a status code and a message text respectively in one go.

The argument list is in name-attribute pair format in both the function declaration and the function calling (unlike in most other languages which put the argument list in a comma-delimited position sensitive list inside a pair of small brackets.)

The function declaration line does not have to include all the arguments.  Those that are included in the declaration line will be in name-attribute pair format, where each attribute represents the default value (the value the function takes if the argument is missing from the calling line).

If there is no default value for an argument, DO NOT include it in the declaration line.  In such case, if the argument is missing from the calling line, it will be undefined.  You can use the "isset" BEE Conversion on the arg%function:name or arg%name, to find out whether a particular argument is defined or not.

Variables if any in the default value is interpreted from the parent Context at calling time, instead of at the declaration time.  For example:

var a = 123;

func1;

var a = 456;

function func1 x="{a}"

{

      // {arg%x} evaluates to "123"

}

Within the function declaration, arguments are referred to by the variable arg%function:argname or directly via arg%argname (useful for array passing.)  For example, if function "myfunc" has two arguments: a=1 and b=2, then arg% contains:

The arg%function variable contains the argument in a non-structural form.  For example, if argument b is an array like b="(array)x=>11,y=>12", arg%function:b will look exactly like this, without the evaluation of the array:

All arguments are optional syntactically.  That means missing arguments of passing more of them do not cause syntax problem.  Missing arguments will take on the default value.  If no default value is specified for a missing argument, it will be undefined within the function.

Excessive arguments simply stay in the arg% variable list without causing trouble.  That enables the function to work on a variable argument list by scanning the arg%function variable for argument values.

Arguments are passed by value, not by reference.  To pass variables by reference, you can pass the variable name and declare the variable "parent".  (Please see the "parent" tag.)  For example:

function plusOne

{

      parent "{arg%v}";

      var "{arg%v}" = "(expr){{arg%v}} + 1";

}

var a = 2;

plusOne v="a";

// Now {a} is 3

Variables within a function are "local", which means that they do not inherit the values they got before the function call, and any changes to them inside the function would not be effective outside (except for System Classes.)

Example:

function calculate num1=0 num2=0

{

      var result%function:sum="(expr){arg%num1}+{arg%num2}";

      var result%function:diff="(expr){arg%num1}-{arg%num2}";

}

calculate num1=5 num2=2;

display "Five plus two is {result%calculate:sum}<br> ";

display "Five minus two is {result%calculate:diff}<br> ";

If the argument names is preceded by an "!", it means the BEE Variable inside the argument will NOT be evaluated ("absolute" passing).

Example:

var something = "out there";

showme what="{something}";  // Show me out there

showme !what="{something}";  // Show me in here

function showme

{

      var something = "in here";

      display "Show me {arg%what}<br> ";

}

If the calling command does not pass in the argument, and the argument name in the function declaration line for default value is preceded by an "!", the argument value will be "absolute", which means it will NOT be evaluated in the parent Context.  For example:

var something = "out there";

showme1;  // Show me out there

showme2;  // Show me in here

function showme1 what="{something}"

{

      var something = "in here";

      display "Show me {arg%what}<br> ";

}

function showme2 !what="{something}"

{

      var something = "in here";

      display "Show me {arg%what}<br> ";

}

Parameters

function specifies the name of the function.  It must be an alphanumeric string starting with a letter.  Function name is case insensitive.  It will be converted to lowercase internally.

Within the function declaration, the following BEE Variables are made available:

After calling the function, the following BEE Variables are made available: