Merge branch 'master' into docs

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/internals/object_layout.md

@@ -0,0 +1,2 @@
+# Размещение объектов
+

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,102 @@
+# Стеки виртуальной машины
+
+Во время работы, виртуальная машина FZLang полагается на три стека: данных, окружений и вызовов.
+Каждый стек инициализируется как массив из 256 значений, а затем зануляется.
+Основное свойство, присущее всем трём стекам - последнее значение является верхом стека и сниматься в первую очередь должно оно, декрементируя указатель на вершину стека.
+
+## Стек данных
+
+Стек данных представляет из себя массив из 256 элементов типа `fzl_value_t`.
+Структура `fzl_value_t` - это контейнер для хранения значений, используемых во время работы программы.
+
+```c
+typedef struct
+{
+  fzl_type_t type;
+
+  union
+  {
+    void *obj;
+
+    struct
+    {
+      const char *value;
+      size_t length;
+    } s;
+
+    char c;
+    bool b;
+
+    int8_t i8;
+    uint8_t u8;
+
+    int16_t i16;
+    uint16_t u16;
+
+    int32_t i32;
+    uint32_t u32;
+
+    int64_t i64;
+    uint64_t u64;
+
+    intptr_t i;
+    uintptr_t u;
+  } as;
+} fzl_value_t;
+```
+
+Стек используется во время работы программы виртуальной машиной, чтобы писать и читать промежуточные вычисления.
+К концу работы программы, стек должен быть пуст.
+
+## Стек окружений
+
+Чтобы определять лексическое окружение, в котором на данный момент производятся вычисления и выполняются команды, используется стек окружений.
+Стек окружений - это массив из 256 элементов типа `fzl_vm_env_t`.
+
+```c
+typedef struct
+{
+  size_t size;
+  size_t remainder;
+
+  fzl_vm_env_entry_t *table;
+
+  fzl_vm_object_t **owned_objects;
+  size_t owned_objects_remainder;
+  size_t owned_objects_count;
+} fzl_vm_env_t;
+```
+
+Каждый элемент стека хранит таблицу локальных имён `fzl_vm_env_entry_t`, а также объекты, которые принадлежат текущему окружению.
+Локальное имя - это контейнер, оборачивающий `fzl_value_t` и дающий ему имя:
+
+```c
+typedef struct
+{
+  char *name;
+  fzl_value_t value;
+} fzl_vm_env_entry_t;
+```
+
+Объект же представляет из себя массив полей, хранимых в этом объекте.
+Количество элементов определется при аллокации объекта (опкод `FZL_OPCODE_ALLOC_OBJECT N`, подробнее - в [описании опкодов](./opcodes.md)).
+
+```c
+typedef struct
+{
+  fzl_value_t *values;
+  size_t values_count;
+} fzl_vm_object_t;
+```
+
+Создание окружения или выход из него происходит при опкодах `FZL_OPCODE_MK_ENVTABLE` и `FZL_OPCODE_RM_ENVTABLE` соответственно.
+При этом, если компилятор видит возвращаемое из функции значение типа `FZL_TYPE_OBJECT`, то перед опкодами `FZL_OPCODE_RET` и `FZL_OPCODE_RM_ENVTABLE` он вставляет `FZL_OPCODE_ESCAPE_OBJECT`,
+которое позволяет переместить владение объектом в родительское окружение.
+
+## Стек возврата
+
+Стек возврата хранит адреса инструкций при входе в функцию (через опкод `FZL_OPCODE_CALL`).
+Опкод `FZL_OPCODE_RET` снимает адрес со стека вызовов и прыгает на снятый адрес.
+
+Сам по себе стек представляет из себя 256 элементов типа `size_t`.
+

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/errors_print.md

@@ -0,0 +1,120 @@
+# Вывод ошибок
+
+Если во время работы программы происходит ошибка рантайма, то ВМ выводит своё состояние на момент остановки.
+Среди выводимой информации есть:
+
+1. Указатель на адрес инструкции;
+2. Стек данных;
+3. Стек окружений;
+4. Стек вызовов.
+
+## Указатель на адрес инструкции (IP)
+
+Он может быть полезен для отладки, в паре с выводом опкодов программы.
+Если подать в ВМ флаг `--debug` (`-d`) вместе с путём к скомпилированной программой, то ВМ выведет список опкодов программы без её запуска.
+
+Выглядит вывод программы примерно так:
+
+```
+0000: MK_ENVTABLE
+0001: JMP IP: 53
+0003: MK_ENVTABLE
+0004: LOADCONST #0 ('a')
+0006: STORE
+0007: LOADCONST #0 ('a')
+0009: WRITE
+0010: MK_ENVTABLE
+0011: LOADCONST #0 ('a')
+0013: LOOKUP_ENV
+0014: GET_FIELD #0
+...
+```
+
+Порядковый номер позволяет быстро найти инструкцию, на которой произошло исключение.
+Полный список опкодов и их описание можно найти в документе [списка опкодов](../internals/opcodes.md).
+
+## Стек данных
+
+Стек данных выводится как список значений в стиле `[T] V`, где `T` - номер типа, `V` - значение.
+Если значение является строкой или объектом, то в начале дописывается `str: V` и `ref: V` соответственно.
+
+Вот, как выглядит пример вывода стека:
+
+```
+> Data stack:
+        > [2] str: 'this'
+```
+
+Важно учесть, что значения выводятся сверху вниз. То есть, первыми будут выведены самые свежие значения.
+
+## Стек окружения
+
+Стек окружения выводится как два списка: объекты во владении и локальные для окружения имена.
+
+Пример окружения:
+
+```
+> Environments:
+        > [1] 0x55a9d8196a20:
+                > Owned objects (0/2):
+                > Local entries (3/4):
+                        > [14] b = 4
+                        > [1] a = ref 0x55a9d81969e0
+                        > [0] this = 0
+        > [0] 0x55a9d8196930:
+                > Owned objects (1/2):
+                        > ref: 0x55a9d81969e0 (entries: 1)
+                > Local entries (1/2):
+                        > [1] sum = ref 0x55a9d81969e0
+```
+
+`> [N] A` - это сама таблица окружения.
+`N` - это уровень таблицы, который тем выше, чем глубже само окружение.
+`A` - это адрес таблицы в памяти.
+
+Внутри идёт первый список - "Owned objects", с указанием количества элементов и аллоцированным размером массива `(<кол-во>/<размер>)`.
+Перечисление объектов идёт форматом `ref: A (entries: N)`, где `A` - адрес объекта в памяти, `N` - количество хранимых полей.
+
+Далее идёт список локальных имён - "Local entries", с таким же указанием количества элементов к аллоцированному размеру.
+Формат элемента - `[T] N = V`, где `T` - номер типа, `N` - имя элемента, а `V` - его значение.
+
+## Стек вызовов
+
+На стеке вызовов лежат точки возврата, которые попадают на стек при инструкции `CALL` и съедаются инструкцией `RET`.
+
+```
+> Call stack:
+        > [0] 53
+```
+
+Формат записи простой: `[L] IP`, где `L` - уровень вложенности (больше = глубже), а `IP` - указатель на номер инструкции, на которую нужно прыгнуть после возврата.
+
+## Полный вывод
+
+Итого, полный вывод ошибки выглядит следующим образом:
+
+```
+===== ERROR =====
+> Caused on IP: 21
+
+> Data stack:
+        > [2] str: 'this'
+
+> Environments:
+        > [1] 0x55a9d8196a20:
+                > Owned objects (0/2):
+                > Local entries (3/4):
+                        > [14] b = 4
+                        > [1] a = ref 0x55a9d81969e0
+                        > [0] this = 0
+        > [0] 0x55a9d8196930:
+                > Owned objects (1/2):
+                        > ref: 0x55a9d81969e0 (entries: 1)
+                > Local entries (1/2):
+                        > [1] sum = ref 0x55a9d81969e0
+
+> Call stack:
+        > [0] 53
+Error: runtime error - expected 2 values in data stack
+```
+

docs/ru/reference/grammar.ebnf

@@ -0,0 +1,61 @@
+/* FZL (FromZero Language) syntax */
+/* Version 1 */
+/* Authors: */
+/* - Samsonium (https://git.samsonium.dev/Samsonium) */
+
+<program> ::= <_> <statement>+
+
+<statement> ::= <class_stmt>
+              | <fn_stmt>
+              | <if_stmt>
+              | <block_stmt>
+              | <ret_stmt>
+              | <expr_stmt>
+
+<_>  ::= " "*
+<ws> ::= " "+
+
+<expr_stmt>  ::= <expr> <_> ";" <_>
+<block_stmt> ::= "{" <_> <statement>* "}" <_>
+<ret_stmt>   ::= "return" (<ws> <expr>)? <_> ";" <_>
+
+<class_stmt> ::= "class" <ws> <name> <_> "{" <_> (<declaration> | <fn_stmt>)* "}" <_>
+<fn_stmt>    ::= "fn" <ws> <name> <_> "(" <_> (<param> (<_> "," <_> <param>)*)? ")" <_> <block_stmt>
+<param>      ::= <type> <ws> <name>
+
+<if_stmt> ::= "if" <_> "(" <_> <expr> <_> ")" <_> <statement> (<_> "else" <ws> <statement>)?
+
+/* Assign (lowest epxression priority, right-associative) */
+<expr>        ::= <assign_expr>
+<assign_expr> ::= <new_expr> (<_> "=" <_> <assign_expr>)?
+<new_expr>    ::= ("new" <ws> <name>) | <or_expr>
+<or_expr>     ::= <and_expr> (<_> "||" <_> <and_expr>)*
+<and_expr>    ::= <cond_expr> (<_> "&&" <_> <cond_expr>)*
+<cond_expr>   ::= <term_expr> (<_> <cond_op> <_> <term_expr>)*
+<cond_op>     ::= "==" | "!=" | "<=" | ">=" | "<" | ">"
+
+<term_expr>   ::= <factor_expr> (<_> ("+" | "-") <_> <factor_expr>)*
+<factor_expr> ::= <power_expr> (<_> ("*" | "/" | "%") <_> <power_expr>)*
+<power_expr>  ::= <unary_expr> (<_> "^" <_> <power_expr>)?
+<unary_expr>  ::= (("!" | "-" | "+") <_>)* <postfix_expr>
+
+/* Postfix: chain of calls and dots */
+<postfix_expr>  ::= <primary_expr> (<call_suffix> | <member_suffix>)*
+<call_suffix>   ::= <_> "(" <_> (<expr> (<_> "," <_> <expr>)*)? <_> ")"
+<member_suffix> ::= <_> "." <_> <name>
+
+<primary_expr> ::= <literal>
+                 | <declaration>
+                 | "(" <_> <expr> <_> ")"
+                 | <name>
+
+<declaration> ::= <type> <ws> <name>
+
+<type> ::= "int" | "uint" | "bool" | "char" | "str"
+         | "i8" | "i16" | "i32" | "i64"
+         | "u8" | "u16" | "u32" | "u64"
+
+<literal>        ::= <number> | <string_literal> | "true" | "false" | "null"
+<name>           ::= ([A-z] | "_") | ([A-z] | [0-9] | "_")*
+<string_literal> ::= ('"' [^"]* '"') | ("'" [^']* "'") 
+

docs/ru/reference/grammar_ebnf.md

@@ -0,0 +1,2 @@
+# Грамматика (EBNF)
+

docs/ru/reference/operators.md

@@ -0,0 +1,40 @@
+# Операторы
+
+FZLang поддерживает арифметические, логические и унарные операции.
+Во время работы бинарные операции достают со стека два значения, и обратно кладут результат на стек.
+Унарные операции достают одно значение со стека, а затем кладут результат обратно на стек.
+
+## Арифметические операции
+
+| Операция | Допустимые типы | Описание |
+| -------- | --------------- | -------- |
+| `N + N` | *все числовые* | Сложение двух операндов |
+| `N - N` | *все числовые* | Вычитание правого операнда из левого |
+| `N * N` | *все числовые* | Переменожение двух операндов |
+| `N / N` | *все числовые* | Деление левого операнда на правый |
+| `N % N` | *все числовые* | Получение остатка от деления левого операнда на правый |
+| `N ^ N` | *все числовые* | Возведение левого операнда в степень правого |
+| `-N` | *все числовые* | Инверсия операнда |
+
+## Операции сравнения
+
+| Операция | Допустимые типы | Описание |
+| -------- | --------------- | -------- |
+| `N == N` | *все числовые*, булевы, объекты, строки | Сравнить равенство операндов |
+| `N != N` | *все числовые*, булевы, объекты, строки | Сравнить неравенство операндов |
+| `N > N` | *все числовые* | Проверить, что левый операнд больше правого |
+| `N >= N` | *все числовые* | Проверить, что левый операнд больше или равен правому |
+| `N < N` | *все числовые* | Проверить, что левый операнд меньше правого |
+| `N <= N` | *все числовые* | Проверить, что левый операнд меньше или равен правому |
+| `!N` | булевы | Инвертировать операнд |
+
+> Важно:
+> В случае сравнения объектов (`==`, `!=`), сравниваются адреса, а не значения!
+
+## Логические операции
+
+| Операция | Допустимые типы | Описание |
+| -------- | --------------- | -------- |
+| `N && N` | булевы | Логическое **И** двух операндов |
+| `N || N` | булевы | Логическое **ИЛИ** двух операндов |
+

docs/ru/reference/types_system.md

@@ -0,0 +1,54 @@
+# Система типов
+
+FZLang имеет две основы для типов: примитивы и объекты.
+
+Примитивами являются строки, числовые типы, булевы и скрытый тип - "объект".
+Объектами на данный момент являются экземпляры классов, а также литерал `null`.
+
+## Таблица типов
+
+| Внутреннее имя  | Синтаксическое имя | Описание |
+| --------------- | ------------------ | -------- |
+| FZL_TYPE_NULL   | *отстутсвует* | *на данный момент не используется* |
+| FZL_TYPE_OBJECT | *отстутсвует* | экземпляр класса или литерал `null` |
+| FZL_TYPE_STRING | `str` | строка |
+| FZL_TYPE_CHAR   | `char` | *на данный момент не используется* |
+| FZL_TYPE_BOOL   | `bool` | булева |
+| FZL_TYPE_INT8 | `i8` | 8-битное знаковое число |
+| FZL_TYPE_UINT8 | `u8` | 8-битное беззнаковое число |
+| FZL_TYPE_INT16 | `i16` | 16-битное знаковое число |
+| FZL_TYPE_UINT16 | `u16` | 16-битное беззнаковое число |
+| FZL_TYPE_INT32 | `i32` | 32-битное знаковое число |
+| FZL_TYPE_UINT32 | `u32` | 32-битное беззнаковое число |
+| FZL_TYPE_INT64 | `i64` | 64-битное знаковое число |
+| FZL_TYPE_UINT64 | `u64` | 64-битное беззнаковое число |
+| FZL_TYPE_INT | `int` | знаковое число размером с машинное слово |
+| FZL_TYPE_UINT | `uint` | беззнаковое число размером с машинное слово |
+
+
+## Совместимость
+
+При проверке совместимости типов работают следующие правила:
+
+1. Если оба типа - объекты (`FZL_TYPE_OBJECT`), то:
+  1. Если один из типов имеет имя класса `<nullptr>`, проверка **пройдена**;
+  2. Если оба типа имеют одинаковое имя класса, проверка **пройдена**;
+  3. В ином случае проверка **не пройдена**.
+2. Если типы равны, проверка **пройдена**;
+3. Если оба типа - числовые (`u8`..`uint`, `i8`..`int`), проверка **пройдена**;
+4. Если ни одно правило из вышеперечисленных не сработало, то проверка **не пройдена**.
+
+**пройдена** = типы совместимы, **не пройдена** - не совместимы.
+
+## Работа в рантайме
+
+Для примитивов (т.е., не `FZL_TYPE_OBJECT`), значения используются прямо.
+Это значит, что они все операции, работающие со значениями используют для работы то значение, что лежит в контейнере на стеке.
+
+Объектные типы хранятся на стеке как **ссылки на объект**.
+Для них валидные такие операции, как:
+
+- `FZL_OPCODE_ESCAPE_OBJECT` (эвакуация объекта в родительское окружение)
+- `FZL_OPCODE_GET_FIELD N` (чтение поля с индексом `N` из объекта)
+- `FZL_OPCODE_SET_FIELD N` (запись значения в поле объекта с индексом `N`)
+

docs/ru/stdlib/builtins.md

@@ -0,0 +1,23 @@
+# Встроенные функции
+
+В языке FZLang предусмотрены встроеные функции, доступные для использования в любой программе.
+
+## Выход `exit`
+
+```
+fn exit(uint code)
+```
+
+Функция принимает аргументом беззнаковое число и выходит из программы с указанным кодом.
+
+## Вывод в stdout `printline`
+
+```
+fn printline(value)
+```
+
+Принимает аргументом любое значение и выводит в стандартный вывод указанное значение.
+Для примитивы выводятся чисто, на основе типа.
+Объекты выводятся как `obj<...>`, где `...` - перечисление значений полей.
+Поля выводятся по типу и значению в формате: `T<V>`, где `T` - название типа, `V` - текущее значение.
+

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