Introduction

Inside a BrainStim script you can make use of script function(s) and include(s) that allow you to write better code because you can structure your code in smaller modules, making it reusable, easier to read and test.

Functions

A function is a group of reusable code which can be called anywhere in your program. This eliminates the need of writing the same code again and again. It helps programmers in writing modular codes. Functions allow a programmer to divide a big program into a number of small and manageable functions.

Before we use a function, we need to define it. The most common way to define a function is by using the function keyword, followed by a unique function name, a list of parameters (also referred to as 'arguments') (that might be empty)and a statement block surrounded by curly braces, like the below template:

function functionname(parameter-list)
{
    //enter function body script code here...
}


Let's define a simple function that writes a message ('Hello there') to the BrainStim 'default' OutputLog Tab by calling the BrainStim Log() function. The below sayHello() function has no parameters or arguments defined.

function sayHello()
{
    Log("Hello there");
}


To invoke or call the sayHello() function somewhere later in the script, you would simply need to write the name of that function and provide the list of defined parameters (arguments) like:

sayHello();


Before we end the script we have to make sure to set the function to null in order for the script engine to finalize and perform a garbage collection(see this document for some more information about this topic) like:

sayHello = null;

Till now, we have seen a function without any parameters defined. But there is a facility to pass different parameters while calling a function. These passed parameters can be captured inside the function and any manipulation can be done over those parameters. A function can take multiple parameters separated by comma. Let's extend our sayHello() function with two parameters (arguments):

function sayHello(firstName, lastName)
{
    Log("Hello " + firstName + " " + lastName + ".");
}

To invoke or call the sayHello() function we now also provide the parameters (arguments) like:

sayHello("John", "Doe");

A function can have an optional return statement. This is required if you want to return a value from a function. This statement should be the last statement in a function. For example, you can pass two numbers in a function and then you can expect the function to return their multiplication in your calling program.

function add(first, last)
{
    var full;
    full = first + last;
    return full;
}

Calling that function could look something like:

var result = add(3, 5);
Log("The result is: " + result);

A complete example of the above code can be found in the script file Functions.qs that is located in the Main Program Directory under the subfolder /Examples\Script. To execute this example you can:

Includes

Inside the script you can make use of an Include keyword/statement that allows you to include/embed other script (*.qs) files. Including another script file is like automatic copy/pasting the entire included document at the Include statement. The string parameter from the Include function holds the path to the script file to include.

The provided string can be a absolute or a relative path, if only a filename is defined than the Include function searches for the filename inside the directory where the current active running script document is stored.
If the file is not found here then it searches for the file in the default Include directory (see Main Program directory chapter), if the file is even then not found then the search is extended to the optionally directories that are defined (in order) by the Include Directories setting in the Settings Dialog.

By using include(s) in your script you can make it even more modular and reusable, let's see how we can make use of an include statement: