doc: add full EBDF grammar

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,2 @@
+# Стеки виртуальной машины
+

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,2 @@
+# Интерфейс компилятора
+

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,2 @@
+# Операторы
+

docs/ru/reference/types_system.md

@@ -0,0 +1,2 @@
+# Система типов
+

docs/ru/stdlib/builtins.md

@@ -0,0 +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