Add documentation and update README.md

Author: FlacSy

README.md

@@ -2,7 +2,7 @@
 
 ![Giraffe](images/Giraffe.png)
 
-**Giraffe-Language** — это язык программирования, ориентированный на создание скриптов для автоматизации процессов и разработки удобных интерфейсов для сложных проектов. 
+**Giraffe-Language** — это интерпритуруемый язык программирования, ориентированный на создание скриптов для автоматизации процессов и разработки удобных интерфейсов для сложных проектов. 
 
 
 ## Текущий статус
@@ -13,6 +13,8 @@
 
 - Разработка интерпретатора 
 
+- Разработка хранилищя состояния
+
 - Оптимизация производительности и добавление новых функций
 
 

documentation/ast.md

@@ -0,0 +1,154 @@
+# Документация для абстрактного синтаксического дерева (AST)
+
+Абстрактное синтаксическое дерево (AST) — это иерархическое представление структуры исходного кода. Оно используется для представления синтаксической структуры кода в более удобном для обработки виде. Эта документация описывает основные компоненты AST, их связи и поля.
+
+## Обзор
+
+AST состоит из трех основных компонентов:
+
+- **AstNode**: Представляет корневой узел AST.
+- **Statement**: Представляет различные типы операторов, которые выполняются в программе.
+- **Expression**: Представляет выражения, используемые в операторах и вычислениях.
+
+### AstNode
+
+Перечисление `AstNode` является корневым узлом AST и содержит структуру программы с операторами.
+
+#### Варианты:
+
+- `Program { statements: Vec<Statement> }`:
+  - Представляет всю программу, состоящую из списка операторов.
+- `Statement(Statement)`:
+  - Содержит один оператор, который является частью программы.
+- `Expression(Expression)`:
+  - Содержит выражение, которое может быть частью оператора или отдельным элементом.
+
+#### Методы:
+- `build_program(statements: Vec<Statement>) -> AstNode`: 
+  - Создает узел `Program` с набором операторов.
+
+### Statement
+
+Перечисление `Statement` представляет различные типы операторов в программе. Операторы выполняются и обычно выполняют действие в программе.
+
+#### Варианты:
+
+- `FunctionDeclaration(FunctionDeclaration)`:
+  - Представляет объявление функции в программе.
+- `VariableDeclaration(VariableDeclaration)`:
+  - Представляет объявление переменной.
+- `IfStatement(IfStatement)`:
+  - Представляет оператор if с условием, телом и опциональными ветвями elif и else.
+- `WhileStatement(WhileStatement)`:
+  - Представляет оператор while с условием и телом.
+- `PrintStatement(PrintStatement)`:
+  - Представляет оператор вывода (print).
+- `ReturnStatement(ReturnStatement)`:
+  - Представляет оператор возврата.
+- `Assignment(Assignment)`:
+  - Представляет оператор присваивания, который присваивает значение переменной.
+- `ExpressionStatement(Expression)`:
+  - Представляет оператор, который является выражением (без побочных эффектов).
+- `Block(Vec<Statement>)`:
+  - Представляет блок операторов.
+- `ForInStatement(String, Expression, Vec<Statement>)`:
+  - Представляет цикл `for`, который перебирает коллекцию.
+
+#### Методы:
+- Доступны различные методы для создания конкретных типов операторов, таких как `function_declaration()`, `variable_declaration()`, `if_statement()` и др.
+
+### Expression
+
+Перечисление `Expression` представляет выражения, которые вычисляются для получения значения. Оно используется как часть операторов или в расчетах.
+
+#### Варианты:
+
+- `Literal(Literal)`:
+  - Представляет литеральное значение, такое как числа, строки, булевы значения и т. д.
+- `Variable(String)`:
+  - Представляет переменную (то есть ссылку на переменную по имени).
+- `BinaryOperation(Box<Expression>, Operator, Box<Expression>)`:
+  - Представляет бинарную операцию с левым операндом, оператором и правым операндом.
+- `FunctionCall(String, Vec<Expression>)`:
+  - Представляет вызов функции с именем функции и списком аргументов.
+- `List(Vec<Expression>)`:
+  - Представляет список выражений.
+- `Dictionary(Vec<(Expression, Expression)>)`:
+  - Представляет словарь с парами ключ-значение, где как ключи, так и значения являются выражениями.
+- `Tuple(Vec<Expression>)`:
+  - Представляет кортеж из выражений.
+- `Null`:
+  - Представляет значение null.
+
+#### Методы:
+- Доступны различные методы для создания выражений, такие как `literal()`, `variable()`, `binary_operation()`, `function_call()` и др.
+
+### Literal
+
+Перечисление `Literal` представляет литеральные значения, которые могут быть использованы напрямую в исходном коде.
+
+#### Варианты:
+
+- `Integer(i64)`:
+  - Представляет литеральное целое число.
+- `Float(f64)`:
+  - Представляет литеральное число с плавающей запятой.
+- `Boolean(bool)`:
+  - Представляет литеральное булево значение (`true` или `false`).
+- `String(String)`:
+  - Представляет литеральную строку.
+- `Null`:
+  - Представляет значение null.
+
+### Operator
+
+Перечисление `Operator` представляет различные операторы, которые могут быть использованы в выражениях, такие как арифметические и операторы сравнения.
+
+#### Варианты:
+
+- `Add`: Сложение (`+`)
+- `Subtract`: Вычитание (`-`)
+- `Multiply`: Умножение (`*`)
+- `Divide`: Деление (`/`)
+- `GreaterThan`: Больше чем (`>`)
+- `LessThan`: Меньше чем (`<`)
+- `Equal`: Равно (`==`)
+- `NotEqual`: Не равно (`!=`)
+- `And`: Логическое И (`&&`)
+- `Or`: Логическое ИЛИ (`||`)
+
+#### Методы:
+- Доступны различные методы для создания операторов, такие как `add()`, `subtract()`, `multiply()` и др.
+
+### TokenType
+
+Перечисление `TokenType` представляет типы токенов, которые распознаются лексером. Это перечисление используется в процессе лексического анализа для классификации элементов кода.
+
+#### Варианты:
+
+- `COMMENT_MULTILINE`, `COMMENT_SINGLELINE`: Представляют комментарии.
+- `KEYWORD`: Представляет ключевое слово.
+- `IDENTIFIER`: Представляет идентификатор.
+- `INTEGER`, `FLOAT`, `STRING`, `BOOLEAN`: Представляют примитивные типы.
+- `LIST`, `DICT`, `SET`, `TUPLE`: Представляют сложные типы данных.
+- `NULL`, `OPTION`: Представляют специальные типы.
+- `ERROR`: Представляет нераспознанный токен.
+- `FUNCTION`: Представляет функцию.
+- `OPERATOR`, `SYMBOL`, `BRACKET`, `PUNCTUATION`: Представляют операторы, символы и знаки препинания.
+- `PRINT`: Представляет оператор вывода (print).
+- `EOF`: Представляет конец файла.
+
+### Token
+
+Структура `Token` представляет токен в исходном коде. Каждый токен имеет тип (из `TokenType`) и значение (строку, которое этот токен представляет).
+
+#### Поля:
+- `token_type`: Тип токена (из `TokenType`).
+- `value`: Строковое значение токена.
+
+#### Методы:
+- `new(token_type: TokenType, value: &str) -> Self`: Создает новый токен с заданным типом и значением.
+
+## Заключение
+
+В этой документации описана структура абстрактного синтаксического дерева (AST), которое используется для представления исходного кода в виде иерархической модели. Мы рассмотрели основные компоненты AST, такие как узлы программы, операторы и выражения, а также различные типы данных, которые могут быть использованы в процессе анализа и выполнения программы.

documentation/interpreter.md

@@ -0,0 +1,3 @@
+# Документация для интерпретатора 
+
+### ***В разработке...***

documentation/lexer.md

@@ -0,0 +1,90 @@
+# Документация для лексера (токенайзера)
+
+## Обзор
+
+Лексер — это компонент интерпретатора, который выполняет разбиение исходного кода на последовательность токенов. Токены — это атомарные элементы программы, такие как ключевые слова, операторы, идентификаторы и литералы. Лексер находит эти токены с использованием регулярных выражений и классифицирует их по типу.
+
+Он использует регулярные выражения для анализа строк и выявления различных токенов.
+
+## Структуры данных
+
+### `TokenType`
+
+Перечисление, которое описывает типы токенов, которые могут быть распознаны лексером. Включает в себя:
+
+- **COMMENT_MULTILINE**: Многострочные комментарии.
+- **COMMENT_SINGLELINE**: Однострочные комментарии.
+- **KEYWORD**: Ключевые слова языка.
+- **IDENTIFIER**: Идентификаторы (имена переменных, функций и т.д.).
+- **INTEGER**: Целые числа.
+- **FLOAT**: Числа с плавающей точкой.
+- **STRING**: Строки (с двойными кавычками).
+- **BOOLEAN**: Логические значения (true, false).
+- **ANNOTATION_TYPE**: Аннотации типов (например, int, str, bool).
+- **LIST, DICT, SET, TUPLE**: Сложные типы данных (списки, множества, кортежи).
+- **NULL**: Тип данных Null.
+- **OPTION**: Тип данных Option.
+- **ERROR**: Ошибки в исходном коде.
+- **FUNCTION**: Функции.
+- **OPERATOR**: Операторы (например, +, -, =).
+- **SYMBOL**: Символы (например, $, #).
+- **BRACKET**: Скобки (круглые, фигурные, квадратные).
+- **PUNCTUATION**: Пунктуация (например, ;, :, .).
+- **PRINT**: Специальный токен для команды "print!".
+- **EOF**: Конец файла.
+
+### `Token`
+
+Структура, которая представляет собой токен. Каждый токен состоит из:
+
+- **token_type**: Тип токена (например, `KEYWORD`, `IDENTIFIER` и т.д.).
+- **value**: Строковое значение токена, которое может быть ключевым словом, идентификатором, числом и т.д.
+
+Метод `new` создает новый токен с указанным типом и значением.
+
+### `Lexer`
+
+Лексер, который выполняет разбиение исходного кода на токены с использованием регулярных выражений. В нем содержатся:
+
+- **keywords**: Хеш-таблица ключевых слов, где ключ — строка, а значение — тип токена (`KEYWORD`).
+- **regex_patterns**: Список пар, каждая из которых состоит из регулярного выражения и соответствующего типа токена (или `None`, если токен не создается).
+
+Метод `new` инициализирует лексер, добавляет ключевые слова и регулярные выражения для распознавания различных токенов.
+
+Метод `tokenize` выполняет разбор строки исходного кода на токены, проверяя каждый символ с помощью регулярных выражений. Он возвращает результат в виде вектора токенов.
+
+## Регулярные выражения
+
+Лексер использует регулярные выражения для распознавания токенов в исходном коде. Некоторые из них:
+
+- **Комментарии**:
+  - Однострочные комментарии: `//[^\n]*`
+  - Многострочные комментарии: `/\*[\s\S]*?\*/`
+- **Типы данных**:
+  - Примитивные типы: `\b(int|str|bool)\b`
+  - Сложные типы: `\b(list|dict|set|tuple)\b`
+- **Ключевые слова**:
+  - Множество ключевых слов (например, `const`, `func`, `if`, `while`): `\b(?:const|func|var|if|elif|else|while|for|loop|continue|exit|break|return|is|in|and|or|not|try|handle)\b`
+- **Числа**:
+  - Целые числа: `\b\d+\b`
+  - Числа с плавающей точкой: `\b\d+\.\d+\b`
+- **Строки**: `#""([^"\\]|\\.)*""#`
+- **Операторы**: `[+\-*/%=<>!&|^]=?|==|!=|&&|\|\|`
+- **Скобки**: `[\(\)\{\}\[\]]`
+- **Пунктуация**: `[;,:.]`
+
+Каждое регулярное выражение привязывается к соответствующему типу токена или игнорируется (например, пробелы).
+
+## Алгоритм работы
+
+1. Лексер получает строку исходного кода.
+2. Проходит по строке символ за символом, пытаясь найти подходящие регулярные выражения.
+3. Когда выражение находит совпадение, создается токен, который добавляется в список.
+4. Если регулярное выражение не находит совпадений, лексер генерирует ошибку.
+5. Лексер продолжает до тех пор, пока не обработает всю строку.
+6. После завершения обработки добавляется специальный токен `EOF` для обозначения конца файла.
+
+
+## Заключение
+
+Лексер является важным элементом системы анализа исходного кода. Он преобразует строку текста в структуру токенов, которую затем может обработать синтаксический анализатор. Этот лексер поддерживает множество типов токенов, включая комментарии, ключевые слова, типы данных, операторы и другие элементы синтаксиса языка.

documentation/parser.md

@@ -0,0 +1,3 @@
+# Документация для парсера 
+
+### ***В разработке...***

documentation/state_storage.md

@@ -0,0 +1,3 @@
+# Документация для хранилищя состояния
+
+### ***В разработке...***