Notice!This is documentation for v5, which is no longer actively maintained.
For up-to-date documentation, see the latest version.
 -->

User-defined functions

Introduction

User-defined functions are functions that you write, as opposed to the
built-in functions in Pine Script®. They are useful to define
calculations that you must do repetitevely, or that you want to isolate
from your script's main section of calculations. Think of user-defined
functions as a way to extend the capabilities of Pine Script, when no
built-in function will do what you need.

You can write your functions in two ways:

In a single line, when they are simple, or

On multiple lines

Functions can be located in two places:

If a function is only used in one script, you can include it in the
script where it is used. See our
Style guide for recommendations on where to place functions in your
script.

You can create a Pine Script
library to include
your functions, which makes them reusable in other scripts without
having to copy their code. Distinct requirements exist for library
functions. They are explained in the page on
libraries.

Whether they use one line or multiple lines, user-defined functions have
the following characteristics:

They cannot be embedded. All functions are defined in the script's
global scope.

They do not support recursion. It is not allowed for a function
to call itself from within its own code.

The type of the value returned by a function is determined
automatically and depends on the type of arguments used in each
particular function call.

A function's returned value is that of the last value in the
function's body.

Each instance of a function call in a script maintains its own,
independent history.

Single-line functions

Simple functions can often be written in one line. This is the formal
definition of single-line functions:

<function_declaration>

 <identifier>(<parameter_list>) => <return_value>

<parameter_list>

 {<parameter_definition>{, <parameter_definition>}}

<parameter_definition>

 [<identifier> = <default_value>]

<return_value>

 <statement> | <expression> | <tuple>

Here is an example:

f(x, y) => x + y

After the function f() has been declared, it's possible to call it
using different types of arguments:

a = f(open, close)
b = f(2, 2)
c = f(open, 2)

In the example above, the type of variable a is series because the
arguments are both series. The type of variable b is integer
because arguments are both literal integers. The type of variable c
is series because the addition of a series and literal integer
produces a series result.

Multi-line functions

Pine Script also supports multi-line functions with the following
syntax:

<identifier>(<parameter_list>) =>

 <local_block>

<identifier>(<list of parameters>) =>

 <variable declaration>

 ...

 <variable declaration or expression>

where:

<parameter_list>

 {<parameter_definition>{, <parameter_definition>}}

<parameter_definition>

 [<identifier> = <default_value>]

The body of a multi-line function consists of several statements. Each
statement is placed on a separate line and must be preceded by 1
indentation (4 spaces or 1 tab). The indentation before the statement
indicates that it is a part of the body of the function and not part of
the script's global scope. After the function's code, the first
statement without an indent indicates the body of the function has
ended.

Either an expression or a declared variable should be the last statement
of the function's body. The result of this expression (or variable)
will be the result of the function's call. For example:

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

The function geom_average has two arguments and creates two variables
in the body: a and b. The last statement calls the function
math.sqrt (an extraction of the square root). The geom_average call
will return the value of the last expression: (math.sqrt(a + b)).

Scopes in the script

Variables declared outside the body of a function or of other local
blocks belong to the global scope. User-declared and built-in
functions, as well as built-in variables also belong to the global
scope.

Each function has its own local scope. All the variables declared
within the function, as well as the function's arguments, belong to the
scope of that function, meaning that it is impossible to reference them
from outside --- e.g., from the global scope or the local scope of
another function.

On the other hand, since it is possible to refer to any variable or
function declared in the global scope from the scope of a function
(except for self-referencing recursive calls), one can say that the
local scope is embedded into the global scope.

In Pine Script, nested functions are not allowed, i.e., one cannot
declare a function inside another one. All user functions are declared
in the global scope. Local scopes cannot intersect with each other.

Functions that return multiple results

In most cases a function returns only one result, but it is possible to
return a list of results (a tuple-like result):

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

Special syntax is required for calling such functions:

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

Limitations

User-defined functions can use any of the Pine Script built-ins,
except:
barcolor(),
fill(),
hline(),
indicator(),
library(),
plot(),
plotbar(),
plotcandle(),
plotchar(),
plotshape()
and
strategy().