ForthUkr

ForthUkr is a bilingual Forth interpreter and Qt 6 IDE: Ukrainian words and ANS Forth side by side, turtle graphics, a step debugger, and a built-in help browser.

ForthUkr — інтерпретатор Forth і графічне IDE на C++20 / Qt 6 (QML). Два синтаксиси паралельно: український і класичний ANS Forth. Є черепашача графіка, покроковий зневаджувач, довідка та автодоповнення.

Version 0.1.0. License: GNU GPL v3 or later (see LICENSE).

File words (write-file / записати_файл, delete-file, mkdir, include) can only touch the current working directory. The IDE uses an application workspace, not the source tree. Treat .fukr files like scripts: run only code you trust.

Можливості

Мова та інтерпретатор

• Двомовний синтаксис: кожне слово має український еквівалент і стандартну назву ANS Forth (копія / dup, скинути / drop, обміняти / swap, поверх / over, ротація / rot).
• Керуючі конструкції: якщо ... інакше ... тоді (if ... else ... then), цикли початок ... доки (begin ... until), початок ... поки ... повторити (begin ... while ... repeat), лічильні цикли до ... цикл (do ... loop), розгалуження вибір ... варіант ... кінець_вибору (case ... of ... endcase).
• Два стеки: стек даних та стек повернень (>r, r>, r@, 2>r, 2r>, 2r@), індекси циклів i, j, k (і, й, к).
• Числові типи: дійсні числа (long double), комплексні числа (3+4i, complex, re, im, conj).
• Рядки: літерали "..." з escape-послідовностями (\n, \t, \", \\), операції конкатенації, взяття підрядка, зміна регістру.
• Математична бібліотека: піднесення до степеня (^), квадратний корінь (sqrt), модуль (abs), тригонометрія (sin, cos, tan, atan2), ділення з залишком (mod, /mod).
• Масиви та пам'ять: адресна арифметика (cells, cell+, cell-), виділення пам'яті (allot, create), динамічне виділення в купі (allocate, free, resize), операції заповнення (fill, erase), дамп пам'яті (dump).
• Файловий ввід/вивід у межах робочої директорії: читання, запис і дописування, перевірка існування та розміру, імпорт через включити (include). Ліміти ітерацій, пам'яті, рекурсії та include задаються окремо (меню «Вигляд → Ліміти виконання...», значення 0 = без обмеження). Необроблена помилка в GUI зупиняє виконання, а не процес.

Середовище розробки (IDE)

• Редактор коду з підсвіткою синтаксису для українських та англійських слів Forth.
• Візуальний покроковий налагоджувач (Step Over F10, Run F5, Stop Shift+F5) з підсвіткою поточного токена та відстеженням стека.
• Жива панель інспекції стека даних та стека повернень.
• Автодоповнення слів за Ctrl+Space.
• Підсвітка парних ключових слів (якщо / тоді, до / цикл тощо).
• Полотно векторної графіки (Logo/Turtle) з координатною сіткою та маркером черепашки.
• Вбудована довідкова база з пошуком за назвою, категорією та сигнатурою стека.
• 170 прикладів програм у examples.json (українською та англійською).

Вимоги для збірки

• Компілятор C++ з підтримкою стандарту C++20 (GCC 11+, Clang 13+, MSVC 2022+).
• CMake 3.16 або новіший.
• Qt 6.5+ (Quick, QML, Core, Gui, Test).

Збірка

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Після збірки у директорії build з'являться виконувані файли:

• appforth_ukr — основний бінарник (графічний або консольний режим);
• forth_tests — набір автоматичних тестів.

Запуск

Графічний режим (IDE)

./build/appforth_ukr

Консольний режим (CLI)

Для виконання Forth-файлу з командного рядка передайте шлях до нього першим аргументом:

./build/appforth_ukr script.fukr

Тести

./build/forth_tests

або через CTest:

ctest --test-dir build --output-on-failure

Довідник команд

Операції зі стеком

Команда (UA)	Команда (EN)	Стек	Опис
копія	dup	( x -- x x )	Дублювати вершину стека
скинути	drop	( x -- )	Видалити вершину стека
обміняти	swap	( a b -- b a )	Поміняти місцями два верхні елементи
поверх	over	( a b -- a b a )	Скопіювати другий елемент на вершину
ротація	rot	( a b c -- b c a )	Циклічний зсув трьох верхніх елементів
висмикнути	nip	( a b -- b )	Видалити передостанній елемент
підсунути	tuck	( a b -- b a b )	Вставити копію вершини під другий елемент
2копія	2dup	( a b -- a b a b )	Дублювати пару верхніх елементів
2скинути	2drop	( a b -- )	Видалити пару верхніх елементів
2обміняти	2swap	( a b c d -- c d a b )	Поміняти місцями дві пари елементів
друк	.	( x -- )	Надрукувати число або значення з пробілом
друк_стеку	.s	( -- )	Вивести поточний вміст стека

Стек повернень

Команда (UA)	Команда (EN)	Стек	Опис
>р, в_r	>r	( x -- ) ( R: -- x )	Перемістити значення на стек повернень
р>, з_r	r>	( -- x ) ( R: x -- )	Забрати значення зі стека повернень
р@, переглянути_r	r@	( -- x ) ( R: x -- x )	Скопіювати вершину стека повернень
і	i	( -- n )	Поточний індекс внутрішнього циклу
й	j	( -- n )	Поточний індекс зовнішнього циклу

Керування виконанням

Синтаксис	Опис
умова якщо ... тоді	Умовне виконання (if ... then)
умова якщо ... інакше ... тоді	Галуження (if ... else ... then)
початок ... умова доки	Цикл з постумовою (begin ... until)
початок ... умова поки ... повторити	Цикл з передумовою (begin ... while ... repeat)
limit start до ... цикл	Цикл з лічильником (do ... loop)
limit start до ... step +цикл	Цикл з довільним кроком (+loop)
вийти_з_циклу	Достроковий вихід з лічильного циклу (leave)
вибір ... n варіант ... кінець_вибору	Конструкція вибору (case ... of ... endcase)

Пам'ять та масиви

Команда	Стек	Опис
змінна name	( -- )	Оголосити змінну (1 комірка)
константа name	( x -- )	Оголосити константу зі значенням з вершини стека
!	( val addr -- )	Записати значення за адресою
@	( addr -- val )	Зчитати значення за адресою
+!	( n addr -- )	Додати число до значення за адресою
створити name	( -- )	Створити заголовок слова з поточною адресою пам'яті
комірки (cells)	( n -- n )	Перерахунок кількості елементів у зміщення в комірках
виділити (allot)	( n -- )	Виділити n комірок у поточному буфері
виділити_пам'ять (allocate)	( u -- addr ior )	Динамічне виділення пам'яті в купі (ior=0 при успіху)
звільнити_пам'ять (free)	( addr -- ior )	Звільнення динамічно виділеної пам'яті
змінити_розмір (resize)	( addr u -- new-addr ior )	Зміна розміру виділеного блоку
дамп (dump)	( addr u -- )	Вивести дамп u комірок за вказаною адресою

Черепашача графіка

Команда (UA)	Команда (EN)	Стек	Опис
вперед	fd, forward	( dist -- )	Рух уперед на вказану відстань
назад	bk, backward	( dist -- )	Рух назад
вправо	rt, right	( angle -- )	Поворот за годинниковою стрілкою (градуси)
вліво	lt, left	( angle -- )	Поворот проти годинникової стрілки
підняти_перо	pu, penup	( -- )	Вимкнути малювання при русі
опустити_перо	pd, pendown	( -- )	Увімкнути малювання при русі
колір_пера	pencolor	( str -- )	Встановити колір пера (назва або hex)
товщина_пера	pensize	( w -- )	Встановити товщину лінії
коло	circle	( r -- )	Намалювати коло радіуса r навколо поточної точки
очистити_графіку	cs	( -- )	Очистити полотно
додому	home	( -- )	Повернути черепашку в центр координат

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

Обчислення факторіалу

: факторіал
  копія 1 < якщо
    скинути 1
  інакше
    1 обміняти
    початок
      копія >r
      *
      r> 1 -
      копія 1 <=
    доки
    скинути
  тоді
;

"5! = " друк 5 факторіал друк новий_рядок
"6! = " друк 6 факторіал друк новий_рядок

Масиви та адресна арифметика

\ Оголошення масиву: 1 комірка від 'змінна' + 4 додаткові через 'allot' = 5 комірок
змінна масив 4 комірки виділити

\ Запис елементів
100 масив 0 комірки + !
200 масив 1 комірки + !
300 масив 2 комірки + !

\ Читання елементів
"Елемент 0: " друк масив 0 комірки + @ друк новий_рядок
"Елемент 1: " друк масив 1 комірки + @ друк новий_рядок

\ Вивід вмісту
масив 5 дамп

Черепашача графіка (зірка)

очистити_графіку
2 товщина_пера
"gold" колір_пера

5 0 до
  120 вперед
  144 вправо
цикл

Структура проекту

• main.cpp — точка входу, перемикання між графічним та консольним режимами;
• Interpreter.h, Interpreter.cpp — інтерпретатор Forth: стек, словник, пам'ять, арифметика, виконання токенів;
• ForthVocabulary.h — спільний список слів для підсвітки;
• ForthHighlighter.h, ForthHighlighter.cpp — синтаксична підсвітка для QTextDocument;
• HelpDatabase.h, HelpDatabase.cpp — довідник слів, сигнатури, пошук та автодоповнення;
• Main.qml — графічний інтерфейс;
• examples.json — бібліотека прикладів для IDE і тестів;
• tests/TestForth.cpp — модульні тести інтерпретатора (QtTest);
• CMakeLists.txt — сценарій збірки CMake.

Гарячі клавіші

• Ctrl+R — виконати код;
• F10 — зробити один крок налагодження (Step Over);
• F5 — продовжити виконання у режимі налагодження;
• Shift+F5 — зупинити виконання або зневадження;
• Ctrl+Space — викликати вікно автодоповнення;
• Ctrl+L — очистити поле виводу;
• Ctrl+K — скинути стек;
• Ctrl+O — відкрити файл;
• Ctrl+S — зберегти файл;
• F1 — відкрити вікно повної довідки.

Ліцензія

GNU General Public License v3.0 or later

Copyright (C) 2026 Ihor Dolinskyi

ForthUkr uses Qt. Qt is a trademark of The Qt Company Ltd. and is available under LGPLv3, GPLv3, and commercial licenses. See Qt licensing.