Function

function functionName(__parameterNames) { }

Functions allow structuring and reuse of code. They are defined with the function keyword, and their content is a code block enclosed in curly brackets. Functions can take parameters between brackets (parentheses). The return keyword is used to end the function and return a value.

Parameters and result

Parameters are always passed by value, but note that the value of a collection variable is a reference. Multiple parameters are separated by commas.

The result of a function is defined by the return keyword. It is also possible to end a function without returning anything. This happens when the last line has run, the return statement is empty, or a break; is executed.

Example

use System;
use Web;

var page = Web.loadPage("http://www.google.com/");
System.print(getLang(page));

function getLang(page) {
    return Web.xPath(page, "/html/@lang");
}

Scope

• Variables declared in the highest scope (outside of functions) are in scope of all functions in the same robot, but not in included functions
  
• Variables declared in a function are never in scope outside of that function (although the value can be passed or returned)
• Parameters with the same name as another variable in scope will mask that variable

Example

use System;

var test1 = 1; // declared in super scope, so this var is available in all functions
function1();

function function1() {
    var test2 = 2; // will be garbage collected when function 1 ends
    var test3 = 3;
    function2(test3); // passes the value of test3
    System.print(test1); // prints 8, because function2 changed it
    System.print(test3); // still prints 3, because this variable was shadowed in function2
}

function function2(test3) { // value '3' is put in new variable also named 'test3'
    test1 = 8; // this changes test1 in robot-wide scope
    // test2 is not in scope
    test3 = 4; /// this changes only the masking variable test3 (in this scope)
    System.print(test3); //prints 4
}

Re-using functions

Functions in a robot can be used in another robot using the include keyword.