🐍 Piton - Українська Транскрипційна Мова Програмування

«Мова, яка розуміє тебе з пів слова»

Piton - це легка, інтерпретована мова програмування з автентичним українським синтаксисом (написаним транслітом). Створена переважно для освітніх цілей, швидкого системного прототипування та практичного вивчення принципів побудови трансляторів(інтерпретаторів).

🌐 Свобода кодування без залежності від платформи: репозиторій доступний не тільки на Github, а й на Codeberg

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

Якщо ви хочете саме вивчати мову, а не читати огляд репозиторію, починайте з документації.

Також ви можете:

• Локально зібрати документацію: mdbook build docs
• Локально відкрити документацію: mdbook serve docs

🎭 Філософія та "Великодні яйця"

Проєкт базується на кількох ключових постулатах:

• Я не виправляю помилки, я перетворюю їх на фічі. Якщо лексична помилка повторюється достатньо часто, вона має повне право стати системним стандартом.
• Авторитет коду. Інтерпретатор не знає емоцій і не зважає на наукові ступені. Якщо написано Piton, парситися і виконуватися буде саме Piton.
• Гнучкість у найменуванні. Нехай кожен називає речі так, як йому підказує фонетика. Орфографія - це умовність, логіка - абсолют.

💥 Унікальна система обробки помилок

Piton має власний характер. Замість нудних і незрозумілих трейсбеків (Tracebacks), у разі синтаксичної або логічної помилки (наприклад, ділення на нуль або невідповідність типів) інтерпретатор відповідає вам так, як відповів би суворий викладач програмування:

«Ryadok [-]: Ya tut interpretator, ya znayu yak maye buty. A tak yak ty pyshesh, tak buty ne maye! (Type mismatch)»

⚙️ Технічні особливості

Попри гумористичну передісторію, під капотом Piton - це серйозний програмний інструмент, написаний мовою Go з дотриманням архітектурних патернів розробки мов програмування:

• 🗺️ Нативна візуалізація (SVG формат): Вбудований лінкер збирає "Супер-Дерево" (Super AST) з усіх імпортованих файлів і генерує ідеальні векторні блок-схеми за стандартами ДСТУ.
• 🧠 Recursive Descent Parser (Рекурсивний спуск): Власний, математично вивірений парсер, що генерує абстрактне синтаксичне дерево (AST) з нуля, без використання сторонніх генераторів (на кшталт yacc/bison).
• 🌳 Tree-walking Evaluator: Експресивний інтерпретатор, який обходить AST та ефективно виконує інструкції.
• 🔀 Динамічна типізація та гетерогенні списки: Змінні можуть містити будь-який тип даних, а масиви - безпечно змішувати числа, рядки та інші значення в одному списку без паніки системи типів.
• 📦 Block Scoping (Область видимості): Підтримка ізоляції змінних у функціях та циклах.
• 🧩 Передача параметрів: Аргументи функцій оцінюються в оточенні виклику і записуються в нове локальне Environment перед виконанням тіла, тож функція отримує власні копії параметрів, але й усе ще бачить глобальні дані через ланцюг outer.
• 🔄 Тюринг-повнота: Повна підтримка розгалужень (yaksho/inackshe), циклів (poky), функцій (functia) та вбудованих математичних операцій (від кореня до арксинуса).

🗺️ Генератор Блок-схем (Visualizer)

Piton не тільки виконує ваш код, але й вміє автоматично його креслити! Завдяки вбудованому рушію візуалізації (на базі формату D2), ви можете в одну команду перетворити ваші скрипти на професійні векторні блок-схеми.

Це працює не просто як "малювалка тексту". Інтерпретатор Piton створює повноцінне "Супер-Дерево" (Super AST), з режимом -all може автоматично підтягнути всі залежності через vykorystaty, і групує функції у візуальні рамки відповідних модулів. Головний потік програми виділяється як "Головна програма" для легкого читання.

Ви можете гнучко керувати генерацією через CLI:

• ./piton -draw ./main.piton - згенерувати повну схему для одного файлу.
• ./piton -all ./main.piton - згенерувати повну схему всього проєкту в одному файлі (flowchart.svg).
• ./piton -draw -split ./main.piton - розбити схему на частини (кожна функція генерується в окремий файл, напр. Hello.svg).
• ./piton -draw -target=myFunc ./main.piton - згенерувати блок-схему виключно для вказаної функції.

💻 Приклад Коду

Синтаксис Piton інтуїтивно зрозумілий. Ось фрагмент реального коду (повна демонстрація можливостей, включаючи математичні операції korin, stupin та loh10, знаходиться у файлі main.piton):

# Ініціалізація гетерогенного списку
values = [1, 4, 10, 25, 0.5, 100]
currentValue = 0

# Головна функція програми
functia main():
    drukuvaty "\n--- Piton Showcase ---"
    i = 0
    
    # Цикл poky (поки)
    poky i < dovzhyna(values):
        currentValue = values[i]
        drukuvaty "\nЧисло:"
        drukuvaty currentValue
        
        # Математичні вбудовані функції
        drukuvaty "    Корінь:"
        drukuvaty korin currentValue
        
        # Умова yaksho (якщо) та inackshe (інакше)
        yaksho currentValue > 0:
            drukuvaty "    Kosynus:"
            drukuvaty kosynus currentValue
        inackshe:
            drukuvaty "    Kosynus: вимагає додаткових даних"
            
        drukuvaty "    Класифікація:"
        drukuvaty klasify()
        
        i = i + 1

# Допоміжна функція
functia klasify():
    yaksho currentValue > 50:
        vernuty "Надвелике"
    inackshe yaksho currentValue > 10:
        vernuty "Велике"
    inackshe:
        vernuty "Компактне"

main()

🧮 Порівняння та логіка

Piton тепер має повний набір базових порівнянь: >, <, >=, <=, == та !=. Кожен із них працює над числовими значеннями (float64) і повертає булевий результат, який можна використати у yaksho, poky, functia або будь-якому іншому логічному виразі.

Для комбінування умов застосовуйте ta (логічне «і») або abo (логічне «або»), а ne інвертує вираз, що йде після нього. Наприклад:

a = 5
b = 10

yaksho (a <= b) ta ne (a == 0):
    drukuvaty "a не більше за b і не дорівнює нулю"
inackshe yaksho a > b:
    drukuvaty "Числа не в тому порядку"

a = true
drukuvaty ne a
# false

ta/abo очікують булеві значення з обох сторін і видають повідомлення про тип, якщо отримують щось інше. ne працює як префіксний оператор заперечення: ne true = false

✅ Легкий приклад

Щоб швидко побачити Piton у дії, запустіть короткий трекер сесій: examples/session-tracker.piton покроково показує списки, цикли poky, умовні yaksho/inackshe, виклики functia і вбудовані математичні оператори (abs, korin, stupin, dovzhyna). Запуск:

./piton examples/session-tracker.piton

🎨 Стилізований друк

drukuvaty тепер підкреслює рядковий вивід, ви можете вказати кольори вручну через функцію kolor(colorName, value). Вона повертає успадкований рядок, загорнутий в ANSI-коди, тож можна візуалізувати kolor("red", "Увага!") або навіть drukuvaty kolor("bright_cyan", 1+2). Доступні імена кольорів: black, red, green, yellow, blue, magenta, cyan, white, bright_black, bright_red, bright_green, bright_yellow, bright_blue, bright_magenta, bright_cyan, bright_white.

🧮 Демонстрація dodaty

dodaty - власна утиліта Piton для безпечного нарощування списків: вона або зливає два списки, або додає один елемент до наявного масиву, не змінюючи оригінал. Щоб побачити приклади різних викликів, запустіть:

./piton examples/spysok-demo.piton

Скрипт друкує початковий список, результат додавання інших списків та результат, до якого додається тільки один елемент, даючи змогу зосередитися саме на поведінці dodaty.

Для розширеного прикладу, де демонструються зрізи на зразок list[i:] і "go-way" видалення, запустіть:

./piton examples/dodaty-demo.piton

Також оператор + у Piton поводиться як у скриптових мовах: якщо один із доданків - рядок, другий приводиться до рядка (у тому числі bool або число), так що "hello" + 2 дає "hello2".

📏 Слайси списків

Piton підтримує зрізи списків на кшталт Go (s[start:end], s[:end], s[start:], s[:]). Ви отримуєте новий список, тому можна безпечно працювати з підмножинами елементів і не турбуватися про зміну оригінального масиву.

Для видалення елементів варто скористатися "go-way": спочатку витягнути підсписок до індексу, а потім - після нього, і з'єднати результати через dodaty. Наприклад:

s = [1, 2, 3, 4]
trimmed = dodaty(s[:2], s[3:])
drukuvaty trimmed  # виведе [1, 2, 4]

🪧 Демонстрація slovnyk

slovnyk у Piton задається літералом через {} з рядковими ключами, працює з доступом через m["key"], підтримує оновлення значень, видалення ключів через delete(m, "key") і вкладені структури на кшталт списків та інших словників. Також dovzhyna() повертає кількість полів у словнику.

Готовий приклад є в examples/slovnyk-demo.piton:

./piton examples/slovnyk-demo.piton

Скрипт показує створення профілю користувача, читання окремих полів, оновлення ключів, додавання нового поля, видалення ключа та зміну вкладеного значення в nalashtuvannya.

🎲 Демонстрація vypadkovo

vypadkovo працює з діапазонами або списками: з 1 аргументом повертає випадкове число від 0 до вказаного значення, із двома - у проміжку [min, max), а зі списком - один із елементів. Є готовий приклад, де скрипт вибирає фрукт, число до 5 та значення з діапазону 10..15:

./piton examples/vypadkovo-demo.piton

📂 Імпорти через vykorystaty

vykorystaty дозволяє імпортувати інші модулі Piton. Можна передати або ідентифікатор (vykorystaty hello), або рядок у лапках (vykorystaty "../hello"), а шлях буде доповнено .piton; назви функцій з модуля автоматично експортуються у глобальний простір і їх можна викликати без префікса. Приклад:

vykorystaty "hello"
main.Hello("Світ")

Цей сценарій уже записано у import.piton, тож його можна запустити командою ./piton import.piton.

У examples/vykorystaty-demo.piton показано імпорт через модуль: файл examples/hello.piton експортує functia Hello(...), а сам скрипт викликає її як hello.Hello("world"). Запустіть ../piton vykorystaty-demo.piton, щоб переконатися, що іменовані модулі працюють саме так.

⏱️ Час і затримка

chas() повертає поточний час у секундах, zatrymka(seconds) ставить виконання на паузу, а zaokruhlennya(value, precision) округлює дробове число до вказаної точності. Щоб побачити все в дії, запустіть:

./piton examples/chas-demo.piton

📦 Використання як Go-бібліотеки

Piton спроєктовано як модульний інструмент. Ядро інтерпретатора та візуалізатора можна легко інтегрувати у ваші Go-застосунки для виконання користувацьких скриптів чи малювання алгоритмів.

package main

import (
   "fmt"
   "os"
   "github.com/OlexiyOdarchuk/piton/interpreter"
)

func main() {
   code := `
x = 10
y = 20
drukuvaty x + y
`

   // 1. Виконання коду Piton
   err := interpreter.Run(code, os.Stdout)
   if err != nil {
      fmt.Println("Помилка виконання:", err)
   }

   // 2. Генерація блок-схеми з коду
   images, err := interpreter.Visualize(code, "", false)
   if err == nil {
      for filename, svgData := range images {
         os.WriteFile(filename, svgData, 0644)
         fmt.Println("Збережено схему:", filename)
      }
   }
}

🚀 Встановлення та CLI

Швидке встановлення (Релізи)

Найпростіший спосіб почати - завантажити вже зібраний виконуваний файл для вашої операційної системи. Завдяки налаштованій автоматичній збірці (CI/CD через GitHub Actions), ви можете просто:

1. Перейти на сторінку Releases.
2. Завантажити архів або бінарний файл під вашу ОС (Linux, macOS, Windows).
3. Розпакувати й одразу користуватися!

Збірка з вихідного коду

Якщо ж ви хочете зібрати інтерпретатор самостійно (маючи встановлений Go):

1. Клонуйте репозиторій:

   git clone https://github.com/OlexiyOdarchuk/piton.git
   cd piton

2. Зберіть виконуваний файл:

   go build -o piton ./cmd/piton

❄️ Nix Ecosystem & Reproducibility

Проєкт Piton повністю підтримує екосистему Nix. Це означає, що вам не потрібно турбуватися про версії Go, змінні оточення або залежності. Nix створює ідентичне середовище як на вашому ПК, так і на CI-сервері.

Швидкий старт через Flakes

Якщо у вас встановлено Nix, ви можете використовувати Piton без клонування репозиторію:

• Спробувати REPL: nix run github:OlexiyOdarchuk/piton
• Виконати скрипт: nix run github:OlexiyOdarchuk/piton main.piton
• Відмілювати блок-схему: nix run github:OlexiyOdarchuk/piton -- --draw main.piton

Для контріб'юторів (Nix Develop)

Забудьте про go install. Просто введіть:

nix develop

Ви отримаєте ізольовану оболонку, де вже встановлено:

• Go (актуальної версії)
• gopls (для роботи вашої IDE)
• nixfmt (для форматування конфігів)
• mdbook (для роботи з документацією)

Локальна збірка

Щоб зібрати проєкт через Nix (результат буде в ./result/bin/piton):

nix build

Запуск та Інтерактивний режим

• Запуск скрипта: ./piton main.piton
• Генерація блок-схем: ./piton -draw main.piton
• REPL (Інтерактивна консоль): Просто запустіть ./piton без аргументів. Консоль підтримує багаторядкові блоки, підказує промпти >>>/... і працює в режимі реального часу.

🗺️ Road Map / Що далі? (TODO)

Проєкт Piton розвивається. На черзі впровадження функціоналу для перетворення інтерпретатора на повноцінне середовище розробки:

• ⚡ REPL (Interactive Shell): Створення інтерактивної консолі для виконання коду в реальному часі.
• 🏗️ Генератор блок-схем Реалізація нативного генератора блок-схем для кожного рядка коду Piton.
• 📊 Динамічні списки: Реалізація вбудованої функції dodaty(spysok, element) для маніпуляції даними на льоту.
• 🎲 Модуль рандомізації: Функція vypadkovo(min, max) для розробки ігрових механік та симуляцій.
• ⏱️ Аналіз продуктивності: Впровадження функції chas(), щоб вимірювати швидкість виконання алгоритмів (бенчмаркинг).
• 📂 Робота з файловою системою: Підтримка функцій для зчитування файлів та імпорту сторонніх модулів через vykorystaty.
• 🎨 ANSI Styling: Покращення виводу drukuvaty підтримкою поєднання та множення рядків.
• 🪧 HashMap Реалізація стуктури даних "Хешмапа" (slovnyk), щоб оперувати даними як з map[] в Go або dict в Python
• 📃 Документація: Написати повноцінну документацію для мови, аби її можна було зрозуміти без перегляду коду
• ❄️ Flake for Nix: Додати flake.nix для користувачів nix та NixOS, щоб зручно встановлювати Piton працювати в проєкті через nix develop
• 🧱 Структури: Додати можливість писати та реалізовувати власні структури як в Go або як класи в Python
• 📂 Робота з файловою системою: Додати можливість роботи з файловою системою. Читання і запис файлів
• ⬇️ Інсталятор: Додати NSIS інсталятор для Windows, щоб Piton автоматично встановлювався на систему. Додати пакет в AUR і зробити .deb і AppImage пакети

📄 Ліцензія

MIT License

---

📝 Проєкт створено в рамках дослідження впливу академічної комунікації на розвиток системного програмного забезпечення.