Functions

A function is a block of organized code that performs a specific set of actions. One of the benefits of a function is that it can be used over and over again in a script, without having to write a lot of duplicate code.

Function Definition

A function is made up of two parts: a function “declaration” and a function “body”. The function declaration consists of the function keyword, followed by the name of the function, and parentheses (). The function body contains the block of code for the actions the function will perform, and is terminated by the end keyword.

This is an example of a simple function definition for a function named “printHello”.

local function printHello()
    print('Hello world!')
end

This function prints the text string ‘Hello world!’ to the log console.

All functions are either global or local in scope. Unless a function is declared as local, it will default to global scope. A global function is visible to all scopes within a script. A local function is visible only to the block in which it is defined, plus any child blocks.

Function Parameters

Functions can take inputs called “parameters” (also called “arguments”) - which is data that is used by the function to carry out its action. Function parameters are optional - a function can take zero, one, or more parameters. If a function does require parameters, they must be included in the parentheses, separated by commas, when declaring the function.

local function divide(a, b)    <-- the divide() function requires the two inputs included in the parentheses.
    return a / b
end

function onStart()
    local result = divide(10, 2)

    print(result)  <-- Prints '5'
end

This program prints the result of dividing two numbers. When the above program runs:

1. The divide() function is declared as a local function that takes two inputs (a and b) and returns the result of dividing a by b when it is called.
2. The onStart() function declares a local variable called result.
3. result is assigned the value of what is returned by calling the divide() function while passing two inputs (10 and 2) to it.
4. onStart() then prints value of result.

Calling Functions

The code in a function can be run by “calling” the function (sometimes this is referred to as “executing” the function), which simply means that something triggers the function to run. To call a function, write the function name followed by parentheses - for example, print() , calls the “print” function.

When a function is called, any parameter(s) that the function declared as inputs should be passed to it. To pass inputs to a function, specify the inputs between the parentheses - for example print('Hello world!') , where the string 'Hello world!' , is being passed as an input to the “print” function. If the function does not require any input(s), simply follow the function with empty () when calling it.

local function printHello()   <-- the "printHello" function is declared
    print('Hello world!')       <-- the "print" function is called, and passes 'Hello world!' as an input
end

function onStart()
  printHello()                <-- the "printHello" function is called
end

This program writes the string “Hello world!” to the log console, one time when the program starts.

Return Values

Functions can return data when called, using the return keyword. Return values are the values that a function returns when it has completed.

The data returned by a function can be assigned to a variable, passed as an input to another function, or used anywhere else a variable can be used.

In the following example, the program prints the result of dividing two numbers.

local function divide(a, b)
    return a / b
end

function onStart()
    local result = divide(10, 2)

    print(result)  <-- Prints '5'
end

When the above program runs:

1. The divide() function is declared as a local function that takes two inputs (a and b) and returns the result of dividing a by b when it is called.
2. The onStart() function declares a local variable called result.
3. result is assigned the value of what is returned by calling the divide() function while passing two inputs (10 and 2) to it.
4. onStart() then prints value of result.

Function Signature

The specific pattern of inputs that a function takes and the outputs that it returns is called its “signature.” It is important to know the signature of a function because it explains how the function works and how you should use it in a program. If you know the signature of a function, you can always pass the correct inputs to the function when you call it.

To confirm the signatures of functions that can be used in SuperCode, check the online reference docs, or ask the community in the #help channel on the SuperCode Discord server.

Function Uses

Functions are commonly used by programmers to break down a problem into smaller pieces, with each function performing a specific task.

local function add(a, b)
    return a + b
end

local function divide(a, b)
    return a / b
end

function onStart()
    local result1 = divide(10, 2)

    print(result1)  <-- Prints '5'

    local result2 = add(result1, 3)

    print(result2) <-- Prints '8'
end

When the above program runs:

1. add() and divide() are declared as local functions.
2. onStart() calls the divide() function and passes 10 and 2 to it and the result of executing divide() is assigned to a local variable result1.
3. result1 is printed.
4. The add() function is called and result1 and 3 are passed to it and the result of executing add() is assigned to a local variable result2
5. result2 is printed.