FoxLang/DOCUMENTATION.md

# 📚 Документация FoxLang v5.0

## Оглавление
1. [Основы синтаксиса](#1-основы-синтаксиса)
2. [Переменные и Типы](#2-переменные-и-типы)
3. [Пользовательские функции](#3-пользовательские-функции)
4. [Математика и Логика](#4-математика-и-логика)
5. [Управляющие конструкции](#5-управляющие-конструкции)
6. [Массивы](#6-массивы)
7. [Модули и Импорт](#7-модули-и-импорт)
8. [Встроенные функции](#8-встроенные-функции)
9. [Современный синтаксис](#9-современный-синтаксис)

---

## 1. Основы синтаксиса
FoxLang использует синтаксис, похожий на C++ и Java.
* Каждая команда **обязана** заканчиваться точкой с запятой `;`.
* Блоки кода выделяются фигурными скобками `{ ... }`.
* Комментарии начинаются с `//` и идут до конца строки.
* Поддерживаются идентификаторы с подчеркиваниями (`user_name`, `get_data`).

```cpp
// Это комментарий
print("Hello"); // Команда
string user_name = "john_doe"; // Современный синтаксис
```

---

## 2. Переменные и Типы

Язык поддерживает пять основных типов данных:

* `int` — Целые числа.
* `float` — Дробные числа с плавающей точкой.
* `string` — Текст в двойных кавычках.
* `bool` — Логический тип (`true` или `false`).
* `void` — Тип для функций без возвращаемого значения.

**Объявление:**

```cpp
int health = 100;
float gravity = 9.8;
string player_name = "Player1";
bool is_alive = true;
```

**Присваивание:**

```cpp
health = 90;
gravity = 1.62;
player_name = "Player2";
is_alive = false;
```

---

## 3. Пользовательские функции

FoxLang поддерживает полноценные пользовательские функции с параметрами и возвратом значений.

### Объявление функций

```cpp
// Функция с возвращаемым значением
int add(int a, int b) {
    return a + b;
}

// Функция без возвращаемого значения
void greet(string name) {
    print("Hello, " + name + "!");
}

// Функция без параметров
string get_version() {
    return "FoxLang 5.0";
}
```

### Вызов функций

```cpp
int result = add(5, 3);
greet("Alice");
string version = get_version();
print("Version: " + version);
```

### Рекурсивные функции

```cpp
int factorial(int n) {
    if (n <= 1) {
        return 1;
    }
    return n * factorial(n - 1);
}

int fact5 = factorial(5); // 120
```

### Локальные переменные

```cpp
int calculate_area(int width, int height) {
    int area = width * height; // Локальная переменная
    return area;
}
```

> **Важно:** Нельзя объявить переменную с именем, которое уже существует в текущей области видимости.
> При присваивании дробного значения переменной типа `int`, оно будет автоматически преобразовано в целое (отброшена дробная часть).

---

## 4. Математика и Логика

Поддерживаются стандартные арифметические операции с учетом приоритета.

### Арифметические операторы

| Оператор | Описание | Пример |
| --- | --- | --- |
| `+` | Сложение / Конкатенация строк | `5 + 5` или `"A" + "B"` |
| `-` | Вычитание | `10 - 2` |
| `*` | Умножение | `2 * 2` |
| `/` | Деление | `10 / 2` |
| `%` | Остаток от деления | `10 % 3` (вернет 1) |
| `++` | Инкремент (увеличение на 1) | `i++` (вернет старое значение, затем увеличит переменную) |

### Операторы сравнения

Операторы сравнения возвращают `1` (истина) или `0` (ложь).

| Оператор | Описание | Пример |
| --- | --- | --- |
| `==` | Равно | `x == 5` |
| `!=` | Не равно | `x != 5` |
| `<` | Меньше | `x < 10` |
| `>` | Больше | `x > 0` |

### Логические операторы

FoxLang поддерживает логические операторы для работы с boolean значениями:

| Оператор | Описание | Пример |
| --- | --- | --- |
| `&&` | Логическое И (AND) | `(x > 0) && (x < 10)` |
| `\|\|` | Логическое ИЛИ (OR) | `(x == 0) \|\| (x == 1)` |
| `!` | Логическое НЕ (NOT) | `!(x == 0)` |

```cpp
bool is_valid = (age >= 18) && (age <= 65);
bool is_weekend = (day == "Saturday") || (day == "Sunday");
bool is_not_empty = !name.empty();
```

---

## 5. Управляющие конструкции

### Условия (If / Else)

```cpp
int x = 10;
if (x == 10) {
    print("X is ten");
} else {
    print("X is not ten");
}
```

### Циклы (While)

Выполняет блок кода, пока условие истинно.

```cpp
int i = 0;
while (i < 5) {
    print("Loop iteration: " + i);
    i++;
}
```

### Циклы (For)

Классический цикл `for`, состоящий из инициализации, условия и шага.

```cpp
for (int i = 0; i < 5; i++) {
    print("For loop: " + i);
}
```

### Switch/Case конструкции

FoxLang поддерживает конструкции `switch/case` с поддержкой `break` и `default`:

```cpp
int day = 3;
switch (day) {
    case 1:
        print("Понедельник");
        break;
    case 2:
        print("Вторник");
        break;
    case 3:
        print("Среда");
        break;
    default:
        print("Другой день");
        break;
}
```

### Управление циклами

- `break` — Прерывает выполнение цикла или switch
- `continue` — Переходит к следующей итерации цикла

```cpp
for (int i = 0; i < 10; i++) {
    if (i == 5) {
        continue; // Пропустить 5
    }
    if (i == 8) {
        break; // Выйти из цикла
    }
    print(i);
}
```

### Области видимости (Scope)

Блоки кода `{ ... }` создают новую область видимости. Переменные, объявленные внутри блока, недоступны снаружи.

```cpp
int global = 10;
{
    int local = 5;
    print(global); // 10
    print(local);  // 5
}
// print(local); // Ошибка! Переменная local не существует здесь.
```

---

## 6. Массивы

Массивы в FoxLang имеют фиксированный размер при создании.

1. **Создание:** `array имя размер;`
2. **Запись:** `set(имя, индекс, значение);`
3. **Чтение:** `get(имя, индекс)`
4. **Размер:** `size(имя)`

```cpp
array chest 3;     // Массив на 3 элемента
set(chest, 0, 55); // Записать 55 в индекс 0
print(get(chest, 0)); // Выведет 55
```

---

## 7. Модули и Импорт

FoxLang поддерживает импорт внешних модулей.
Используйте `include("путь/к/файлу.fox");`.

**Особенности:**

* При подключении внешних модулей код, находящийся вне функций, будет выполнен при импорте. Глобальные переменные и функции становятся доступными в текущем файле.

---

## 8. Встроенные функции

### Ввод/Вывод
| Функция | Описание | Пример |
| --- | --- | --- |
| `print(expr...)` | Выводит текст или результат выражения в консоль. Может принимать несколько аргументов. | `print("Hello", name);` |
| `input()` | Ждет ввода строки от пользователя и возвращает её. | `string name = input();` |
| `input(prompt)` | Выводит приглашение и ждет ввода строки. | `string name = input("Имя: ");` |

### Математические функции
| Функция | Описание | Пример |
| --- | --- | --- |
| `round(number)` | Округляет дробное число до ближайшего целого. | `int x = round(3.7); // 4` |
| `random(min, max)` | Генерирует случайное число в диапазоне от min до max включительно. | `int dice = random(1, 6);` |

### Работа с файлами
| Функция | Описание | Пример |
| --- | --- | --- |
| `read_file(filename)` | Читает первую непустую строку из файла (игнорирует комментарии #). | `string config = read_file("config.txt");` |

### HTTP запросы
| Функция | Описание | Пример |
| --- | --- | --- |
| `httpget(url)` | Выполняет HTTP GET запрос и возвращает ответ сервера. | `string data = httpget("https://api.example.com");` |
| `httppost(url, data)` | Выполняет HTTP POST запрос с данными. | `string response = httppost(url, "{\"key\":\"value\"}");` |
| `httppost(url, data, content_type)` | HTTP POST с указанием типа контента. | `httppost(url, data, "application/json");` |
| `httpput(url, data)` | Выполняет HTTP PUT запрос с данными. | `string response = httpput(url, data);` |
| `httpput(url, data, content_type)` | HTTP PUT с указанием типа контента. | `httpput(url, data, "text/plain");` |
| `httpdelete(url)` | Выполняет HTTP DELETE запрос. | `string response = httpdelete(url);` |

### Работа со строками и JSON
| Функция | Описание | Пример |
| --- | --- | --- |
| `json_get(json_string, key)` | Извлекает значение по ключу из JSON строки. Поддерживает ключи: "chat_id", "text", "update_id". | `string chat_id = json_get(response, "chat_id");` |
| `str_contains(text, substring)` | Проверяет, содержит ли строка подстроку. Возвращает `true` или `false`. | `bool found = str_contains("Hello World", "World");` |
| `str_to_int(string)` | Преобразует строку в целое число. При ошибке возвращает 0. | `int num = str_to_int("123");` |

### Ввод с клавиатуры (низкоуровневый)
| Функция | Описание | Пример |
| --- | --- | --- |
| `getch()` | Читает один символ с клавиатуры без нажатия Enter. | `string key = getch();` |
| `kbhit()` | Проверяет, была ли нажата клавиша. Возвращает `true` или `false`. | `bool pressed = kbhit();` |

### Системные функции
| Функция | Описание | Пример |
| --- | --- | --- |
| `wait(milliseconds)` | Приостанавливает выполнение программы на указанное количество миллисекунд. | `wait(1000); // Пауза 1 секунда` |
| `fox()` | Пасхалка: выводит название языка "FoxLang". | `fox();` |

---

## 9. Современный синтаксис

FoxLang поддерживает современные соглашения по именованию и синтаксису:

### Идентификаторы с подчеркиваниями

В отличие от старых версий, FoxLang теперь полностью поддерживает идентификаторы с подчеркиваниями:

```cpp
// Переменные
string user_name = "john_doe";
int max_health = 100;
bool is_game_over = false;

// Функции
void calculate_damage(int base_damage, float multiplier) {
    // ...
}

int get_player_score() {
    return player_score;
}
```

### Глобальные переменные

FoxLang поддерживает объявление глобальных переменных с ключевым словом `global`:

```cpp
global int game_score = 0;
global string player_name = "Unknown";

void update_score(int points) {
    game_score = game_score + points;
}

void main() {
    print("Score: " + game_score);
    update_score(100);
    print("New score: " + game_score);
}
```

### Примеры современного кода

```cpp
// Современная функция с подчеркиваниями
bool check_user_permissions(string user_role, int required_level) {
    if (user_role == "admin") {
        return true;
    }
    
    int user_level = get_user_level(user_role);
    return user_level >= required_level;
}

// Работа с массивами
void sort_user_scores(array scores, int count) {
    for (int i = 0; i < count - 1; i++) {
        for (int j = 0; j < count - i - 1; j++) {
            if (get(scores, j) > get(scores, j + 1)) {
                int temp = get(scores, j);
                set(scores, j, get(scores, j + 1));
                set(scores, j + 1, temp);
            }
        }
    }
}
```

---