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.

Hades programs are executed by passing a source file to main.py through the Python interpreter. The runner resolves file extensions automatically, surfaces helpful formatted errors when something goes wrong, and offers a verbose mode that prints the full token list and parse tree — useful when you want to understand exactly how the interpreter sees your code.

​
Basic Usage

python3 main.py <file.hds> [-v|--verbose]
For a simple “hello world” program saved as hello.hds: 
greeting: str = 'Hello, World!';
print(greeting);
Run it with: 
python3 main.py hello.hds

Hello, World!

​
File Extension Resolution

You do not always need to type the full filename. The runner applies the following resolution rules in order:
  1. No extension supplied — .hds is appended automatically.
    python3 main.py hello → looks for hello.hds
  2. .hds not found, .hd exists — falls back to the .hd variant automatically.
    python3 main.py hello → tries hello.hds, then hello.hd
  3. Unexpected extension supplied — the file is still run, but a warning is printed to let you know the extension is non-standard.
Both .hds (Hades Script) and .hd (Hades) are valid Hades file extensions. The VS Code extension recognises both. Prefer .hds for new files.

​
Verbose Mode

Passing -v or --verbose as the second argument instructs the runner to print the complete token list and AST (Abstract Syntax Tree) to standard output before executing the program. This is invaluable for debugging parser behaviour or understanding how an expression is parsed. 
python3 main.py hello.hds --verbose
# or
python3 main.py hello.hds -v
Given the following source file: 
x: int = 10;
y: int = x + 5;
print(y);
Verbose output looks like this (abbreviated for clarity): 
[Token(TT.INT_TYPE_HINT, 'int', 0:1), Token(TT.ID, 'x', 0:5), Token(TT.COLON, ':', 0:6), ...]
ProgramNode([VarDeclNode('x': TT.INT_TYPE_HINT = NumberNode(10)), VarDeclNode('y': TT.INT_TYPE_HINT = BinOpNode(IdNode(x), TT.PLUS, NumberNode(5))), CallNode('print', args=[IdNode(y)])])
15
The program output (15) follows the debug dump.
Use verbose mode alongside a short test file when writing a new language feature or tracking down an unexpected parse — seeing the exact token sequence reveals ambiguities that are invisible at the source level.

​
Exit Codes

CodeMeaning
0Program ran successfully
1File not found
1Syntax error (lexer or parser)
1Runtime error (interpreter)
All error messages are printed to standard output with source location and a red caret pointer before the process exits. See the Error Messages page for full details on the error format.

​
Quick Reference

python3 main.py program.hds

​
Common Mistakes

The verbose flag must be the second argument, immediately after the filename. Placing it first (python3 main.py -v program.hds) will cause the runner to treat -v as the filename and fail with a file-not-found error.

Build docs developers (and LLMs) love

Get started for freeTalk to us