🇧🇬 ЖАР (Zhar)

Runtime Status:

ЖАР е модерен програмен език с българска синтактика. Подходящ за обучение, прототипиране и професионална разработка.

---

📋 Версии и Release Channels

Какво означава "1.0" vs "3.x"?

ЖАР използва две независими версионни схеми за ясно разделение:

• Language Specification v1.0 - Спецификацията на езика (стабилна, дефинирана)
• Runtime/Toolchain v3.1.0 - Имплементацията и tooling-ът (еволюираща, подобряваща се)

Language Spec v1.0 дефинира синтаксиса, семантиката и API-то на стандартната библиотека. Тя е стабилна и гарантира backwards compatibility.

Runtime v3.1.0 е версията на имплементацията - runtime ядрата, CLI инструментите, компилаторите. Тя еволюира с нови features и подобрения, но остава съвместима със спецификацията.

Release Channels

Channel	Статус	Използване
Stable	✅ Production-ready	Препоръчително за всички
RC	⚠️ Release Candidate	Финални тестове преди stable
Beta	⚠️ Нови features	Тестване, feedback добре дошъл
Alpha	🧪 Експериментално	Само за разработка, не за production

Текуща версия: Runtime v3.1.0 (Stable) съвместима със Language Spec v1.0

За пълна информация вижте Version Policy.

---

🚀 Ново в версия 3.1.0

✅ Native Backends - Всички работят!

Последни подобрения (Януари 2025):

• ✅ C++ Backend - Поправено зареждане на библиотеката, поддръжка на версионирани библиотеки
• ✅ Rust Backend - Компилиран и интегриран, lazy initialization
• ✅ Go Backend - Интегриран като Python bridge, активен и работи
• ✅ ZPM (Package Manager) - Интегриран като команда, добавени зависимости

Тестове: 9/9 теста преминават успешно (100% успех)

Backend	Статус	Версия
Rust Core	✅ Production	3.1.0
C++ Core	✅ Active	2.2.24
Go Core	✅ Active	2.1.0
Python Core	✅ Reference	3.1.0

📦 ZPM v2 - Пълен Package Manager

Команда	Описание
zpm init	Създава нов проект
zpm add	Добавя зависимост
zpm update	Обновява зависимости
zpm lock	Генерира lock файл
zpm vendor	Кешира локално
zpm publish	Публикува в registry
zpm search	Търси пакети
zpm info	Информация за пакет
zpm list	Инсталирани пакети

📚 8 Официални модула

Модул	Описание
zhar-http	HTTP клиент (GET, POST, PUT, DELETE)
zhar-http-server	REST сървър с routing и middleware
zhar-json	JSON parse/stringify
zhar-yaml	YAML поддръжка
zhar-cli	CLI инструменти (аргументи, цветове, progress bar)
zhar-crypto	Криптография (SHA, HMAC, Argon2, Ed25519, AES-GCM)
zhar-sqlite	SQLite база с QueryBuilder и миграции
zhar-logging	Структурирано логване с нива

📖 10 Cookbook рецепти

Рецепта	Категория
Mini Web API	Web
REST Client с JWT/OAuth2	Web
Worker Queue система	Web
Simple Web GUI	Web
File Processor	CLI
JSON Processing	Data
Sorting Algorithms	Algorithms
Cyrillic Processing	Unicode
Python Integration (NumPy, Pandas)	Bridges
Rust Integration (PyO3, Rayon)	Bridges

🔧 LSP v2.3.0

• ✅ Autocomplete с контекст
• ✅ Hover информация
• ✅ Go-to definition
• ✅ Find references
• ✅ Rename символи
• ✅ Document formatting
• ✅ Diagnostics (грешки, предупреждения)
• ✅ Code actions (quick fixes)
• ✅ Semantic highlighting
• ✅ VS Code extension с snippets
• ✅ Neovim конфигурация

📜 Language Specification v1.0

• 01-introduction.md - Цели и обхват
• 02-lexical.md - Токени, идентификатори, ключови думи
• 03-types.md - Типова система
• 06-functions.md - Функции, ламбди, рекурсия
• 07-classes.md - ООП, наследяване
• 08-modules.md - Модулна система
• 09-unicode.md - UAX #31, NFC, UTS #39
• 10-errors.md - Exception handling

🤝 Community

Канал	Линк
Discord	discord.gg/zhar-lang
Telegram	@zhar_lang
Forgejo Issues	https://git.vi-lab.eu/orion/zhar/issues
Twitter/X	@zhar_lang
LinkedIn	ЖАР Programming Language
Reddit	r/zhardev

📊 Benchmark Suite

# Изпълни всички benchmarks
python benchmarks/run_all.py

# JSON изход
python benchmarks/run_all.py --json

# Конкретна категория
python benchmarks/run_all.py --category compute

Категория	Тестове
compute	fibonacci, primes, quicksort
strings	concat, search, replace
collections	list ops, dict ops
unicode	NFC normalization

🔧 CI/CD Quality Gates

Job	Описание
lint-python	ruff, black, mypy
lint-rust	rustfmt, clippy
test-python	pytest + coverage
test-rust	cargo test
benchmarks	Performance tracking
security	Trivy, Safety, Bandit
docs	MkDocs build

📚 Docs Site (47 страници)

cd docs/site
mkdocs serve -a 0.0.0.0:1000
# http://localhost:1000

Секция	Страници
Getting Started	5
Spec	10
Stdlib	7
ZPM	5
Cookbook	5
Cores	5
API	5
Contributing	4
Blog	1

---

📋 Съдържание

1. Инсталация
2. Hello World
3. CLI команди
4. Примери
5. ZPM (Package Manager)
6. Официални модули
7. LSP и IDE поддръжка
8. Cookbook
9. За образование
10. Архитектура
11. Документация
12. Community
13. Принос

---

🚀 Инсталация

Вариант 1: Стандартна инсталация

# 1. Клониране
git clone https://git.vi-lab.eu/orion/zhar.git
cd zhar

# 2. Python среда
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate   # Windows

# 3. Инсталация
pip install -e ".[dev]"

# 4. Проверка
zhar --version

Вариант 2: Бърза инсталация

# Forgejo-first: използва raw файл от Forgejo
curl -sSL https://git.vi-lab.eu/orion/zhar/raw/branch/main/scripts/install.sh | sh

Вариант 3: Docker Compose (Препоръчително)

# Стартиране на всички услуги
docker compose up -d --build

# Проверка на статус
docker compose ps

# Логове
docker compose logs -f

Достъпни услуги:

• 📚 Documentation: http://localhost:1000
• 🎮 Playground: http://localhost:1001
• 🧮 Calculator: http://localhost:1002
• 🌐 Web Interpreter: http://localhost:1003
• 🖥️ Dashboard: http://localhost:1004

Вариант 4: Docker (Standalone)

docker pull zhar-lang/zhar:latest
docker run -it zhar-lang/zhar

Системни изисквания

Компонент	Минимум	Препоръчително
Python	3.10+	3.11+
Rust	1.70+	1.75+ (за Rust Core)
RAM	512 MB	2 GB
Disk	100 MB	500 MB

---

👋 Hello World

печат "Здравей, свят!"

zhar run hello.zhar
# Изход: Здравей, свят!

---

🛠️ CLI команди

Основни

Команда	Описание
zhar run <file>	Изпълнява файл
zhar repl	Интерактивен режим
zhar check <file>	Проверка без изпълнение
zhar fmt <file>	Форматиране
zhar test	Изпълнява тестове
zhar --version	Показва версия

Безопасност

zhar run --sandbox app.zhar          # Изолиран режим
zhar run --no-fs app.zhar            # Без файлова система
zhar run --no-net app.zhar           # Без мрежа
zhar run --memory-limit 50MB app.zhar # Лимит памет

---

💡 Примери на езика

Променливи

нека име = "Иван"
нека възраст = 25
нека активен = истина

Условия

ако възраст >= 18 тогава
    печат "Пълнолетен"
иначе
    печат "Непълнолетен"
край

Цикли

за x в [1, 2, 3, 4, 5]
    печат x * 2
край

Функции

функция факториел(n: число) -> число
    ако n <= 1 тогава
        връщай 1
    край
    връщай n * факториел(n - 1)
край

печат факториел(5)  # 120

Класове

клас Точка
    функция нов(x: число, y: число)
        моя.x = x
        моя.y = y
    край
    
    функция разстояние() -> число
        връщай (моя.x ** 2 + моя.y ** 2) ** 0.5
    край
край

нека т = Точка(3, 4)
печат т.разстояние()  # 5.0

---

📦 ZPM (Package Manager)

Статус: ✅ Работи (интегриран като команда)

ZPM е пълнофункционален package manager за ЖАР, интегриран като команда в проекта.

Команди v2

Команда	Описание
zpm init	Създава нов проект
zpm add <pkg>	Добавя зависимост
zpm update	Обновява зависимости
zpm lock	Генерира lock файл
zpm vendor	Кешира локално
zpm publish	Публикува в registry
zpm search <query>	Търси пакети
zpm info <pkg>	Информация за пакет
zpm list	Инсталирани пакети

Пример

zpm init моят_проект
cd моят_проект
zpm add zhar-http@^1.0.0
zpm add zhar-json@^1.0.0
zhar run main.zhar

zpm.toml

[package]
name = "моят_проект"
version = "1.0.0"
authors = ["Иван Петров <ivan@example.com>"]

[dependencies]
zhar-http = "^1.0.0"
zhar-json = "^1.0.0"

---

📚 Официални модули

Модул	Описание	Пример
zhar-http	HTTP клиент	GET("https://api.com")
zhar-http-server	REST сървър	сървър.GET("/api", handler)
zhar-json	JSON	parse(json_низ)
zhar-yaml	YAML	прочети("config.yaml")
zhar-cli	CLI tools	ArgParser, Цветове, ProgressBar
zhar-crypto	Криптография	SHA256, Ed25519, AES_GCM
zhar-sqlite	SQLite	Database, QueryBuilder, Migration
zhar-logging	Логване	info(), error(), debug()

Използване

импортирай GET, POST от zhar-http
импортирай parse, stringify от zhar-json

нека отговор = GET("https://api.example.com/data")
нека данни = parse(отговор.body)
печат данни["name"]

---

🔧 LSP и IDE поддръжка

VS Code

cd releases/lsp/vscode
npm install
npm run compile
code --install-extension zhar-lsp-2.3.0.vsix

Features:

• Autocomplete
• Hover информация
• Go-to definition
• Find references
• Rename
• Formatting
• 19 Snippets

Neovim

-- ~/.config/nvim/lua/zhar.lua
local nvim_lsp = require('lspconfig')
nvim_lsp.zhar_lsp.setup({
    cmd = { 'zhar_lsp' },
    filetypes = { 'zhar' },
})

Keybindings:

• gd - Go to definition
• K - Hover
• gr - References
• <space>rn - Rename
• <space>f - Format

---

📖 Cookbook

Практически примери в cookbook/:

Рецепта	Описание
Mini Web API	REST API с GET/POST
REST Client	JWT, OAuth2, API Key
Worker Queue	Background jobs
Web GUI	HTML/CSS/JS GUI
File Processor	CLI tool
JSON Processing	Parse, stringify
Sorting	Bubble, Selection, Insertion
Cyrillic	Unicode, NFC
Python	NumPy, Pandas
Rust	PyO3, Rayon

---

🎓 ЖАР за образование

Инсталация за учебни цели

git clone --depth 1 https://git.vi-lab.eu/orion/zhar.git
cd zhar
python -m venv .venv && source .venv/bin/activate
pip install -e .

Директории за преподаватели

Директория	Описание
examples/	200+ примери
examples/golden/	Еталонни тестове
cookbook/	10 практически рецепти
hero_projects/	3 демо проекта

Безопасен режим за изпити

zhar run --sandbox --no-fs --no-net student.zhar
timeout 10 zhar run student.zhar

---

🏗️ Архитектура

Изходен код (.zhar)
        ↓
    Лексер (UTF-8, NFC, UAX #31)
        ↓
    Парсер (Recursive descent)
        ↓
      AST
        ↓
  Type Checker + Security (UTS #39)
        ↓
      ZIR
        ↓
  ┌────┴────┐
  ▼         ▼
Python   Rust/C++/Go
  VM      Backend

Runtime Policy

Ядро	Статус	CI Policy
Rust Core	🟢 Production	Blocking
C++ Core	🟢 Active	Blocking
Go Core	🟢 Active	Blocking
Python Core	🔵 Reference	Warning

Unicode Support (3.1.0)

Feature	Python	Rust	C++	Go
UAX #31	✅	✅	✅	✅
NFC	✅	✅	✅	✅
UTS #39 Confusables	✅	✅	⏳	✅
Mixed Script	✅	✅	⏳	✅

---

📚 Документация

Документ	Описание
spec/v1.0/	Language Specification v1.0
docs/RUNTIME_POLICY.md	Runtime Policy
docs/UNICODE_POLICY.md	Unicode Policy
docs/ECOSYSTEM_STRATEGY.md	Ecosystem Strategy
cookbook/	Practical recipes
CHANGELOG.md	Version history
CONTRIBUTING.md	How to contribute
CODE_OF_CONDUCT.md	Code of Conduct

Docs Site

# Build docs
pip install mkdocs-material
cd docs/site
mkdocs serve
# Open http://localhost:8000

---

🤝 Community

Канал	Описание
Discord	Чат, помощ, идеи
Telegram	@zhar_lang - новини
Forgejo Issues	RFC, Q&A, bug reports
Twitter/X	@zhar_lang - releases
LinkedIn	Професионална мрежа
Reddit	r/zhardev

Контакт

Цел	Email
Общи въпроси	hello@zhar-lang.org
Сигурност	security@zhar-lang.org
Бизнес	business@zhar-lang.org

---

🤝 Принос

Вижте CONTRIBUTING.md за пълни инструкции.

# 1. Fork и clone
git clone https://git.vi-lab.eu/YOUR_USER/zhar.git

# 2. Създай branch
git checkout -b feature/my-feature

# 3. Промени и тестове
pytest tests/

# 4. Commit (conventional commits)
git commit -m "feat(parser): add lambda support"

# 5. Push и PR
git push origin feature/my-feature

Code Style

• Python: PEP 8, type hints, ruff, black
• Rust: rustfmt, clippy
• Commits: Conventional Commits

---

📊 Статус на проекта

Компонент	Статус	Версия
Език (Core)	✅ Stable	3.1.0
Rust Core	✅ Production	3.1.0
C++ Core	✅ Active	2.2.24
Go Core	✅ Active	2.1.0
ZPM	✅ Stable	2.0
LSP	✅ Stable	2.3.0
Официални модули	✅ Stable	1.0.0
Cookbook	✅ Complete	10 recipes
Spec v1.0	✅ Complete	10 docs
Docs Site	✅ Complete	47 pages
Benchmark Suite	✅ Complete	4 categories
CI/CD	✅ Complete	Quality Gates
Comprehensive Tests	✅ Complete	100% success
Playground	⚠️ Beta	-

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

Метрика	Rust Core	Python Core
Fibonacci(40)	0.8s	45.2s
String 1M	0.15s	2.1s
List 100K	0.05s	0.9s

CI/CD

# Quality Gates на всеки PR
- Lint (Python + Rust)
- Tests (pytest + cargo test)
- Security (trivy, safety)
- Docs build

Тестване

Всеобхватни тестове:

• ✅ test_capabilities.py - Базов тест за езикови функции (27 теста)
• ✅ test_comprehensive_capabilities.py - Всеобхватен тест за всички компоненти (9 теста)
• ✅ 100% успех на всички тестове

# Изпълни всеобхватен тест
python -c "from tests.test_comprehensive_capabilities import print_comprehensive_report; print_comprehensive_report()"

# Или с pytest
pytest tests/test_comprehensive_capabilities.py -v

Покрити компоненти:

• CLI команди (zhar --version, zhar run, zhar check)
• Standard Library модули (мат, текст, списък, речник)
• Native Backends (Rust, C++, Go)
• FFI Bridges (Python)
• Type System (annotations, inference)
• ZPM (Package Manager)
• Примерни файлове

---

📄 Лиценз

MIT License - вижте LICENSE

---

🔗 Линкове

• Git: https://git.vi-lab.eu/orion/zhar
• Docs: docs.zhar-lang.org (coming soon)
• Discord: discord.gg/zhar-lang
• Blog: docs/blog/

---

ЖАР - Българският програмен език! 🇧🇬🔥