doc: add book,internal,reference,builtins sections

docs/grammar.ebnf

@@ -1,6 +0,0 @@
-program       := statement*
-statement     := expression
-expression    := call | string_literal
-call          := name "(" argument-list? ")"
-argument-list := string_literal ("," string_literal)*
-

docs/ru/book/00_introduction.md

@@ -0,0 +1,43 @@
+# Вступление
+
+Добро пожаловать в небольшую книжку по основам языка FZLang и спасибо, что решились попробовать этот язык программирования.
+
+Для начала, стоит рассказать, что это за язык и как будет идти обучение в этой "книжке".
+
+## Что такое FZLang
+
+FZLang - это язык программирования с собственным тулчейном, включающим в себя компилятор и виртуальную машину.
+Компилятор позволяет проверить и скомпилировать исходный код программы, чтобы сохранить в переносимый файл, а виртуальная машина - выполнить программу, написанную на FZLang.
+
+Изначально, этот проект задумывался как самоучитель по компиляторостроению.
+Мне (Samsonium) было интересно разобрать:
+
+- Почему между компилятором и интерпретатором есть значимая разница?
+- Как программа, под названием "компилятор" понимает, что я хочу сделать?
+- Как устроено исполнение скомпилированной программы? Да и как, вообще, происходит процесс "перевода" с человеческого на машинный?
+
+Я занимаюсь программированием уже более 10 лет, но за всё время так и не удосужился об этом разузнать!
+
+Поэтому, этот проект был рождён как поле для экспериментов, разрабатывая который я стану лучше понимать устройство того, на чём строится весь мир программистов.
+Однако, по ходу разработки у языка стала появлятся своя форма, а также философия.
+
+Сейчас, я бы описал философию языка так: "быть удобным, как инструмент, но всегда стараться оставаться предсказуемым".
+Полагаю, любое комьюнити желает своему языку того же, но мне это помогло сделать определённый выбор в ключевых точках развития.
+
+### Как в FZLang устроена работа с памятью
+
+Изначально вопрос появился после внедрения стеков виртуальной машины, и звучал он так: "сборщик мусора или что-то другое?".
+Изучить работу сборщика было, конечно, интересно.
+Однако мне, человеку, выбравшему Java как первый язык, была знакома его "тяжесть" и "скорость" работы.
+Конечно же, отдельное "спасибо" за это можно сказать его сборщику мусора.
+
+Поэтому, вместо GC я решил посмотреть в сторону RAII и, в итоге, получил хорошую формулу гуляния объекта в программе:
+если объект подан как аргумент, то происходит "заимствование" его во вложенное окружение, и если объект возвращается, то происходит перемещение объекта в родительское окружение.
+Такой подход позволяет не делать GC, а ещё, что самое важное, получить детерминированное время жизни объекта, а значит, детерминированную память (настолько, насколько это возможно).
+
+Короче говоря, FZLang обзавёлся scope-based RAII.
+
+---
+
+Далее: [Начало работы](./01_getting-started.md)
+

docs/ru/book/01_getting-started.md

@@ -0,0 +1,46 @@
+# Начало работы
+
+Для того, чтобы начать работу с FZLang, достаточно установить себе на компьютер два исполяемых файла:
+
+- `fzc` - компилятор
+- `fz` - виртуальная машина
+
+Для того, чтобы скомпилировать программу, достаточно выполнить программу `fzc`, указав в качестве аргументов пути к файлам с исходным кодом.
+Если программа успешно скомпилировалась, то её можно запустить через программу `fz`, также указав путь скомпилированному файлу.
+Без указания компилятору пути к выходному файлу, скомпилированная программа будет сохранена как `a.fzb`.
+
+## Настройки компилятора
+
+Чтобы посмотреть о доступных настройках компилятора, выполните `fzc --help` (или `fzc -h`).
+На данный момент, справка выглядит так: 
+
+```
+Usage: fzc [flags] <sources...>
+Available flags:
+        -h      --help          Print help
+        -v      --verbose       Display compilation info (tokens, AST, consts table, etc)
+        -V      --version       Print compiler version
+        -o      --out           Set compiled file name
+```
+
+Флаг `-h` (`--help`) просто выводит ту же справку. Флаги `-v` / `--verbose` делает подробный вывод компиляции:
+
+- Какие лексемы были прочитаны;
+- Какое синтаксическое дерево было собрано;
+- Какие значения были записаны в таблицу констант;
+- Какие опкоды были записаны в программу.
+
+Флаги `-V` / `--version` выводят версию компилятора. Флаги `-o`, `--out` позволяют задать путь выходного файла.
+
+## Настройки виртуальной машины
+
+У виртуальной машины есть всего два флага: `--help` (`-h`) и `-d`.
+
+- `--help` (или `-h`) выводит справку;
+- `-d <путь к файлу>` выводит список опкодов с нумерацией. С помощью этого флага вы можете посмотреть, как вашу программу будет читать ВМ.
+
+---
+
+Далее: [Основы и типы](./02_basics-and-types.md)
+
+Назад: [Вступление](./00_introduction.md)

docs/ru/book/02_basics-and-types.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)

docs/ru/book/03_control-flow.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)

docs/ru/book/04_functions-and-recursion.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)

docs/ru/book/05_classes-and-objects.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)

docs/ru/book/06_memory-model.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)

docs/ru/internals/object_layout.md

@@ -0,0 +1,21 @@
+# Размещение объектов
+
+Экземпляр класса во время исполнения представлен структурой объекта с массивом значений полей:
+
+```
+typedef struct
+{
+  fzl_value_t *values;
+  size_t values_count;
+} fzl_vm_object_t;
+```
+
+Поля получают последовательные индексы в порядке объявления.
+Таблица класса хранит имя поля, тип и `slot_index`.
+Поэтому `object.field` компилируется в `GET_FIELD` или `SET_FIELD` с числовым индексом.
+
+Выражение `new ClassName` проверяет наличие класса и генерирует `ALLOC_OBJECT N`, где `N` — число полей.
+Сравнение объектов проверяет указатели.
+При уничтожении окружения освобождаются принадлежащие ему объекты и массивы их значений.
+
+При возврате объекта из вложенного окружения `ESCAPE_OBJECT` переносит владение в родительское окружение.

docs/ru/internals/opcodes.md

@@ -0,0 +1,119 @@
+# Опкоды
+
+Программы, написанные на FZLang, исполняются с помощью виртуальной машины, входящей в тулчейн FZLang и компилирующейся в паре с компилятором.
+Компилятор FZC может выпускать следующие опкоды, которые понимает и исполняет ВМ:
+
+## Загрузка данных и работа со стеком
+
+Коды: `0xF00001`..`0xF00004`
+
+| Номер    | Название                | Назначение                      | Аргумент              |
+| -------- | ----------------------- | ------------------------------- | --------------------- |
+| 0xF00001 | FZL_OPCODE_LOADCONST    | Загрузить константу `N` на стек | `N` - номер константы |
+| 0xF00002 | FZL_OPCODE_CALL_BUILTIN | Вызвать встроенную функцию `N`  | `N` - номер функции   |
+| 0xF00003 | FZL_OPCODE_PUSHNUM      | Поместить на стек число `N`     | `N` - значение        |
+| 0xF00004 | FZL_OPCODE_PUSHBOOL     | Поместить на стек булеву `B`    | `B` - значение        |
+
+## Управление контекстом и окружением
+
+Коды: `0xF10001`..`0xF10005`
+
+| Номер    | Название               | Назначение                                                          |
+| -------- | ---------------------- | ------------------------------------------------------------------- |
+| 0xF10001 | FZL_OPCODE_MK_ENVTABLE | Создать новое окружение                                             |
+| 0xF10002 | FZL_OPCODE_RM_ENVTABLE | Уничтожить окружение                                                |
+| 0xF10003 | FZL_OPCODE_STORE       | Создать в окружении имя, лежащее на вершине стека                   |
+| 0xF10004 | FZL_OPCODE_LOOKUP_ENV  | Достать из стека имя, найти в окружении и положить на стек значение |
+| 0xF10005 | FZL_OPCODE_WRITE       | Достать со стека имя и значение, и записать в окружение             |
+
+## Управление потоком
+
+Коды: `0xF20001`..`0xF20002`
+
+| Номер    | Название       | Назначение                                                        | Аргумент                 |
+| -------- | -------------- | ----------------------------------------------------------------- | ------------------------ |
+| 0xF20001 | FZL_OPCODE_JMP | Прыгнуть на адрес `IP`                                            | `IP` - адрес-цель прыжка |
+| 0xF20002 | FZL_OPCODE_JZ  | Прыгнуть на адрес `IP`, если значение на вершине стека равно нулю | `IP` - адрес-цель прыжка |
+
+## Вызов функций
+
+Коды: `0xF30001`..`0xF30002`
+
+| Номер    | Название        | Назначение                                                        |
+| -------- | --------------- | ----------------------------------------------------------------- |
+| 0xF30001 | FZL_OPCODE_CALL | Положить на стек вызовов текущий адрес и перейти к началу функции |
+| 0xF30002 | FZL_OPCODE_RET  | Снять со стека вызовов последний адрес и перейти к нему           |
+
+## Работа с объектами
+
+Коды: `0xFA0001`..`0xFA0005`
+
+| Номер    | Название                 | Назначение                                                                       | Аргумент              |
+| -------- | ------------------------ | -------------------------------------------------------------------------------- | --------------------- |
+| 0xFA0001 | FZL_OPCODE_ALLOC_OBJECT  | Аллоцировать объект под `N` значений и поместить его на стек                     | `N` - кол-во значений |
+| 0xFA0002 | FZL_OPCODE_GET_FIELD     | Снять со стека ссылку на объект и получить значение поля `N`                     | `N` - номер поля      |
+| 0xFA0003 | FZL_OPCODE_SET_FIELD     | Снять со стека ссылку на объект и значение, а затем записать значение в поле `N` | `N` - номер поля      |
+| 0xFA0004 | FZL_OPCODE_ESCAPE_OBJECT | Перенести объект (в т.ч. дочерние ему) в родительское окружение                  | отсутствует           |
+
+## Арифметические операции
+
+Коды: `0xA00001`..`0xA00007`
+
+| Номер    | Название       | Назначение                                                                              |
+| -------- | -------------- | --------------------------------------------------------------------------------------- |
+| 0xA00001 | FZL_OPCODE_ADD | Снять два числа со стека и сложить их, положив результат на стек                        |
+| 0xA00002 | FZL_OPCODE_SUB | Снять два числа со стека и вычесть первое от второго, положив результат на стек         |
+| 0xA00003 | FZL_OPCODE_MUL | Снять два числа со стека и переменожить их, положив результат на стек                   |
+| 0xA00004 | FZL_OPCODE_DIV | Снять два числа со стека и поделить первое на второе, положив результат на стек         |
+| 0xA00005 | FZL_OPCODE_POW | Снять два числа со стека и возвести второе в степерь первого, положив результат на стек |
+| 0xA00006 | FZL_OPCODE_MOD | Снять два числа со стека и положить на стек остаток от деления второго на первое        |
+| 0xA00007 | FZL_OPCODE_NEG | Снять число со стека, инвертировать, и положить обратно на стек                         |
+
+## Сравнение чисел
+
+Коды: `0xB00001`..`0xB00006`
+
+| Номер    | Название            | Назначение                                                                                                   |
+| -------- | ------------------- | ------------------------------------------------------------------------------------------------------------ |
+| 0xB00001 | FZL_OPCODE_CMP_EQ   | Снять два числа со стека, проверить на равенство и положить на стек результат                                |
+| 0xB00002 | FZL_OPCODE_CMP_NEQ  | Снять два числа со стека, проверить на неравенство и сохранить результат на стеке                            |
+| 0xB00003 | FZL_OPCODE_CMP_LT   | Снять два числа со стека, проверить, что второе меньше первого, и затем положить результат на стек           |
+| 0xB00004 | FZL_OPCODE_CMP_LTEQ | Снять два числа со стека, проверить, что второе меньше или равно первому, и затем положить результат на стек |
+| 0xB00005 | FZL_OPCODE_CMP_GT   | Снять два числа со стека, проверить, что второе больше первого, и затем положить результат на стек           |
+| 0xB00006 | FZL_OPCODE_CMP_GTEQ | Снять два числа со стека, проверить, что второе больше или равно первому, и затем положить результат на стек |
+
+## Сравнение строк
+
+Коды: `0xB10001`..`0xB10002`
+
+| Номер    | Название               | Назначение                                                                     |
+| -------- | ---------------------- | ------------------------------------------------------------------------------ |
+| 0xB10001 | FZL_OPCODE_CMP_EQ_STR  | Снять две строки со стека, сравнить на равенство, положить результат на стек   |
+| 0xB10002 | FZL_OPCODE_CMP_NEQ_STR | Снять две строки со стека, сравнить на неравенство, положить результат на стек |
+
+## Сравнение объектов
+
+Коды: `0xB20001`..`0xB20002`
+
+| Номер    | Название               | Назначение                                                                      |
+| -------- | ---------------------- | ------------------------------------------------------------------------------- |
+| 0xB20001 | FZL_OPCODE_CMP_EQ_OBJ  | Снять два объекта со стека, сравнить на равенство, положить результат на стек   |
+| 0xB20002 | FZL_OPCODE_CMP_NEQ_OBJ | Снять два объекта со стека, сравнить на неравенство, положить результат на стек |
+
+## Бинарные логические операции
+
+Коды: `0xC00001`..`0xC00002`
+
+| Номер    | Название       | Назначение                                                               |
+| -------- | -------------- | ------------------------------------------------------------------------ |
+| 0xC00001 | FZL_OPCODE_AND | Взять два значения со стека и положить на стек результат логического И   |
+| 0xC00002 | FZL_OPCODE_OR  | Взять два значения со стека и положить на стек результат логического ИЛИ |
+
+## Унарные логические операции
+
+Коды: `0xD00001`
+
+| Номер    | Название       | Назначение                                                         |
+| -------- | -------------- | ------------------------------------------------------------------ |
+| 0xD00001 | FZL_OPCODE_NOT | Взять значение со стека и положить инвертированный булев результат |
+

docs/ru/internals/stacks.md

@@ -0,0 +1,24 @@
+# Стеки виртуальной машины
+
+ВМ использует три фиксированных стека по 256 элементов.
+
+## Стек данных
+
+`dstack` хранит значения `fzl_value_t`: числа, строки, булевы значения, ссылки на объекты и null.
+`PUSHNUM`, `PUSHBOOL` и `LOADCONST` помещают значения на стек.
+Арифметические и логические операции снимают операнды и кладут результат обратно.
+
+## Стек вызовов
+
+`cstack` хранит адреса возврата.
+`CALL` сохраняет текущий адрес и переходит к функции,
+`RET` снимает последний адрес.
+Рекурсивные вызовы используют отдельные записи.
+
+## Стек окружений
+
+`estack` хранит таблицы имён и владельцев объектов.
+`MK_ENVTABLE` создаёт окружение, `RM_ENVTABLE` уничтожает его, `STORE` добавляет имя, `LOOKUP_ENV` ищет значение, `WRITE` изменяет переменную.
+`ESCAPE_OBJECT` переносит возвращаемый объект перед закрытием окружения.
+
+Запуск `fz -d program.fzb` печатает декодированную последовательность опкодов и аргументов.

docs/ru/philosopy.md

@@ -0,0 +1,31 @@
+# Философия языка
+
+Язык FZLang преследует две цели при разработке: "быть удобным, как инструмент, но всегда оставаться предсказуемым".
+
+Вот, какими путями язык пытается достичь этой философии:
+
+## В отношении к памяти и ресурсам
+
+В средах с GC программист точно не знает, в какой момент сборщик мусора решит произвести очистку:
+объект может висеть секундами после завершения метода.
+А в момент очистки рантайм может устроить микропаузу, что критично для аудио, игр, сети или встроенных систем.
+
+В модели scope-based RAII, которая используется в том числе в FZLang, память детерминирована.
+Любой объект имеет область, которая им владеет, а как только область уничтожается - объект уничтожается вместе с ней.
+Время отклика таком подходе равное и предсказуемое.
+
+Ещё один плюс, который предоставляет модель scope-based RAII - это работа с ресурсами (сокеты, файлы).
+Проблема освобождения ресурсов решается чистой семантикой области видимости: умирает скоуп - очищается всё, что к нему привязано.
+
+И последним аргументом в сторону scope-based RAII стало отстутствие оверхеда на рантайм.
+Полноценному GC для работы нужны карты памяти, фоновые потоки, барьеры чтения и записи.
+В FZLang виртуальная машина весит очень мало, а вся память освобождается по ходу чтения инструкций.
+
+## В отношении синтаксиса
+
+Язык FZLang намеренно не упрощается некоторые детали синтаксиса.
+Например, при обращении к экземпляру класса в его методах, использование `this` является обязательным, как и указание типов при декларациях, - это строгая часть.
+Однако, объявление функции без возвращаемого типа позволяет опускать тип, так как писать на месте типа постоянно `void` было бы избыточно.
+
+Таким образом, FZLang старается балансировать между синтаксисом, позволяющим оставаться языку детерминированным и упрощениями, которые действительно уместны.
+

docs/ru/reference/compiler_cli.md

@@ -0,0 +1,19 @@
+# Интерфейс компилятора
+
+Компилятор называется `fzc`.
+Он принимает исходные файлы `.fzs` и создаёт бинарный файл `.fzb`.
+
+```
+fzc [flags] <sources...>
+```
+
+| Флаг          | Назначение                                     |
+| ------------- | ---------------------------------------------- |
+| -h, --help    | Показать справку                               |
+| -v, --verbose | Вывести токены, AST, таблицу констант и опкоды |
+| -V, --version | Показать версию                                |
+| -o, --out     | Задать имя выходного файла                     |
+
+Если `-o` не задан, результат записывается в `a.fzb`. Пример: `fzc -v -o hello.fzb exl/hw.fzs`.
+
+VM запускается командой `fz [flags] <file path>`. Флаг `-d` или `--debug` печатает опкоды, не выполняя программу.

docs/ru/reference/grammar_ebnf.md

@@ -0,0 +1,33 @@
+# Грамматика (EBNF)
+
+Упрощённая грамматика текущего парсера:
+
+```
+program        = { statement } ;
+statement      = class | function | if | block | return | expression ";" ;
+block          = "{" { statement } "}" ;
+class          = "class" name "{" { declaration | function } "}" ;
+function       = "fn" name "(" [ parameters ] ")" [ type-name ] statement ;
+parameters     = parameter { "," parameter } ;
+parameter      = type-name name ;
+return         = "return" [ expression ] ";" ;
+if             = "if" "(" expression ")" statement [ "else" statement ] ;
+expression     = assignment ;
+assignment     = new-expression [ "=" assignment ] ;
+new-expression = logical-or | "new" name ;
+logical-or     = logical-and { "||" logical-and } ;
+logical-and    = comparison { "&&" comparison } ;
+comparison     = term { compare-op term } ;
+term           = factor { ( "+" | "-" ) factor } ;
+factor         = power { ( "*" | "/" | "%" ) power } ;
+power          = unary [ "^" unary ] ;
+unary          = ( "+" | "-" | "!" ) unary | postfix ;
+postfix        = primary { call | member } ;
+call           = "(" [ expression { "," expression } ] ")" ;
+member         = "." name ;
+primary        = literal | declaration | name | "(" expression ")" ;
+declaration    = type-name name ;
+type-name      = builtin-type | name ;
+```
+
+`literal` включает строковый, числовой, булев и `null` литералы. Комментарии `// ...` и пробельные символы между токенами игнорируются.

docs/ru/reference/operators.md

@@ -0,0 +1,17 @@
+# Операторы
+
+| Оператор             | Назначение                             |
+| -------------------- | -------------------------------------- |
+| +, -                 | Сложение/вычитание, унарные плюс/минус |
+| *, /, %              | Умножение, деление, остаток            |
+| ^                    | Возведение в степень                   |
+| ==, !=, <, <=, >, >= | Сравнение                              |
+| !                    | Логическое отрицание                   |
+| &&, ||               | Логические И и ИЛИ                     |
+| =                    | Присваивание                           |
+| .                    | Доступ к полю и методу                 |
+
+Для строк и объектов доступны только `==` и `!=`.
+Ключевое слово `new` создаёт экземпляр класса: `new Point`.
+
+Приоритет от большего к меньшему: унарные операции; ^; *, /, %; +, -; сравнения; &&; ||; =. Скобки имеют высший приоритет.

docs/ru/reference/types_system.md

@@ -0,0 +1,22 @@
+# Система типов
+
+| Типы              | Значение                                 |
+| ----------------- | ---------------------------------------- |
+| int, uint         | Целое машинного размера                  |
+| i8, i16, i32, i64 | Знаковые целые фиксированного размера    |
+| u8, u16, u32, u64 | Беззнаковые целые фиксированного размера |
+| str               | Строка                                   |
+| char              | Символ                                   |
+| bool              | Булево значение                          |
+| ClassName         | Экземпляр пользовательского класса       |
+
+Также существует `null`, применимое к объектным значениям.
+Тип указывается при объявлении переменной, поля и аргумента функции.
+
+Объект совместим с объектом того же класса или с `null`.
+Объекты разных классов несовместимы.
+Строки поддерживают `==` и `!=`, объекты сравниваются по ссылке.
+Поля класса имеют объявленные типы и последовательные слоты.
+
+Для функции тип результата указывается после списка параметров.
+Для функции без результата его можно опустить.

docs/ru/stdlib/builtins.md

@@ -0,0 +1,30 @@
+# Встроенные функции
+
+Встроенные функции распознаются компилятором по имени и исполняются ВМ напрямую.
+
+## printline
+
+Выводит аргумент в стандартный вывод и добавляет перевод строки:
+
+```
+printline("hello, world");
+printline(42);
+```
+
+Вызов без аргументов считается ошибкой компиляции.
+Функция используется для строк, чисел, булевых значений и объектов.
+
+## exit
+
+Завершает программу с указанным кодом возврата:
+
+```
+if (failed)
+{
+  printline("Test failed");
+  exit(1);
+}
+```
+
+Код передаётся одним аргументом.
+Ненулевой код обычно означает ошибку.

src/compiler/utils/fzl_options.c

@@ -27,6 +27,7 @@ fzl_options_t *fzl_mkoptions(int argc, char **argv)
   }
 
   memset(opts, 0, sizeof(fzl_options_t));
+  opts->should_continue = true;
 
   if (argc < 2)
   {
@@ -81,12 +82,14 @@ fzl_options_t *fzl_mkoptions(int argc, char **argv)
   size_t fcount     = 0;
   char **files      = malloc(fremainder * sizeof(char *));
 
+  if (opts->should_continue)
+  {
     for (; i < argc; i++)
     {
       if (argv[i][0] == '-')
       {
-      printf(
+        printf("%sWarning%s: unhandled flag '%s' (should be defined before "
-          "%sWarning%s: unhandled flag '%s' (should be defined before sources "
+               "sources "
                "list)\n",
                FZL_CWARNING, FZL_CRST, argv[i]);
         continue;
@@ -100,6 +103,7 @@ fzl_options_t *fzl_mkoptions(int argc, char **argv)
 
       files[fcount++] = argv[i];
     }
+  }
 
   opts->files       = files;
   opts->files_count = fcount;
@@ -115,7 +119,6 @@ fzl_options_t *fzl_mkoptions(int argc, char **argv)
     return NULL;
   }
 
-  opts->should_continue = true;
   return opts;
 }
 

src/vm/main.c

@@ -17,6 +17,7 @@ void print_hint()
   printf("Usage: fz [flags] <file path>\n");
   printf("Flags:\n");
   printf("\t-h\t--help\tprint usage information\n");
+  printf("\t-d\t--debug\tdisplay program opcodes\n");
 }
 
 // Parse passed arguments and build args setup structure