# Basic syntax (https://docs-orhepa2tm-ton-core-docs.vercel.app/llms/tolk/basic-syntax/content.md)



## Imports [#imports]

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

```tolk
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 [#structures]

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

```tolk
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](/llms/languages/tolk/types/list-of-types/content.md): 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](/llms/languages/tolk/features/auto-serialization/content.md):

```tolk
// makes a cell containing hex "0A14"
val c = p1.toCell();
// back to { x: 10, y: 20 }
val p3 = Point.fromCell(c);
```

## Functions [#functions]

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

```tolk
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 [#methods]

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

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

```tolk
// `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
fun int.isNegative(self) {
    return self < 0
}
```

## Variables [#variables]

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

```tolk
val coeff = 5;
// cannot change its value, `coeff += 1` is an error
```

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

```tolk
var x = 5;
x += 1;      // now 6
```

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

```tolk
var x: int8 = 5;
```

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

## Constants [#constants]

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

```tolk
const ONE = 1
const MAX_AMOUNT = grams("0.05")
const ADMIN_ADDRESS = address("EQ...")
```

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

## Value semantics [#value-semantics]

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

```tolk
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]

* 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
// 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 [#comments]

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

```tolk
// This is a single-line comment

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

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

## Conditional operators [#conditional-operators]

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

```tolk
fun sortNumbers(a: int, b: int) {
    if (a > b) {
        return (b, a)
    } else {
        return (a, b)
    }
}
```

A ternary operator is also available:

```tolk
val sign = a > 0 ? 1 : a < 0 ? -1 : 0;
```

## Union types and matching [#union-types-and-matching]

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

```tolk
fun processValue(value: int | slice) {
    match (value) {
        int => {
            value * 2
        }
        slice => {
            value.loadUint(8)
        }
    }
}
```

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

```tolk
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](/llms/languages/tolk/features/message-handling/content.md).

## While loop [#while-loop]

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

```tolk
while (i > 0) {
    // ...
    i -= 1;
}
```

## Assert and throw [#assert-and-throw]

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

```tolk
const ERROR_NO_BALANCE = 403;

// in some function
throw ERROR_NO_BALANCE;

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

## Arrays [#arrays]

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

```tolk
var numbers = [1, 2, 3];    // array<int>
numbers.push(4);
numbers.get(0);              // 1
```

## Iterate over a map [#iterate-over-a-map]

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

```tolk
fun iterateOverMap(m: map<int32, Point>) {
    var r = m.findFirst();
    while (r.isFound) {
        // ...
        r = m.iterateNext(r);
    }
}
```

## Send a message to another contract [#send-a-message-to-another-contract]

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

```tolk
val reply = createMessage({
    bounce: BounceMode.NoBounce,
    value: grams("0.05"),
    dest: someAddress,
    body: RequestedInfo { ... }
});
reply.send(SEND_MODE_REGULAR);
```

## Contract getters [#contract-getters]

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

```tolk
get fun currentOwner() {
    val storage = lazy Storage.load();
    return storage.ownerAddress;
}
```