Function declarations

A function declaration gives reusable code a name. It is useful when several places need the same calculation or sequence of changes.

Declare and call a function

var health = 75;

fn healthLabel() {
  format("{} HP", health)
}

text "@1 checks their status: {}." with healthLabel();

Read the declaration by its syntax:

• fn begins a function declaration.
• healthLabel is the function’s name.
• () contains its parameters. This function has none.
• { ... } is the function body.
• The final expression is the value the function returns.

The final line calls it by writing its name followed by parentheses:

healthLabel()

The declaration defines the function. The call runs it.

Parameters and arguments

A parameter is a local name declared by a function. An argument is a value supplied by a call.

fn healthLabel(name, health) {
  format("{} has {} HP", name, health)
}

text healthLabel("Alex", 75);

In the declaration, name and health are parameters. Inside the function body, they behave like local variables.

In the call, "Alex" and 75 are arguments. Sugar assigns them to the parameters by position: name receives "Alex", then health receives 75.

Default parameter values

A parameter may provide a default:

fn healthLabel(name, health, suffix = " HP") {
  format("{} has {}{}", name, health, suffix)
}

Both calls are valid:

healthLabel("Alex", 75)
healthLabel("Alex", 75, " health")

The first call uses the default suffix. The second replaces it. Required parameters must appear before parameters with defaults.

Return a value

Sugar returns a function’s final expression automatically:

fn double(value) {
  value * 2
}

Use return when the function must stop earlier:

fn describeRoll(roll) {
  if roll == 20 {
    return "a perfect 20";
  }

  format("a {}", roll)
}

return; stops without returning a value. Code after a return does not run.

Change state without returning a value

A function may perform assignments and finish without a final expression:

var health = 75;

fn heal(amount) {
  health = clamp(health + amount, 0, 100);
}

text {
  heal(10);
  "Health: {health}"
}

heal(10); is used as a statement because the function changes health instead of producing a value for another expression.

Function scope

Parameters and let variables declared inside a function belong only to that call. Top-level variables from the same Code module are also available to the function.

A top-level function can be called by every text and Item action in that module. The order of top-level declarations does not matter.

Functions may call other functions, but recursion is not supported: a function cannot eventually call itself.

Later, the Apps lesson extends the same declaration with App and hosted scope. The next lesson introduces lists and objects, then closures: unnamed function-like values passed directly to another operation.