doc: add book,internal,reference,builtins sections

2026-10-19 11:11:43 +03:00
parent 306be6b82d
commit 81d07aa6e5
14 changed files with 420 additions and 2 deletions
@@ -41,7 +41,6 @@ Available flags:

 ---

-Далее: [Первая программа](./02_first-program.md)
+Далее: [Основы и типы](./02_basics-and-types.md)

 Назад: [Вступление](./00_introduction.md)
-
@@ -0,0 +1,53 @@
+# Основы и типы
+
+В этой главе разберём выражения, переменные и значения FZLang.
+Исходный код хранится в файлах с расширением .fzs, а каждая инструкция обычно заканчивается точкой с запятой.
+
+## Литералы
+
+Числа записываются последовательностью десятичных цифр.
+Строки заключаются в одинарные или двойные кавычки, булевы значения — `true` и `false`, пустое значение для объектов — `null`.
+
+```
+int answer = 42;
+str greeting = "hello";
+bool enabled = true;
+```
+
+## Объявление и присваивание
+
+Тип указывается перед именем переменной. Инициализация необязательна:
+
+```
+uint work_it = 21 * 2 ^ 2;
+int make_it = 10;
+u64 do_it;
+do_it = 15;
+```
+
+Поддерживаются машинные `int` и `uint`, знаковые `i8`, `i16`, `i32`, `i64`, беззнаковые `u8`, `u16`, `u32`, `u64`, а также `str`, `char` и `bool`.
+Имена классов используются как типы объектов.
+
+## Арифметика и логика
+
+Доступны операции +, -, *, /, %, ^, сравнения ==, !=, <, <=, >, >= и логические операции &&, ||, !.
+Порядок разбора: унарные операции, степень, умножение/деление/остаток, сложение/вычитание, сравнения, &&, затем ||.
+Скобки меняют порядок вычисления.
+
+Строки поддерживают == и !=, объекты сравниваются по идентичности экземпляра.
+Несовместимые типы отклоняются компилятором.
+
+## Комментарии
+
+Однострочный комментарий начинается с // и продолжается до конца строки.
+
+```
+// Этот текст игнорируется компилятором
+printline("Комментарий пропущен");
+```
+
+---
+
+Далее: [Управление потоком](./03_control-flow.md)
+
+Назад: [Начало работы](./01_getting-started.md)
@@ -0,0 +1,43 @@
+# Управление потоком
+
+FZLang поддерживает условные конструкции и отдельные блоки кода.
+Условия записываются в круглых скобках, тело может быть одной инструкцией или блоком в фигурных скобках.
+
+## Условие if
+
+```
+if (2 + 2 >= 4)
+  printline("two plus two is four");
+else
+{
+  printline("unexpected result");
+  exit(1);
+}
+```
+
+Ветка `else if` является обычным `else`, за которым следует новый `if`.
+Условие вычисляется, после чего ВМ переходит в одну из веток; обычно это булево значение или результат сравнения.
+
+## Блоки
+
+Фигурные скобки создают отдельное окружение:
+
+```
+{
+  int local = 10;
+  printline(local);
+}
+```
+
+После выхода из блока его окружение уничтожается.
+Локальные имена не должны использоваться за пределами блока.
+
+## Ограничения
+
+В текущей реализации нет циклов while или for. Повторяющееся вычисление выражается рекурсивными функциями.
+
+---
+
+Далее: [Функции и рекурсия](./04_functions-and-recursion.md)
+
+Назад: [Основы и типы](./02_basics-and-types.md)
@@ -0,0 +1,44 @@
+# Функции и рекурсия
+
+Функция объявляется ключевым словом `fn`, именем, списком типизированных аргументов и, если функция возвращает значение, типом результата.
+
+```
+fn sum(uint a, uint b) uint
+{
+  return a + b;
+}
+```
+
+Если функция ничего не возвращает, тип после закрывающей скобки можно опустить.
+Вызов записывается как `name(arg1, arg2)`, аргументы передаются в порядке объявления.
+
+## Возврат
+
+return завершает текущую функцию.
+Возвращаемое выражение должно быть совместимо с объявленным типом.
+Пустой return; используется в функции без результата.
+Возврат вне функции — ошибка компиляции.
+
+## Рекурсия
+
+Функция может вызывать саму себя:
+
+```
+fn factorial(uint n) uint
+{
+  if (n <= 1)
+    return 1;
+  return n * factorial(n - 1);
+}
+```
+
+Каждый вызов получает собственное окружение.
+ВМ хранит адрес возврата в стеке вызовов, а локальные значения — в стеке окружений.
+
+При возврате объекта компилятор переносит его владение в родительское окружение.
+
+---
+
+Далее: [Классы и объекты](./05_classes-and-objects.md)
+
+Назад: [Управление потоком](./03_control-flow.md)
@@ -0,0 +1,46 @@
+# Классы и объекты
+
+Класс описывается блоком с полями и методами:
+
+```
+class Point
+{
+  int x;
+  int y;
+
+  fn move(int dx, int dy)
+  {
+    this.x = this.x + dx;
+    this.y = this.y + dy;
+  }
+}
+```
+
+Методы обращаются к полям текущего экземпляра через обязательное имя `this`.
+
+## Создание экземпляра
+
+Экземпляр создаётся выражением `new ClassName`:
+
+```
+Point point = new Point;
+point.x = 1;
+point.y = 2;
+point.move(9, 8);
+```
+
+Объект выделяется с количеством слотов, равным числу полей класса.
+Поля читаются и изменяются через точку.
+Поддерживаются цепочки вроде `list.next.sum()`.
+
+Имя класса выступает типом объекта.
+Переменная может содержать `null`, а объекты одного класса совместимы между собой.
+Сравнение == и != проверяет идентичность экземпляра, а не содержимое полей.
+
+Неизвестный класс или поле приводит к ошибке компиляции.
+
+---
+
+Далее: [Модель памяти](./06_memory-model.md)
+
+Назад: [Функции и рекурсия](./04_functions-and-recursion.md)
@@ -0,0 +1,36 @@
+# Модель памяти
+
+FZLang использует scope-based RAII: объект принадлежит окружению, в котором создан, и освобождается при уничтожении этого окружения.
+Отдельного сборщика мусора нет.
+
+## Окружения
+
+Глобальная программа, функция и каждый блок получают окружение.
+В нём хранятся имена и значения переменных.
+При поиске имени VM проверяет текущее окружение, затем внешние.
+
+После return локальное окружение функции закрывается.
+Возвращаемый объект переносится в родительское окружение, чтобы пережить этот момент.
+
+## Владение объектом
+
+Передача объекта во вложенный вызов позволяет использовать его во внутреннем окружении.
+Операция `ESCAPE_OBJECT` переносит возвращаемый объект и его дочерние объекты наружу.
+
+```
+fn make() Animal
+{
+  Animal result = new Animal;
+  return result;
+}
+```
+
+Числа, булевы значения и строки хранятся как значения контейнера ВМ.
+Объектное значение содержит указатель на структуру экземпляра, а поля занимают числовые слоты класса.
+
+Объект не следует использовать после завершения окружения, которому он принадлежал.
+Возвращайте его из функции или храните в объекте/окружении с большим временем жизни.
+
+---
+
+Назад: [Классы и объекты](./05_classes-and-objects.md)