From 038ddac875ee34c992f4682b6d280e34d0741f9c Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Thu, 11 Dec 2025 21:27:31 +0700 Subject: [PATCH 1/3] basic-syntax --- languages/tolk/basic-syntax.mdx | 126 ++++++++++++-------------------- 1 file changed, 48 insertions(+), 78 deletions(-) diff --git a/languages/tolk/basic-syntax.mdx b/languages/tolk/basic-syntax.mdx index 2dc74f69e..8cb78842d 100644 --- a/languages/tolk/basic-syntax.mdx +++ b/languages/tolk/basic-syntax.mdx @@ -1,35 +1,25 @@ --- -title: "Tolk basic syntax" +title: "Basic syntax" sidebarTitle: "Basic syntax" --- -import { Aside } from '/snippets/aside.jsx'; - -Syntax of Tolk is similar to TypeScript, Rust, and Kotlin. It is designed to be straightforward to read and write. - -Below is a list of basic syntax elements with examples. Most sections end with a link to a detailed topic. - ## Imports -Imports exist at the top of the file: +[Imports](/languages/tolk/syntax/imports) must appear at the top of the file: ```tolk import "another-file" -// symbols from `another-file.tolk` can now be used +// Symbols from `another-file.tolk` become available in this file. ``` -In typical workflows, an IDE inserts imports automatically (for example, when selecting an element from auto‑completion). +In most workflows, the IDE adds imports automatically. For example, when selecting an item from auto-completion. - - -See: [imports](/languages/tolk/syntax/imports). +The entire file is imported. There are no modules or exports; all symbols must have unique names within the project. ## Structures -A struct `Point` holding two 8-bit integers: +A [struct](/languages/tolk/syntax/structures-fields) `Point` holding two 8-bit integers: ```tolk struct Point { @@ -46,11 +36,11 @@ fun demo() { } ``` -- methods are declared like `fun Point.method(self)`, read below -- fields can be of any types: numeric, cell, union, etc. (see [type system](/languages/tolk/types/list-of-types)) -- fields can have default values: `x: int8 = 0` -- fields can be `private` and `readonly` -- structs can be generic: `struct Wrapper { ... }` +- 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 { ... }`. If all fields are serializable, a struct can be [automatically serialized](/languages/tolk/features/auto-serialization): @@ -61,11 +51,9 @@ val c = p1.toCell(); val p3 = Point.fromCell(c); ``` -See: [structures](/languages/tolk/syntax/structures-fields). - ## Functions -A function that calculates the sum of two integers: +A [function](/languages/tolk/syntax/functions-methods) that returns the sum of two integers: ```tolk fun sum(a: int, b: int): int { @@ -73,21 +61,19 @@ fun sum(a: int, b: int): int { } ``` -- parameter types are mandatory -- the return type can be omitted: it will be auto-inferred, like in TypeScript -- parameters can have a default value: `fun f(b: int = 0)` -- statements inside a block are separated by semicolons `;` -- generic functions: `fun f(value: T) { ... }` -- assembler functions: `fun f(...): int asm "..."` - -See: [functions and methods](/languages/tolk/syntax/functions-methods). +- 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(value: T) { ... }` +- Assembler functions are supported: `fun f(...): int asm "..."` ## Methods -A function declared as `fun .name(...)` is a method. +A function declared as `fun .name(...)` is a [method](/languages/tolk/syntax/functions-methods). -- if the first parameter is `self`, it's an **instance method** -- if not `self`, it's a **static method** +- 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) @@ -106,8 +92,9 @@ fun demo() { } ``` -- by default, `self` is immutable, but `mutate self` allows modifying an object -- methods may be declared not only for a struct, but for any type, even a primitive: +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) { @@ -115,39 +102,35 @@ fun int.isNegative(self) { } ``` -See: [functions and methods](/languages/tolk/syntax/functions-methods). - ## Variables -Inside functions, variables are declared with `val` or `var` keywords. - -The `val` keyword declares a variable that is assigned exactly once (immutable): +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 val coeff = 5; // cannot change its value, `coeff += 1` is an error ``` -The `var` keyword declares a variable that may be reassigned: +The `var` keyword declares a variable that can be reassigned: ```tolk var x = 5; x += 1; // now 6 ``` -Variable's type can be specified after its name: +A variable’s type can be specified after its name: ```tolk var x: int8 = 5; ``` -Declaring variables at the top-level (not inside functions) is supported via `global` keyword. -See: [variables](/languages/tolk/syntax/variables). +Declaring variables at the top level, outside functions, is supported using the `global` keyword. + ## Constants -Declaring constants is allowed at the top-level (not inside functions): +Constants can be declared only at the top level, not inside functions: ```tolk const ONE = 1 @@ -155,11 +138,11 @@ const MAX_AMOUNT = ton("0.05") const ADMIN_ADDRESS = address("EQ...") ``` -To group integer constants, [enums](/languages/tolk/types/enums) are also useful. +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 arguments unless explicitly specified. +Tolk follows value semantics: assignments create independent copies, and function calls do not [mutate](/languages/tolk/syntax/mutability) arguments unless explicitly specified. ```tolk var a = Point { x: 1, y: 2 }; @@ -171,13 +154,11 @@ someFn(a); // pass a copy; `a` will not change anotherFn(mutate a); ``` -See: [mutability](/languages/tolk/syntax/mutability). - ## Semicolons -- semicolons are **optional at the top-level** (after imports, aliases, etc.) -- **required between statements in a function** -- after the last statement in a block, it's also optional +- 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 @@ -194,7 +175,7 @@ fun demo() { ## Comments -Like most modern languages, Tolk supports single-line (or end-of-line) and multi-line (block) comments: +Tolk supports single-line or end-of-line and multi-line or block comments: ```tolk // This is a single-line comment @@ -207,6 +188,8 @@ 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 fun sortNumbers(a: int, b: int) { if (a > b) { @@ -217,19 +200,15 @@ fun sortNumbers(a: int, b: int) { } ``` -In Tolk, `if` is a statement, with `else if` and `else` optional blocks. - A ternary operator is also available: ```tolk val sign = a > 0 ? 1 : a < 0 ? -1 : 0; ``` -See: [conditions and loops](/languages/tolk/syntax/conditions-loops). - ## Union types and matching -Union types allow a variable to hold "one of possible types". They are typically handled by `match`: +[Union types](/languages/tolk/types/unions) allow a variable to hold one of possible types. They are typically handled by `match`: ```tolk fun processValue(value: int | slice) { @@ -257,12 +236,12 @@ fun processValue(value: int | slice) { } ``` -Unions types are commonly used when [handling incoming messages](/languages/tolk/features/message-handling). - -See: [union types](/languages/tolk/types/unions). +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 while (i > 0) { // ... @@ -270,12 +249,10 @@ while (i > 0) { } ``` -The `for` loop does not exist. - -See: [conditions and loops](/languages/tolk/syntax/conditions-loops). - ## Assert and throw +[Exceptions](/languages/tolk/syntax/exceptions) with `try-catch` statement is supported, although it is not commonly used in contracts. + ```tolk const ERROR_NO_BALANCE = 403; @@ -286,12 +263,9 @@ throw ERROR_NO_BALANCE; assert (balance > 0) throw ERROR_NO_BALANCE; ``` -A try-catch statement is also supported, although it is not commonly used in contracts. - -See: [exceptions](/languages/tolk/syntax/exceptions). - ## Iterate over a map +To iterate, [maps](/languages/tolk/types/maps) can be used: ```tolk fun iterateOverMap(m: map) { var r = m.findFirst(); @@ -302,11 +276,9 @@ fun iterateOverMap(m: map) { } ``` -See: [maps](/languages/tolk/types/maps). - ## Send a message to another contract -An outgoing message body is typically represented by a structure (for example, `RequestedInfo`). +To [construct and send a message](/languages/tolk/features/message-sending), a message body is typically represented by a structure. For example, `RequestedInfo`: ```tolk val reply = createMessage({ @@ -318,11 +290,9 @@ val reply = createMessage({ reply.send(SEND_MODE_REGULAR); ``` -See: [constructing and sending messages](/languages/tolk/features/message-sending). - ## Contract getters -Contract getters (or "get methods") are declared with `get fun`: +[Contract getters](/languages/tolk/features/contract-getters) or get-methods are declared with `get fun`: ```tolk get fun currentOwner() { @@ -331,4 +301,4 @@ get fun currentOwner() { } ``` -See: [contract getters](/languages/tolk/features/contract-getters). + From 5aa258c30fe3189b8153e444d3da9a5bf7b6a5b4 Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Thu, 11 Dec 2025 21:31:46 +0700 Subject: [PATCH 2/3] basic-syntax --- languages/tolk/basic-syntax.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/languages/tolk/basic-syntax.mdx b/languages/tolk/basic-syntax.mdx index 8cb78842d..40e3b9824 100644 --- a/languages/tolk/basic-syntax.mdx +++ b/languages/tolk/basic-syntax.mdx @@ -124,10 +124,8 @@ A variable’s type can be specified after its name: 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: @@ -266,6 +264,7 @@ assert (balance > 0) throw ERROR_NO_BALANCE; ## Iterate over a map To iterate, [maps](/languages/tolk/types/maps) can be used: + ```tolk fun iterateOverMap(m: map) { var r = m.findFirst(); @@ -300,5 +299,3 @@ get fun currentOwner() { return storage.ownerAddress; } ``` - - From 3ce00bcd7e02a6dd27946cba9a9c8996d5e7f7e2 Mon Sep 17 00:00:00 2001 From: aigerimu <89766357+aigerimu@users.noreply.github.com> Date: Thu, 18 Dec 2025 21:59:55 +0700 Subject: [PATCH 3/3] upd --- languages/tolk/basic-syntax.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/languages/tolk/basic-syntax.mdx b/languages/tolk/basic-syntax.mdx index 40e3b9824..6bb01f385 100644 --- a/languages/tolk/basic-syntax.mdx +++ b/languages/tolk/basic-syntax.mdx @@ -249,7 +249,7 @@ while (i > 0) { ## Assert and throw -[Exceptions](/languages/tolk/syntax/exceptions) with `try-catch` statement is supported, although it is not commonly used in contracts. +The `try-catch` statement is supported for [exceptions](/languages/tolk/syntax/exceptions), although it is not commonly used in contracts. ```tolk const ERROR_NO_BALANCE = 403;