About TeapotLang
What is TeapotLang?
TeapotLang is an experimental statically typed programming language and compiler written in Python. It is a from-scratch compiler project designed to explore how programming languages are tokenised, parsed, represented as abstract syntax trees, semantically analysed, and eventually compiled.
The compiler currently includes a hand-written lexer, a recursive-descent parser, a dataclass-based abstract syntax tree, symbol-table construction, and an evolving semantic analysis pass.
TeapotLang is intentionally developed in visible stages. Implemented functionality is distinguished from functionality that is still being designed or built.
-
Language
A new statically typed
.tpprogramming language with a compiler written in Python - Compiler Python 3.10+ compiler with a hand-written lexer and recursive-descent parser
- Stage Alpha — lexer, parser, AST, and parts of semantic analysis implemented; code generation not yet available
-
Entry point
teapot file.tp --trace -
Memory modes
$MEM-GCor$MEM-MANUAL, declared once per source file - License GNU GPL v3.0-or-later
Compiler architecture
The TeapotLang compiler pipeline
TeapotLang processes source code through several compiler stages. The lexer, parser, and abstract syntax tree are implemented, semantic analysis is under active development, and code generation is planned.
Lexical Analysis
The lexer turns raw .tp source code into tokens,
including keywords, types, literals, operators, comments,
and the memory-management directive.
Parsing
A recursive-descent parser consumes the token stream and constructs the abstract syntax tree. It covers structs, enums, errors, operators, functions, default arguments, control flow, casts, arrays, and related expressions.
Abstract Syntax Tree
TeapotLang represents parsed programs using a dataclass-based abstract syntax tree. The AST provides the structured representation consumed by later compiler stages.
Semantic Analysis
Semantic analysis builds symbol information across scopes and performs declaration and scope-related checks. Type checking, broader scope resolution, and additional semantic rules are still being developed.
Code Generation
TeapotLang does not yet have a code-generation backend, runtime, or executable output. Code generation is planned as the next major compiler stage after semantic analysis.
Programming language syntax
TeapotLang syntax
TeapotLang uses explicit, period-terminated statements and type-first declarations. Mutability is represented directly in type names, while each source file declares its memory management mode.
$MEM-GC
pub sct Person {
cstr name.
csi32 age.
}
pub fc add(csi32 a, csi32 b = 5)!csi32 {
exit a + b.
}
fc classify(csi32 score)!cstr {
if (score >= 90) {
exit "excellent".
}
elif (score >= 60) {
exit "passing".
}
else {
exit "needs work".
}
}
// entry point
fc main()!void {
val csi32 total = add(37, 5).
val cstr result = classify(total).
val csi32 shown = total >> csi32.
}Interactive compiler
Explore the compiler
Run TeapotLang directly in your browser. The playground uses the TeapotLang compiler itself through Pyodide and WebAssembly, then exposes the compiler's token stream, abstract syntax tree, and symbol table.
Compile to inspect lexer output.
Compile to inspect parser output.
Static type system
TeapotLang type system
TeapotLang makes integer width, signedness, and mutability explicit. Mutability is encoded directly into the type name instead of being supplied as a separate modifier.
| Category | Mutable | Constant |
|---|---|---|
| Signed integers | msi8 · msi16 · msi32 · msi64 | csi8 · csi16 · csi32 · csi64 |
| Unsigned integers | mui8 · mui16 · mui32 · mui64 | cui8 · cui16 · cui32 · cui64 |
| Floating point | mf32 · mf64 | cf32 · cf64 |
| Text & character | mstr · mchar | cstr · cchar |
| Boolean | mbln | cbln |
| Arbitrary precision / decimal | maint · mdml | caint · cdml |
| Untyped return | void — no mutable or constant form | |
>>,
for example
total >> cstr.
Members are accessed with
::,
for example
student::grades.
Development status
TeapotLang development status
TeapotLang is an alpha-stage compiler project. The distinction between implemented, actively developed, and planned functionality is intentional.
- Works today Lexing, parsing, AST construction, symbol-table construction, duplicate declaration checks, and function parameter scoping
- Being built Type checking, broader scope resolution, and additional semantic rules
- Not started Code generation, an executable backend/runtime, and a standard library
TeapotLang is developed in the open, with source code, issues, contributions, and design discussion available through the project repository.
Contributions are welcome, particularly around compiler implementation and language-design questions. Read the contributing guide before submitting anything beyond a small fix.
View TeapotLang source code →Frequently asked questions
TeapotLang FAQ
What is TeapotLang?
TeapotLang is an experimental statically typed programming language and compiler written in Python. It is being developed as a from-scratch compiler project exploring programming language implementation.
What is TeapotLang written in?
The TeapotLang compiler is written in Python 3.10 or later. The project uses Python to implement the lexer, parser, abstract syntax tree, and compiler analysis components.
Is TeapotLang a compiled programming language?
TeapotLang is designed as a compiled programming language, but the compiler is currently in alpha development. Lexing, parsing, AST construction, and parts of semantic analysis are implemented, while code generation is still planned.
Does TeapotLang have a static type system?
Yes. TeapotLang uses explicit static types including signed and unsigned integers, floating-point types, strings, characters, booleans, and other numeric types. Mutability is represented directly in type names.
What compiler stages does TeapotLang have?
The current compiler architecture consists of lexical analysis, parsing, abstract syntax tree construction, semantic analysis, and planned code generation.
What programming language is the TeapotLang compiler written in?
The compiler is written in Python. The project requires Python 3.10 or later.
Where can I find the TeapotLang source code?
The TeapotLang source code is publicly available on GitHub. The repository contains the compiler implementation, tests, documentation, and project development history.