# extend

    .extend name:{String} \
           where:{Lambda? = null} \
            body:{Lambda}
    -> Void

Content copied to clipboard

Defines a custom function that extends an existing one by name, wrapping its output.

Within the body, the original function is exposed as `.super`: calling it invokes the original with the arguments the wrapper was called with. The body's explicit parameters, if any, must match the original function's parameters by name and let the wrapper read those same arguments. All wrapper parameters are optional, regardless of whether the original parameters are.

    .function {greet}
        name:
        Hello, .name

    .extend {greet}
        .super::uppercase

    .greet {World}

Content copied to clipboard

> Output: `HELLO, WORLD`

The wrapper can reference the original parameters by name to alter the behavior conditionally:

    .extend {greet}
        name:
        .if {.name::equals {World}}
            .super::uppercase
        .ifnot {.name::equals {World}}
            .super

Content copied to clipboard

Because `.super` is the original function itself, it accepts the same arguments. Anything you pass overrides the corresponding argument the wrapper was called with, while anything you leave out falls through unchanged:

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

    .greet {John}

Content copied to clipboard

> Output: `Hello, JOHN`

If where is defined, it is checked against every function call. If the condition is not met, the call falls back to the original function definition. The following snippets have identical behavior:

-       .extend {greet} where:{name: .name::equals {World}}
            name:
            .super::uppercase

  Content copied to clipboard

-       .extend {greet}
            name:
            .if {.name::equals {World}}
                .super::uppercase
            .ifnot {.name::equals {World}}
                .super

  Content copied to clipboard

Function extension is the backbone of element styling, when extending primitive functions such as heading.

#### Parameters

name

name of the existing function to extend

where

- Optional

optional condition to meet. Takes the same parameters as body. If the condition is not met, the call falls back to the original function definition

body

- Likely a body argument

wrapper content. Its explicit parameters, if any, must match the original function's parameter names. `.super` is implicitly available within the body

#### Throws

IllegalArgumentException

if no function named name exists, or if any explicit parameter does not match an original parameter

#### Wiki page

extending-functions