# Техническая документация PyLite

## Архитектура

PyLite состоит из следующих основных компонентов:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Source Code   │ -> │      Lexer       │ -> │     Tokens      │
│     (.pyl)      │    │  (Tokenization)  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                        |
                                                        v
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Interpreter   │ <- │      Parser      │ <- │       AST       │
│  (Execution)    │    │  (Syntax Tree)   │    │ (Abstract Tree) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
```

## Компоненты

### 1. Лексический анализатор (Lexer)

Файл: `pylite/lexer.py`

Отвечает за разбиение исходного кода на токены.

**Основные классы:**
- `Lexer` - главный класс лексера
- `Token` - представляет один токен
- `TokenType` - перечисление типов токенов

**Поддерживаемые токены:**
- Литералы: числа, строки, булевы значения
- Идентификаторы и ключевые слова
- Операторы: `+`, `-`, `*`, `/`, `==`, `!=`, и т.д.
- Разделители: `(`, `)`, `[`, `]`, `{`, `}`, `,`, `:`, `.`
- Специальные: `NEWLINE`, `INDENT`, `DEDENT`, `EOF`

**Особенности:**
- Автоматическое отслеживание отступов для блоков кода
- Обработка комментариев (игнорирование)
- Поддержка escape-последовательностей в строках

### 2. Синтаксический анализатор (Parser)

Файл: `pylite/parser.py`

Строит абстрактное синтаксическое дерево (AST) из токенов.

**Основные классы:**
- `Parser` - главный класс парсера
- Узлы AST в `pylite/ast_nodes.py`

**Поддерживаемые конструкции:**
- Выражения: литералы, бинарные/унарные операции, вызовы функций
- Команды: присваивание, условия, циклы, определения функций/классов
- Приоритет операторов согласно Python

**Алгоритм:**
- Рекурсивный спуск (Recursive Descent)
- Правильная обработка приоритета операторов
- Обработка отступов для блочной структуры

### 3. Интерпретатор (Interpreter)

Файл: `pylite/interpreter.py`

Выполняет код, обходя AST.

**Основные классы:**
- `Interpreter` - главный класс интерпретатора
- `Environment` - управление областями видимости
- `CallableFunction` - пользовательские функции
- `PyLiteClass` / `PyLiteInstance` - классы и объекты

**Возможности:**
- Выполнение всех поддерживаемых конструкций
- Управление областями видимости
- Встроенные функции и модули
- Обработка исключений

### 4. Обработка ошибок (Error Handler)

Файл: `pylite/error_handler.py`

Предоставляет дружелюбные сообщения об ошибках для детей.

**Типы ошибок:**
- `LexerError` - ошибки лексического анализа
- `ParserError` - ошибки синтаксического анализа  
- `RuntimeError` - ошибки времени выполнения
- `ValidationError` - ошибки валидации ограничений

**Особенности:**
- Сообщения на русском языке
- Эмодзи для разных типов ошибок
- Конкретные советы по исправлению

### 5. Встроенные функции и модули

Файл: `pylite/builtins.py`

**Встроенные функции:**
- `print()`, `input()`, `len()`, `type()`
- `str()`, `int()`, `float()`, `bool()`
- `range()`, `max()`, `min()`, `sum()`, `abs()`
- `round()`, `pow()` - дополнительные математические функции

**Модули:**
- `math` - математические функции
- `random` - генерация случайных чисел
- `time` - работа с временем
- `turtle` - черепашья графика (отображение в окне с помощью PyQt5)
- `sound` - воспроизведение звуков

### 6. CLI интерфейс

Файл: `pylite/cli.py`

**Классы:**
- `REPL` - интерактивная оболочка
- `PyLiteRunner` - выполнение файлов

**Возможности:**
- Интерактивный режим с приглашением
- Выполнение .pyl файлов
- Выбор режима (базовый/расширенный)
- Обработка ошибок командной строки

## Окружения и области видимости

PyLite использует стековую модель областей видимости:

```python
global_env = Environment()           # Глобальная область
function_env = Environment(global)   # Область функции
block_env = Environment(function)    # Область блока
```

При поиске переменных происходит поиск вверх по цепочке окружений.

## Режимы работы

### Базовый режим (basic)
- Все ограничения включены
- Максимум 500 строк кода
- Глубина вложенности до 3 уровней
- Длина строки до 80 символов

### Расширенный режим (extended)  
- Ослаблены некоторые ограничения
- Больше возможностей для продвинутых учеников

## Расширение PyLite

### Добавление новых встроенных функций

```python
def my_builtin_function(arg1, arg2):
    # Ваша логика
    return result

# Добавьте в create_builtins() в builtins.py
'my_function': BuiltinFunction('my_function', my_builtin_function, 2, 2)
```

### Добавление нового модуля

```python
def create_my_module() -> Dict[str, Any]:
    return {
        'my_function': BuiltinFunction('my_function', impl, 1, 1),
        'MY_CONSTANT': 42,
    }

# Добавьте в create_modules() в builtins.py
'my_module': create_my_module()
```

### Добавление нового типа узла AST

1. Создайте класс в `ast_nodes.py`:

```python
@dataclass
class MyStmt(Statement):
    param: str
```

2. Добавьте парсинг в `parser.py`
3. Добавьте выполнение в `interpreter.py`

### Использование модуля `turtle`

```python
# turtle_example.pyl
import turtle

# Рисуем красный квадрат
turtle.color("red")
for _ in range(4):
    turtle.forward(100)
    turtle.right(90)

# Показываем результат в окне
turtle.done()
```

### Использование модуля `sound`

```python
# sound_example.pyl
import sound
import time

# Воспроизводим встроенный звук (должен быть в pylite/assets/sounds)
sound.play("click")
time.sleep(1)

# Воспроизводим внешний звук по относительному пути
# (предполагается, что файл mygame/sounds/explosion.wav существует)
# sound.play("mygame/sounds/explosion.wav")
```

### Использование модуля `turtle`

```python
# turtle_example.pyl
import turtle

# Рисуем красный квадрат
turtle.color("red")
for _ in range(4):
    turtle.forward(100)
    turtle.right(90)

# Показываем результат в окне
turtle.done()
```

### Использование модуля `sound`

```python
# sound_example.pyl
import sound
import time

# Воспроизводим встроенный звук (должен быть в pylite/assets/sounds)
sound.play("click")
time.sleep(1)

# Воспроизводим внешний звук по относительному пути
# (предполагается, что файл mygame/sounds/explosion.wav существует)
# sound.play("mygame/sounds/explosion.wav")
```

## Тестирование

Структура тестов:
```
tests/
├── test_lexer.py           # Тесты лексера
├── test_parser.py          # Тесты парсера  
├── test_interpreter.py     # Тесты интерпретатора
└── test_integration.py     # Интеграционные тесты
```

Запуск тестов:
```bash
python run_tests.py
```

## Развёртывание

### Локальная разработка

```bash
# Клонирование
git clone <repo-url>
cd pylite

# Установка в режиме разработки
pip install -e .

# Запуск тестов
python run_tests.py
```

### Создание пакета

```bash
# Сборка
python setup.py sdist bdist_wheel

# Публикация (тестовый PyPI)
twine upload --repository-url https://test.pypi.org/legacy/ dist/*

# Публикация (основной PyPI)  
twine upload dist/*
```

## Производительность

PyLite оптимизирован для обучения, а не для производительности:
- Простота и понятность кода важнее скорости
- Подробные сообщения об ошибках
- Валидация ограничений

Типичная производительность:
- Лексический анализ: ~10,000 строк/сек
- Синтаксический анализ: ~5,000 строк/сек
- Выполнение: зависит от сложности кода

## Безопасность

Ограничения безопасности:
- Нет доступа к файловой системе
- Нет сетевых операций
- Ограничения на размер программы
- Нет выполнения произвольного кода

## Совместимость

- Python 3.8+
- Кроссплатформенность: Windows, Linux, macOS
- Только стандартная библиотека Python

## Roadmap

Планы развития:
1. Визуальный отладчик
2. Веб-интерфейс
3. Больше встроенных модулей
4. Улучшенные сообщения об ошибках
5. Интеграция с IDE

## Вклад в проект

1. Fork репозитория
2. Создайте ветку функции
3. Добавьте тесты
4. Отправьте Pull Request

Требования к коду:
- Следуйте PEP 8
- Добавляйте docstrings
- Покрытие тестами > 80%
- Дружелюбные сообщения об ошибках
