> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ton.org/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.ton.org/feedback

```json
{
  "path": "/tolk/basic-syntax",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Basic syntax

## Imports

[Imports](/languages/tolk/syntax/imports) must appear at the top of the file:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
import "another-file"

// Symbols from `another-file.tolk` become available in this file.
```

In most workflows, the IDE adds imports automatically. For example, when selecting an item from auto-completion.

The entire file is imported. There are no modules or exports; all symbols must have unique names within the project.

## Structures

A [struct](/languages/tolk/syntax/structures-fields) `Point` holding two 8-bit integers:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
struct Point {
    x: int8
    y: int8
}

fun demo() {
    // create an object
    val p1: Point = { x: 10, y: 20 };

    // the same, type of p2 is auto-inferred
    val p2 = Point { x: 10, y: 20 };
}
```

* Methods are declared as `fun Point.method(self)`.
* Fields can use any [types](/languages/tolk/types/list-of-types): numeric, cell, union, and others.
* Fields can define default values: `x: int8 = 0`.
* Fields can be `private` and `readonly`.
* Structs can be generic: `struct Wrapper<T> { ... }`.

If all fields are serializable, a struct can be [automatically serialized](/languages/tolk/features/auto-serialization):

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// makes a cell containing hex "0A14"
val c = p1.toCell();
// back to { x: 10, y: 20 }
val p3 = Point.fromCell(c);
```

## Functions

A [function](/languages/tolk/syntax/functions-methods) that returns the sum of two integers:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun sum(a: int, b: int): int {
    return a + b;
}
```

* Parameter types are mandatory.
* The return type can be omitted: it is auto-inferred.
* Parameters can define default values: `fun f(b: int = 0)`
* Statements in a block are separated by semicolons `;`.
* Generic functions are supported: `fun f<T>(value: T) { ... }`
* Assembler functions are supported: `fun f(...): int asm "..."`

## Methods

A function declared as `fun <receiver>.name(...)` is a [method](/languages/tolk/syntax/functions-methods).

* If the first parameter is `self`, it's an instance method.
* If the first parameter is not `self`, it's a static method.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// `self` — instance method (invoked on a value)
fun Point.sumCoords(self) {
    return sum(self.x, self.y);
}

// not `self` — static method
fun Point.createZero(): Point {
    return { x: 0, y: 0 };
}

fun demo() {
    val p = Point.createZero();    // { 0, 0 }
    return p.sumCoords();          // 0
}
```

By default, `self` is immutable; `mutate self` allows modifying the object.

Methods can be declared for any type, including primitives:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun int.isNegative(self) {
    return self < 0
}
```

## Variables

Within functions, [variables](/languages/tolk/syntax/variables) are declared with `val` or `var` keywords. The `val` keyword declares an immutable variable that can be assigned only once:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
val coeff = 5;
// cannot change its value, `coeff += 1` is an error
```

The `var` keyword declares a variable that can be reassigned:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
var x = 5;
x += 1;      // now 6
```

A variable’s type can be specified after its name:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
var x: int8 = 5;
```

Declaring variables at the top level, outside functions, is supported using the `global` keyword.

## Constants

Constants can be declared only at the top level, not inside functions:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const ONE = 1
const MAX_AMOUNT = ton("0.05")
const ADMIN_ADDRESS = address("EQ...")
```

To group integer constants, [enums](/languages/tolk/types/enums) are useful.

## Value semantics

Tolk follows value semantics: assignments create independent copies, and function calls do not [mutate](/languages/tolk/syntax/mutability) arguments unless explicitly specified.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
var a = Point { x: 1, y: 2 };
var b = a;   // `b` is a copy
b.x = 99;    // `a.x` remains 1
someFn(a);   // pass a copy; `a` will not change

// but there can be mutating functions, called this way:
anotherFn(mutate a);
```

## Semicolons

* Semicolons are optional at the top level, after imports, aliases, etc.
* Semicolons are required between statements in a function.
* After the last statement in a block, a semicolon is optional.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// optional at the top-level
const ONE = 1
type UserId = int

// required inside functions
fun demo() {
    val x = 5;
    val y = 6;
    return x + y    // optional after the last statement
}
```

## Comments

Tolk supports single-line or end-of-line and multi-line or block comments:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
// This is a single-line comment

/* This is a block comment
   across multiple lines. */

const TWO = 1 /* + 100 */ + 1    // 2
```

## Conditional operators

In [conditions](/languages/tolk/syntax/conditions-loops), `if` is a statement. `else if` and `else` blocks are optional.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun sortNumbers(a: int, b: int) {
    if (a > b) {
        return (b, a)
    } else {
        return (a, b)
    }
}
```

A ternary operator is also available:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
val sign = a > 0 ? 1 : a < 0 ? -1 : 0;
```

## Union types and matching

[Union types](/languages/tolk/types/unions) allow a variable to hold one of possible types. They are typically handled by `match`:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun processValue(value: int | slice) {
    match (value) {
        int => {
            value * 2
        }
        slice => {
            value.loadUint(8)
        }
    }
}
```

Alternatively, test a union with `is` or `!is` operators:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun processValue(value: int | slice) {
    if (value is slice) {
        // call methods for `slice`
        return;
    }
    // value is `int`
    return value * 2;
}
```

Union types are commonly used when [handling incoming messages](/languages/tolk/features/message-handling).

## While loop

Tolk does not have a `for` loop; use [`while` loop](/languages/tolk/syntax/conditions-loops) for repeated execution.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
while (i > 0) {
    // ...
    i -= 1;
}
```

## Assert and throw

The `try-catch` statement is supported for [exceptions](/languages/tolk/syntax/exceptions), although it is not commonly used in contracts.

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
const ERROR_NO_BALANCE = 403;

// in some function
throw ERROR_NO_BALANCE;

// or conditional throw
assert (balance > 0) throw ERROR_NO_BALANCE;
```

## Arrays

[Arrays](/languages/tolk/types/tuples) are dynamically sized containers created with `[...]`:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
var numbers = [1, 2, 3];    // array<int>
numbers.push(4);
numbers.get(0);              // 1
```

## Iterate over a map

To iterate, [maps](/languages/tolk/types/maps) can be used:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
fun iterateOverMap(m: map<int32, Point>) {
    var r = m.findFirst();
    while (r.isFound) {
        // ...
        r = m.iterateNext(r);
    }
}
```

## Send a message to another contract

To [construct and send a message](/languages/tolk/features/message-sending), a message body is typically represented by a structure. For example, `RequestedInfo`:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
val reply = createMessage({
    bounce: BounceMode.NoBounce,
    value: ton("0.05"),
    dest: someAddress,
    body: RequestedInfo { ... }
});
reply.send(SEND_MODE_REGULAR);
```

## Contract getters

[Contract getters](/languages/tolk/features/contract-getters) or get-methods are declared with `get fun`:

```tolk theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
get fun currentOwner() {
    val storage = lazy Storage.load();
    return storage.ownerAddress;
}
```