Functions

Anatomy of a function

In general terms, Spektar functions correspond conceptually to C functions or Java methods. The consist of a delaration, and body, where declaration in turn consists of return value, package, function name and parameters, and function body consists of statements.

Within a function, same rules for scripting apply as for component scripting. To put this all together, best let’s look at an example.

/**
This is documentation section. Some HTML is tolerated.

 * star when appears as first non-whitespace char is ignored
 
@function rms Calculate root mean square of an array
@param x The input array
@param num The input array size
@returns The rms of the array
*/
float #rms(float[] $x, int $num) {
	double $sum = 0;
	for (int $i = 0 ; $i < $num ; $i++) {
		$sum += $x[$i] * $x[$i] ;
	}
	$sum = $sum / $num;
	$sum = #math:sqrt($sum);
	return (float) $sum;
}

Packages

If you simply drop function source code into a {user-home}/Spektar/functions/base that function immediately becomes available to all components and scripts. There is no installation required. This also explains why function declaration doesn’t require package.

Invoking a function from a certain package is done by prefixing the function with package name and : sign as below:

float $rms = #base:rms( $mydata, 32);

Naming

Function and package names must consists of letters and numbers only and must start with a letter. Lowercase is preferred and CamelCase is ok.

In terms of files, file must be named as follows:

{function-name}[-version].fn

Function name in filename must be exactly the same as function name in the declaration. Version is optional, and if missing, the file is considered to contain newest / latest version of the function.

Versioning

Version is defined as a single integer number.

An installation may contain multiple versions of a function. If you don’t specify the version in your script, system will select the latest version.

You can specify desired version when calling a function as follows:

float $rms = #base:rms:1( $mydata, 32);

Documenting functions

In the above example we’ve also illustrated how functions can be documented. We essentially follow JavaDoc standards, but in summary:

1. Function file must start with /** which denotes documentation start
2. Documentation section ends with */
3. Any line starting with whitespace and * is trimmed to exclude that prefix
4. Any line starting with @ is processed as below and not included in doc text

Processing @ is done as follows:

1. Line starting with @function defines short, one sentence summary of the purpose of the function.
2. Any line starting with @param - expects parameter name and description.
3. Any line starting with @return - expects short description of the return value

Dependencies

Spektar will automatically handle dependencies while exporting (e.g. to C or Java), as long as functions being used are referenced correctly and available in the functions folder hierarchy.