Extending functions

Function extension is a powerful feature that lets you transform, decorate, or replace a function’s behavior.

You can extend any previously-declared function using the .extend ^{docs ↗} function within a scope. The extension wraps the original function without losing the original definition.

.function {greet}
    name:
    Hello, .name!

.extend {greet}
    .super::uppercase

.greet {world}

Accessing the original

Within the wrapper body, the original function is exposed as .super. Calling it invokes the original with the same arguments.

Parameters

The wrapper body is a lambda. Its explicit parameters, if any, must match the names of the original function’s parameters and let you intercept the arguments the caller passed.

Because .super is the original function itself, it accepts the same arguments. Any argument you pass overrides the one the wrapper was called with, while everything you leave out falls through unchanged.

.function {greet}
    greeting name:
    .greeting, .name!

.extend {greet}
    name:
    .super greeting:{Howdy}

.greet {Hello} {world}

.function {greet}
    greeting name:
    .greeting, .name!

.extend {greet}
    greeting name:
    .super greeting:{.greeting::uppercase}

.greet {Hello} {world}

All wrapper parameters are always optional. You only need to declare the parameters you actually use in the body.

.function {greet}
    greeting name surname:
    .greeting, .name .surname!

.extend {greet}
    name:
    .super name:{.name::uppercase}

.greet {Hello} name:{John} surname:{Doe}

Conditional extension

An optional where inline lambda parameter lets you define a condition that, if not met at call time, lets the whole call fall back to the original definition. Its parameters follow the same rules as the body lambda.

.function {greet}
    greeting name:
    .greeting, .name!

.extend {greet} where:{name: .name::equals {world}}
    greeting:
    .super greeting:{.greeting::uppercase}

.greet {Hello} {world}

.greet {Hello} {John}

.extend {heading} where:{depth: .depth::islower than:{4}}
    content:
    .super background:{teal}

## H2

## H3

## H4