Calling a Function

Calling a function invokes the function's code. To call a function, use the function's name followed by a list of parameters. Some functions may also take a subject parameter, which is passed in before the function name.

Passing in parameters

Parameters are the inputs to the function. Sometimes these are called arguments.

No parameters

When calling a function with no parameters, the parameter list may be omitted.

// Declaraing a function with no parameters
// Empty parameter list can be omitted from declaration
fn FunctionWithNoParameters {
    // ...
}

fn Example() {
    // Calling the function
    FunctionWithNoParameters()
    FunctionWithNoParameters // empty parameter list can be omitted
}

Positional parameters

Function parameters may be passed in the order they are declared.

fn FunctionWithPositionalParameters(name, age) {
    // ...
}
fn Example() {
    FunctionWithPositionalParameters("Augustus", 25)
}

Named parameters

Function parameters may be passed by name.

fn FunctionWithNamedParameters(name, age) {
    // ...
}
fn Example() {
    FunctionWithNamedParameters(age=25, name="Augustus")
}

A shorthand form for named parameters is also supported, where just writing parameterName= with nothing after the equals sign is the same as writing parameterName=parameterName.

fn FunctionWithNamedParameters(name, age) {
    // ...
}
fn Example() {
    let name = "Augustus"
    let age = 25
    // The following two calls are equivalent
    FunctionWithNamedParameters(name=name, age=age)
    FunctionWithNamedParameters(name=, age=)
}

Functions may require certain parameters to be passed by name. This is done by adding an equals sign (=) after the parameter name in the function signature. Once a parameter requires passing by name, all following parameters must also be passed in by name. This is often used for library functions as it forces the caller to be explicit about what each parameter is, which allows new parameters to be added at a later date without breaking existing code.

// `age` must be passed by name to the function below
fn FunctionWithMandatoryNamedParameters(name, age=) {
    // ...
}
fn Example() {
    // This is accepted
    FunctionWithMandatoryNamedParameters(name="Augustus", age=25)
    
    // This causes a compiler error because 'age' is not passed in as a named parameter
    FunctionWithMandatoryNamedParameters("Augustus", 25)
}

If you want to use a default expression, you can force the caller to pass in the parameter by name by inserting the = before the name of the parameter:

// `age` must be passed by name to the function below,
// but can be omitted if the caller wants to use the default value of `25`
fn FunctionWithDefaultExpression(name, = age=25) {
    // ...
}

Context parameters

Function parameters specified within square brackets ([ and ]) in the function signature will be implicitly passed in from context, if not passed in explicitly.

fn FunctionWithContextParameters(name, [color, radius]) {
    // ...
}
fn Example(name) {
    // The color and radius parameters parameters will be passed in from context
    use color=#ff8800, radius=5
    FunctionWithContextParameters("Augustus")
}

See the Context Parameters page for more details.

Subject parameters

Some functions may take a subject, which is passed in before the function name. Subject parameters will be passed in from context if they are not passed in explicitly. Subject parameters define which entity is the current entity this within the scope of the function.

fn hero.FunctionWithSubjectParameter(action) {
    // ...
}
fn Example() {
    Spawn hero {
        // Can explicitly pass in the subject parameter
        hero.FunctionWithSubjectParameter($jump)
        
        // Or the subject parameter may be passed in from context
        FunctionWithSubjectParameter($jump)
    }
}

See the Subject Parameters page for more details.

Subblocks

Some functions may take a subblock, which is expressed as a block of code after the function parameter list. The subblock may be invoked using the delve keyword.

// the || indicates this function takes a subblock with no callback parameters
fn FunctionWithSubblock() || {
    delve()
}
fn Example() {
    FunctionWithSubblock {
        // This block of code gets called back by the function
    }
}

Subblocks may take a callback parameter list, denoted by a space-separated list before the subblock body. The callback parameter list may be in a different order than the function's parameter list as parameters are first matched by name, then by position.

fn FunctionWithSubblock() |favoriteVegetable, size, color| {
    delve($carrot, 5, #ff8800)
}
fn Example() {
    FunctionWithSubblock food color {
        DrawFood(food=, color=)
    }
}

See the Subblocks page for more details.

Return values

A function may return zero or more values using the return keyword. The return values must be specified in the function signature after the -> symbol. When a return statement is executed, the function immediately exits and the outputs are returned.

fn FunctionWithReturnValue() -> name {
    return "Augustus"
}
fn Example() {
    let name = FunctionWithReturnValue
}

A function may return multiple values. When returning multiple values, the return keyword must be followed by a comma-separated list of identifiers.

fn FunctionWithMultipleReturnValues() -> name, age {
    return "Augustus", 25
}
fn Example() {
    let name, age = FunctionWithMultipleReturnValues
}

If more values are returned than used, only the values at the start are used, the rest are discarded.

fn FunctionWithMultipleReturnValues() -> name, age {
    return "Augustus", 25
}
fn Example() {
    let name = FunctionWithMultipleReturnValues
    Transmission { %(name) } // Displays "Augustus"
}