ragul-lang 0.3.2

Ragul — an agglutinative programming language

Ragul

A pipeline scripting language where transformation is built into the syntax itself. Each word is a suffix chain — a left-to-right pipeline stacked onto a root value. Inspired by the structural principles of agglutinative grammar (Hungarian).

data-into  [7, 2, 15, 3, 9, 1, 12, 4]-it.
result-into  data-unique-sorted-5-above-it.
result-print-doing.
// [7, 9, 12, 15]

📖 Full documentation →

---

Install

pip install ragul-lang

Requires Python 3.11+.

To also enable AI-assisted error explanations:

pip install ragul-lang[ai]

What is this? When Ragul finds a type error in your code, this optional feature sends the error and the relevant source lines to Claude (an AI assistant by Anthropic) and prints a plain-English explanation of what went wrong and how to fix it.

This is completely optional and nothing is ever sent automatically. To activate it, set your own ANTHROPIC_API_KEY environment variable — a personal access token you create at console.anthropic.com. Ragul never stores or logs your key; it is sent directly to Anthropic's API only when a diagnostic fires. Without the key, the compiler works identically with no network calls whatsoever.

Or install from source:

git clone https://github.com/kory75/ragul.git
cd ragul
pip install -e ".[dev]"        # toolchain + dev tools
pip install -e ".[ai,dev]"     # + AI support

---

Quick Start

# Run a program
ragul run hello.ragul

# Type-check without running
ragul check hello.ragul

# Interactive REPL
ragul repl

# Start the LSP server (for editor integration)
ragul lsp

# Scaffold a new project
ragul new project myapp

Hungarian primary names (futtat, ellenőriz, repl, új) are also accepted.

---

Examples

Hello World

program-ours-effect
    greeting-into  "Hello, World!"-it.
    greeting-print-doing.

Arithmetic pipeline

program-ours-effect
    x-into  10-it.
    y-into  x-3-add-2-mul-it.   // (10 + 3) × 2 = 26
    y-print-doing.

Filter and sort a list

program-ours-effect
    data-into    [7, 2, 15, 3, 9, 1, 12, 4]-it.
    result-into  data-unique-sorted-5-above-it.
    result-print-doing.
// [7, 9, 12, 15]

Define and call a custom suffix

// Define -double as a reusable suffix
double-ours
    num-yours.
    num-num-add-it.

program-ours-effect
    x-into  7-it.
    y-into  x-double-it.    // 14
    y-print-doing.

Conditionals

classify-ours-if
    num-yours.
    num-100-above-if
        "large"-it.
    -else-if  num-50-above-if
        "medium"-it.
    -else
        "small"-it.

program-ours-effect
    category-into  75-classify-if-it.
    category-print-doing.
// medium

Loops

// Sum a list using fold
summer-ours-fold
    item-yours.
    total-yours.
    total-item-add-it.

program-ours-effect
    list-into    [1, 2, 3, 4, 5]-it.
    result-into  list-summer-fold-it  0-with.
    result-print-doing.
// 15

Date and time

program-ours-effect
    now-into   0-now-it.

    // Format with PHP-style codes
    iso-into   now-dateformat-it  "Y-m-d H:i:s"-with.
    long-into  now-dateformat-it  "l, F j, Y"-with.
    iso-print-doing.     // 2026-03-22 09:05:07
    long-print-doing.    // Sunday, March 22, 2026

    // Arithmetic
    nextweek-into  now-7-adddays-it.
    nw-into  nextweek-dateformat-it  "Y-m-d"-with.
    nw-print-doing.      // 2026-03-29

    // Parse a date string
    parsed-into  "2000-01-01"-parse-it  "Y-m-d"-with.
    yr-into      parsed-year-it.
    yr-print-doing.      // 2000

Error handling

program-ours-effect
    content-into  "data.txt"-filein-it-?.
    content-print-doing.
    -catch
        hiba-print-doing.

---

What's in v0.3.2

Feature	Status
Lexer with full alias normalisation	✅
Parser → Scope tree (indentation-based)	✅
Static type checker (E001–E009, W001)	✅
E006 scope leak detection	✅
E007 module resolution failure	✅
Interpreter — assignment, arithmetic, pipelines	✅
All loop kinds: -while, -until, -each, -fold	✅
Conditionals: -if / -else / -else-if	✅
Error propagation: -? and -catch	✅
Effect scopes (-ours-effect) + I/O channels	✅
true / false boolean aliases	✅
English I/O aliases: stdout, stdin, stderr, filein, fileout	✅
netin / netout channel stubs	✅
adatok module — JSON + CSV parse/emit, field access	✅
minta module — 5 regex suffixes (-match, -capture, -findall, -resub, -resplit)	✅
képernyő module — terminal I/O: -write, -clear, -cursor, -key, -render	✅
idő module — -sleep timing suffix	✅
dátum module — 15 date/time suffixes: PHP-style format, parse, arithmetic, timestamps	✅
lista extensions — -set, -repeat, -index	✅
szöveg extension — -chars (split string to character list)	✅
Stdlib: arithmetic, comparison, logical, string, list, math	✅
CLI: run, check, compile, repl, lsp, new	✅
ragul new project / ragul new module scaffolding	✅
Interactive REPL with persistent environment	✅
LSP server: diagnostics, hover, completion, go-to-def	✅
Agent architecture with Claude AI error analysis	✅
Character-mode game — Téglatörő / Brickbash (examples/games/)	✅
GitHub Actions CI (pytest + mypy on every push)	✅
Documentation site (GitHub Pages)	✅
Published on PyPI as ragul-lang	✅

---

Architecture

ragul/
├── model.py          # Word, Sentence, Scope, RagulType + alias table
├── lexer.py          # Tokeniser with alias normalisation at lex time
├── parser.py         # Two-pass: word construction + scope tree assembly
├── typechecker.py    # Static type checker, E001–E009, W001
├── interpreter.py    # Tree-walking interpreter
├── errors.py         # Structured error types and formatters
├── config.py         # ragul.config TOML loader
├── main.py           # CLI entry point
├── stdlib/
│   ├── core.py       # Arithmetic, comparison, logical, string concat
│   ├── modules.py    # matematika, szöveg, lista, adatok, minta modules
│   ├── screen.py     # képernyő — terminal I/O (5 suffixes)
│   ├── time.py       # idő — timing (-sleep)
│   └── datum.py      # dátum — date/time (15 suffixes)
├── agents/
│   ├── orchestrator.py   # Coordinates the pipeline; Claude AI error analysis
│   ├── task.py           # Task / TaskResult message protocol
│   └── ...               # LexerAgent, ParserAgent, TypeAgent, InterpAgent, ...
├── repl/
│   └── repl.py       # Interactive REPL
└── lsp/
    └── server.py     # pygls LSP server

---

Running Tests

pytest ragul/tests/ -v

With type checking:

python -m mypy ragul/ --ignore-missing-imports

---

Suffix Alias Quick Reference

Each suffix has a canonical Hungarian form plus English and symbolic aliases:

Role	Canonical	English	Symbol
Source (from)	-ból / -ből	-from	-<
Target (into)	-ba / -be	-into	->
Instrument (with)	-val / -vel	-with	-&
Object (acted on)	-t	-it	-*
Action (execute)	-va / -ve	-doing	-!
Error propagation	-e	-else-fail	-?

---

REPL

ragul repl

>>> x-into  3-it.
>>> y-into  x-double-it.
>>> y-print-doing.
6
>>> :show
x = 3  (Szám)
y = 6  (Szám)
>>> :exit

---

ragul.config

Place at your project root:

[projekt]
nev     = "my-project"
verzio  = "0.1.0"
belepes = "main.ragul"

[ellenorzes]
harmonia = "warn"   # "warn" | "strict" | "off"
tipus    = "warn"   # "warn" | "strict" | "off"

---

License

Apache 2.0 — see LICENSE for the full text.