Functions in Sncode

NAME

functions - How to define and call functions in Sncode.

DESCRIPTION

A function is a reusable segment of code that accepts arguments and returns a value.

Notion of scope

Defining symbols like variables consists in binding a name to a value or an entity in memory. Areas in the code where those symbols are accessible to the developer are called scopes.

Variables defined within a function are called local symbols since they don't exist outside of the function's scope.

Functions on the other hand are considered global in the sense that once they are defined (either explicitly or via an include), they are accessibles from anywhere in your script.

The Sncode Library already exposes a series of useful functions to the global scope, but developers can create new ones dynamically called user functions.

Arguments

By default, an argument is passed by value to a function. This means that when the function is called, the value of the argument is copied into a local variable of the same name.

Arguments are either positional or named. A positional argument is simply a value that is passed to the function in a specific order whereas a named argument must have its name explicitly declared along its value.

By default, functions do not accept any argument if the signature is empty.

Arguments listed in the signature are mandatory. When listing arguments, the semi-colon (;) is used to separate positional from named arguments.

Adding the ... symbol allows an infinite number of undefined arguments to be passed to the function after the mandatory ones. This is useful when you want to perform an action on an unknown number of arguments.

Let's consider this function definition:

function f(p1, p2, ... ; n1, n2, ...) 
endf

p1 and p2 are positional arguments whereas n1 and n2 are named arguments.

In short, the function f requires 4 arguments and accepts a variable number of other arguments as well.

Return expression

The return keyword is used to return the value of an expression:

return a;

A function always returns a value. If no return expression is specified, the function returns a null value by default.

A function stops its execution as soon as a value is returned.

Built-in local variables

The following local variables are automatically accessible within any user function:

• sn_argcp: Number of positional arguments
• sn_argcn: Number of named arguments
• argc: Number of arguments
• sn_argsn: Associative array of named arguments
• sn_argsp: Array of positional arguments

To access positional arguments within your function:

sn_argsp[0]; // position starts at 0

To access named arguments within your function:

sn_argsn.n1 // replace "n1" by the name of your argument

Calling a function

A function call starts with the function name, followed by its arguments between parentheses:

f(1, 2, 3, n1: "a", n2: "b");

It is recommended to pass positional arguments first, followed by named arguments, but the opposite is supported as well.

A function can also be called dynamically by using the character @:

f = "abs";
@f(-1); // the "abs" function will be called instead of "f"

This way, we can tell Sncode to fetch the function's name from the value of the variable f. This is useful when the function name is only known at runtime.

EXAMPLES

Declaring a function with

No arguments:

function f()
endf

Only a variable number of positional arguments:

function f(...)
endf

Only a variable number of named arguments:

function f(;...)
endf

A variable number of both positional and named arguments:

function f(...;...)
endf

A mix of mandatory and optional positional arguments:

function f(a, b, ...)
endf

A mix of mandatory and optional named arguments:

function f(;a, b, ...)
endf

Both positional and named mandatory arguments:

function f(a, b ; c, d)
endf

Variables

Checking if a named argument is defined and assigning a default value to it otherwise:

function f(;...)
    if a == undefined then
        a = 1;
    endif
endf

AUTHOR

Written by Pierre Laplante, <laplante@sednove.com> and Jean-Georges Guenard, <jg@sednove.com>