Version: Next

# Functions

LIGO functions are the basic building block of contracts. For example, entrypoints are functions and each smart contract needs a main function that dispatches control to the entrypoints (it is not already the default entrypoint).

The semantics of function calls in LIGO is that of a copy of the arguments but also of the environment. In the case of PascaLIGO, this means that any mutation (assignment) on variables outside the scope of the function will be lost when the function returns, just as the mutations inside the functions will be.

## Declaring Functions#

There are two ways in PascaLIGO to define functions: with or without a block.

### Blocks#

In PascaLIGO, blocks enable the sequential composition of instructions into an isolated scope. Each block needs to include at least one instruction.

block { a := a + 1 }

If we need a placeholder, we use the instruction `skip` which leaves the state unchanged. The rationale for `skip` instead of a truly empty block is that it prevents you from writing an empty block by mistake.

block { skip }

Blocks are more versatile than simply containing instructions: they can also include declarations of values, like so:

block { const a : int = 1 }

Functions in PascaLIGO are defined using the `function` keyword followed by their `name`, `parameters` and `return` type definitions.

Here is how you define a basic function that computes the sum of two integers:

function add (const a : int; const b : int) : int is
block {
const sum : int = a + b
} with sum

The function body consists of two parts:

• `block { <instructions and declarations> }` is the logic of the function;
• `with <value>` is the value returned by the function.

By default, LIGO will warn about unused parameters inside functions. In case we do not use a parameter, we can use the wildcard `_` to prevent warnings. Either use `_` instead of the parameter identifier:

function k (const x : int; const _ : int) is x

or use a parameter identifier starting with wildcard:

function k (const x : int; const _y : int) is x

### Blockless functions#

Functions that can contain all of their logic into a single expression can be defined without the need of a block:

function identity (const n : int) : int is block { skip } with n // Bad! Empty block not needed!
function identity (const n : int) : int is n // Blockless

The value of the expression is implicitly returned by the function. Another example is as follows:

function add (const a: int; const b : int) : int is a + b

You can call the function `add` defined above using the LIGO compiler like this:

ligo evaluate-call gitlab-pages/docs/language-basics/src/functions/blockless.ligo add '(1,2)'
# Outputs: 3

## Anonymous functions (a.k.a. lambdas)#

It is possible to define functions without assigning them a name. They are useful when you want to pass them as arguments, or assign them to a key in a record or a map.

Here is how to define an anonymous function:

function increment (const b : int) : int is
(function (const a : int) : int is a + 1) (b)
const a : int = increment (1); // a = 2

You can check the value of `a` defined above using the LIGO compiler like this:

ligo evaluate-expr gitlab-pages/docs/language-basics/src/functions/anon.ligo a
# Outputs: 2

If the example above seems contrived, here is a more common design pattern for lambdas: to be used as parameters to functions. Consider the use case of having a list of integers and mapping the increment function to all its elements.

function incr_map (const l : list (int)) : list (int) is
List.map (function (const i : int) : int is i + 1, l)

Note that `list_map` is deprecated.

You can call the function `incr_map` defined above using the LIGO compiler like so:

ligo evaluate-call
gitlab-pages/docs/language-basics/src/functions/incr_map.ligo incr_map
"list [1;2;3]"
# Outputs: [ 2 ; 3 ; 4 ]

## Nested functions (also known as closures)#

It's possible to place functions inside other functions. These functions have access to variables in the same scope.

function closure_example (const i : int) : int is
block {
function closure (const j : int) : int is i + j
} with closure (i)

## Recursive function#

LIGO functions are not recursive by default, the user need to indicate that the function is recursive.

At the moment, recursive function are limited to one (possibly tupled) parameter and recursion is limited to tail recursion (i.e the recursive call should be the last expression of the function).

In PascaLIGO recursive functions are defined using the `recursive` keyword

recursive function sum (const n : int; const acc: int) : int is
if n<1 then acc else sum(n-1,acc+n)
recursive function fibo (const n: int; const n_1: int; const n_0 :int) : int is
if n<2 then n_1 else fibo(n-1,n_1+n_0,n_1)