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 is a programming language created by Toby Paradise as a passion project. It combines the familiar curly-brace syntax of C-family languages with static type hints and an interpreter written entirely in Python. Whether you want to explore language internals, experiment with a clean scripting syntax, or study how interpreters are built, Hades offers a focused and readable foundation.

​
What Is Hades?

Hades is an interpreted, statically-typed language with C-style syntax. Source files use the .hds (primary) or .hd (alternate) extension and are executed by passing them directly to the Python-based runtime: 
python3 main.py my_program.hds
Every variable declaration carries an explicit type hint, functions declare their parameter and return types, and the interpreter enforces these contracts at runtime — catching type mismatches before they silently corrupt values.
Hades is a passion project and an evolving language. Some advanced features (such as classes and structs) are defined in the grammar but may be partially implemented in the current interpreter.

​
Key Language Features

​
Type System

Hades variables must be declared with a type hint. The following primitive and complex types are supported:
Type hintDescriptionExample literal
intInteger number42
floatFloating-point number3.14
boolBoolean valueTRUE, FALSE
strString'hello'
listMutable ordered sequence[1, 2, 3]
nothingAbsence of a value (like null)(no initializer needed)
Variables must be declared and initialized in the same statement, with the exception of nothing: 
name: str = 'Alice';
score: int = 100;
ratio: float = 0.95;
active: bool = TRUE;
placeholder: nothing;

​
Functions and Closures

Functions are declared with the func keyword, typed parameter list, and a => ReturnType annotation. The => symbol is also used as the return statement inside the body: 
func greet(name: str) => str {
    => 'Hello, ' + name
}

print(greet('World'))
Functions capture their surrounding scope as a closure, meaning inner functions can read variables declared in outer scopes even after those outer scopes have finished executing.

​
Classes

Classes act as constructors or templates for objects. They support three kinds of members:
  • creator — an initializer method called automatically when an instance is created (named identically to the class).
  • method — a regular instance method.
  • operator — overloads a built-in operator for instances of the class.
Inside a class, my. is used to reference instance variables and methods (similar to this or self in other languages): 
Student: class {
    creator Student(me, name: str, age: int) => nothing {
        my.name: str = name;
        my.age: int = age
    };

    method AgeUp(me) => nothing {
        my.age++
    };

    operator !(me) => bool {
        => !my.name || !my.age
    }
};

Alice: Student = Student{'Alice', 20};
Alice.AgeUp();
print(Alice.age)
Class and struct syntax is defined in the Hades grammar and AST, but interpreter execution of class and struct definitions is not yet wired up. Running class or struct code will raise a runtime error until this support is completed.

​
Structs

Structs aggregate multiple named fields of potentially different types into a single value. They are defined as a template and instantiated separately, either positionally or by name: 
Point: struct = {
    x: float;
    y: float
};

origin: struct<Point> = {0.0, 0.0};
named:  struct<Point> = { x = 1.5, y = 2.0 };

​
Lists and Records

Hades provides two sequence types:
  • list — a mutable sequence accessed with the -> index operator (scores->0). The list type hint is fully implemented.
  • record — an immutable sequence defined with double-quoted comma-separated values ("a, b, c"), accessed with record"index". Attempting to mutate a record raises a TypeError. Records are described in the language grammar but do not yet have a type-hint token in the interpreter; record syntax is planned for a future release.
scores: list = [95, 87, 92];
first: int = scores->0;

​
Control Flow

Hades supports a full suite of control flow constructs:
ConstructSyntax
Conditionalif (cond) { } else if (cond) { } else { }
While loopwhile (cond) { }
Do-while loopdo { } while (cond);
C-style for loopfor (i: int = 0; i < n; i++) { }
For-in loopfor (x: int; x in list) { }
The grammar also documents break (exit a loop), next (skip to the next iteration), and _goTo label (jump to a named label), but these keywords are not yet tokenised or handled by the interpreter — they are planned for a future release.

​
Built-in Functions

The interpreter ships with three built-in functions:
FunctionSignatureDescription
printprint(a, b, ...)Prints all arguments concatenated with no separator
typetype(value)Returns the Hades type name of a value as a string
lenlen(value)Returns the length of a str or list
greeting: str = 'Hello';
print(type(greeting))   // str
print(len(greeting))    // 5

​
The Interpreter Pipeline

Every .hds file passes through three stages before any output is produced:
1

Lexer

The Lexer (modules/lexer.py) reads raw source text character-by-character and produces a flat list of typed Token objects — keywords, identifiers, literals, operators, and punctuation.
2

Parser

The Parser (modules/parser.py) consumes the token stream and builds an Abstract Syntax Tree (AST) composed of typed node objects (e.g. VarDeclNode, FuncNode, IfNode). Structural errors such as mismatched brackets or missing semicolons are raised here as SyntaxError.
3

Interpreter

The Interpreter (modules/interpreter.py) walks the AST node-by-node, evaluating expressions and executing statements. It maintains a chain of Scope objects to handle variables and closures. Type-hint enforcement and runtime errors (InterpreterError) are handled at this stage.
Pass the -v / --verbose flag to print the raw token list and AST between the parse and interpret stages — useful for debugging or learning how the pipeline works: 
python3 main.py my_program.hds -v

​
VS Code Extension

The repository includes a VS Code extension in the hades-language/ directory (publisher: tobyp, display name: Hades Language Support). It provides syntax highlighting for .hds and .hd files. See the Installation guide for instructions on installing it as a local extension.

​
Where to Go Next

Quickstart

Write and run your first Hades program in minutes.

Variables & Types

Deep dive into type hints, declarations, and truthiness rules.

Functions

Learn closures, return types, and function definitions.

Built-in Reference

Complete reference for print, type, and len.

Build docs developers (and LLMs) love

Get started for freeTalk to us