Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ToberlerOhn/hades/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets you writing real Hades code as fast as possible. By the end you will have run a hello world, declared typed variables, written a recursive function, indexed a list, and used verbose mode to inspect the interpreter pipeline. All you need is a cloned copy of the repository and Python 3.12+. If you haven’t done that yet, start with the Installation guide.
1

Write and run Hello World

Create a new file called hello.hds in the root of the cloned hades/ directory with the following content:
name: str = 'World';
print('Hello, ', name, '!')
Run it:
python3 main.py hello.hds
Expected output:
Hello, World!
A few things to notice right away:
  • Variables must be declared with a type hint — name: str — before being assigned.
  • print accepts any number of arguments and concatenates them with no separator.
  • Semicolons are required at the end of most statements, but are not required immediately before a closing } or after one.
You can omit the .hds extension when running a file. python3 main.py hello works identically — the runner will automatically append .hds when looking for the file.
2

Declare variables with types

Hades is statically typed: every variable carries an explicit type hint that the interpreter enforces. Create types_demo.hds:
age: int = 25;
height: float = 1.82;
active: bool = TRUE;
greeting: str = 'Hello';
empty: nothing;

print('Name type : ', type(greeting))
print('Age       : ', age)
print('Height    : ', height)
print('Active    : ', active)
print('Empty     : ', empty)
Run it:
python3 main.py types_demo.hds
Expected output:
Name type : str
Age       : 25
Height    : 1.82
Active    : TRUE
Empty     : nothing
nothing is the only type that does not require an initializer. All other types must be declared and initialized in the same statement. Booleans use the uppercase literals TRUE and FALSE.
The built-in type() function returns the Hades type name of any value as a string — handy for debugging. The nothing type prints as the string nothing and is the Hades equivalent of null or None.
3

Define and call a function

Functions in Hades use the func keyword, declare typed parameters, annotate the return type with =>, and use => as the return statement inside the body.The example below defines a classic recursive Fibonacci sequence and a factorial function (both adapted from testing.hds in the repository), then prints the first ten values of each:
func fibonacci(n: int) => int {
    if (n <= 1) {
        => n
    }
    => fibonacci(n-1) + fibonacci(n-2)
}

func factorial(n: int) => int {
    result: int = 1;
    for (i: int = 1; i <= n; i++) {
        result *= i
    }
    => result
}

for (i: int = 0; i < 10; i++) {
    print(i, ': fib=', fibonacci(i), '  fact=', factorial(i))
}
Save this as math_demo.hds and run it:
python3 main.py math_demo.hds
Expected output:
0: fib=0  fact=1
1: fib=1  fact=1
2: fib=1  fact=2
3: fib=2  fact=6
4: fib=3  fact=24
5: fib=5  fact=120
6: fib=8  fact=720
7: fib=13  fact=5040
8: fib=21  fact=40320
9: fib=34  fact=362880
Functions capture their enclosing scope as a closure. A function defined inside another function can read and use variables from the outer function even after that outer function has returned.
Key syntax points:
  • => before the return type in the signature: func name(params) => ReturnType { }
  • => as the return statement inside the body: => expression
  • The C-style for loop initializes a typed loop variable: for (i: int = 0; i < n; i++)
  • Compound assignment operators like *= work as expected.
4

Work with lists

Lists in Hades are mutable ordered sequences. They are created with square-bracket literals and elements are accessed using the -> index operator.Create lists_demo.hds:
scores: list = [95, 87, 92, 78];

first: int  = scores->0;
last: int   = scores->3;

print('All scores : ', scores->0, ', ', scores->1, ', ', scores->2, ', ', scores->3)
print('First score: ', first)
print('Last score : ', last)
print('Count      : ', len(scores))
Run it:
python3 main.py lists_demo.hds
Expected output:
All scores : 95, 87, 92, 78
First score: 95
Last score : 78
Count      : 4
List indices are zero-based. Accessing an index outside the list’s bounds raises a runtime error: List index N out of range (length M).
You can also iterate over a list with a for-in loop:
nums: list = [10, 20, 30];

for (n: int; n in nums) {
    print(n)
}
Use the built-in len() function to get the number of elements in a list (or characters in a string) without hardcoding bounds.
5

Explore verbose mode

Hades ships with a built-in debug flag that prints the token list and AST produced by the Lexer and Parser before execution begins. This is a great way to understand how your source is being interpreted.Run any file with -v or --verbose:
python3 main.py hello.hds -v
You will see output similar to the following before your program’s normal output:
[Token(STR_TYPE_HINT, 'str', 1, 8), Token(ASSIGN, '=', 1, 14), ...]
ProgramNode(statements=[VarDeclNode(...), CallNode(...)])
Hello, World!

python3 main.py my_program.hds -v
The verbose output has two sections:
SectionWhat it shows
Token listEvery Token object emitted by the Lexer — type, raw value, and line/column position
ASTThe full ProgramNode tree produced by the Parser — every node type and its children
Start with a tiny snippet (two or three lines) when exploring verbose output. A full program can produce hundreds of tokens and deeply nested AST nodes that are hard to read all at once.

​
What to Explore Next

You have now covered the core building blocks of Hades. Here are natural next steps:

Variables & Types

Learn the full type system, truthiness rules, and operator precedence.

Functions

Closures, typed parameters, return annotations, and recursion patterns.

Control Flow

While, do-while, for, for-in, break, next, and _goTo.

Built-in Reference

Full documentation for print, type, and len.

Build docs developers (and LLMs) love

Get started for freeTalk to us