User-Defined Functions

User-Defined Functions in Pine Script

Introduction

User-defined functions, crafted by the user in contrast to the built-in functions available in Pine Script, offer the ability to define custom calculations needed frequently or to segregate a portion of calculations from the script's main section. User-defined functions can essentially extend the capabilities of Pine Script when built-in functions are not suitable for specific needs.

User-defined functions can be written in two forms:

1. Single-line functions: Ideal for simple calculations.

2. Multi-line functions: For complex calculations requiring multiple lines.

Moreover, these functions can be positioned in two places:

1. Within the script where they're being used, if they're specific to that script only.

2. In a Pine Script library, making them reusable in other scripts without code replication. Distinct requirements exist for library functions, explained in the Pine Script Libraries section.

Regardless of whether they're written in a single line or multiple lines, user-defined functions share some common characteristics:

• They cannot be nested; all functions are defined in the global scope of the script.

• They don't support recursion; a function cannot call itself from within its code.

• The return type is determined automatically, based on the type of arguments used in each function call.

Single-Line Functions

Single-line functions, often ideal for simple computations, follow this structure:

<function_name>(<parameter_list>) => <return_value>

Here's an example of a single-line function that adds two numbers:

f(x, y) => x + y

Once defined, you can call this function using various argument types:

a = f(open, close) // a is series type
b = f(2, 2) // b is integer type
c = f(open, 2) // c is series type

Multi-Line Functions

Multi-line functions in Pine Script are handy for complex calculations, and they follow this structure:

<function_name>(<parameter_list>) =>
    <local_block>

The body of a multi-line function contains several statements. Each statement must be placed on a separate line and be preceded by 1 indentation (4 spaces or 1 tab). The last statement of the function's body (either an expression or a declared variable) will be the result of the function's call.

Here's an example of a multi-line function:

geom_average(x, y) =>
    a = x*x
    b = y*y
    math.sqrt(a + b)

Scope in Scripts

Variables declared outside a function belong to the global scope, as do user-declared and built-in functions and variables. Each function has its local scope, including all the variables declared within the function and the function's arguments.

Functions cannot access variables from other functions' local scopes, but they can reference any global scope variable or function (except for recursive calls).

Functions Returning Multiple Results

While most functions return a single result, Pine Script allows functions to return multiple results as a list or tuple-like result:

fun(x, y) =>
    a = x + y
    b = x - y
    [a, b]

To call such functions, use the following syntax:

[res0, res1] = fun(open, close)
plot(res0)
plot(res1)

Limitations

Despite their versatility, user-defined functions in Pine Script have some limitations:

• All functions are defined in the script’s global scope and cannot be nested.

• Functions do not support recursion.

• The type of the value returned by a function depends on the type of arguments used in each function call.