tawla 0.1.0__tar.gz

tawla-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Haddaji
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tawla-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: tawla
+Version: 0.1.0
+Summary: The Tawla programming language and its tawlac compiler
+Author-email: Ahmed Haddaji <ahmedhaddajiahmed@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/HaddajiDev/tawla-lang
+Project-URL: Repository, https://github.com/HaddajiDev/tawla-lang
+Keywords: compiler,programming-language,llvm,tawla
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: llvmlite>=0.44
+Dynamic: license-file
+
+# Tawla
+
+Tawla is a small programming language with its own compiler, `tawlac`, built
+from scratch. It looks a lot like C#: you write classes with fields and methods,
+you get inheritance and interfaces, and everything is statically typed. Under the
+hood `tawlac` turns your code into real machine code using LLVM and runs it on
+the spot, so there's no separate "compile then run" dance.
+
+It started as a learning project to understand how compilers actually work, and
+it grew into a genuinely usable little language. Source files end in `.twl`.
+
+Here's the whole "hello world":
+
+```tawla
+class Main {
+    void main() {
+        print("Hello, Tawla!");
+    }
+}
+```
+
+```
+$ tawlac run hello.twl
+Hello, Tawla!
+```
+
+## Getting it running
+
+You need Python 3.11 or newer. The easiest way to install `tawlac` is with
+[pipx](https://pipx.pypa.io/), which puts it in its own isolated environment and
+on your PATH. It works the same on Windows, macOS, and Linux:
+
+```
+pipx install tawla
+```
+
+(That works once Tawla is published to PyPI. Until then, install from a clone of
+this repo: `pipx install .` from the project folder, or once it's pushed:
+`pipx install git+https://github.com/HaddajiDev/tawla-lang`.)
+
+Prefer plain pip, or just hacking on it from a checkout? That's fine too:
+
+```
+pip install llvmlite
+python -m tawla run examples/hello.twl
+```
+
+Either way you get the `tawlac` command (or `python -m tawla`) with a few
+subcommands:
+
+```
+tawlac run app.twl     # compile and run a file
+tawlac new myapp       # scaffold a new project (like cargo new)
+tawlac init            # scaffold one in the current folder
+tawlac run             # run the current project (reads Tawla.toml)
+tawlac version         # what version is this
+tawlac help            # or: tawlac help run
+```
+
+## What the language can do
+
+- **The basics:** `int`, `bool`, and `string`; arithmetic and comparisons;
+  `if`/`else`, `while`, and functions (recursion works fine).
+- **`var`:** skip the type and let it be inferred — `var x = 5;`.
+- **Classes:** fields, methods, constructors, `this`, and `new`. Objects live on
+  the heap.
+- **Inheritance:** `class Dog : Animal { ... }`, with method overriding and
+  `super(...)` to call the base constructor.
+- **Polymorphism:** methods are virtual, so the right one gets picked at runtime
+  based on the actual object type (this is done with vtables).
+- **Interfaces:** `interface Shape { int area(); }`, and any class can implement
+  it, even classes that share no common parent.
+- **Abstract classes:** mark a class `abstract` and leave some methods without a
+  body for subclasses to fill in.
+- **Generics:** `class Box<T> { ... }`, used as `Box<int>` or `Box<string>`.
+- **Strings:** literals with escapes, `s.length`, `==`, and `+` to join them.
+- **Arrays:** `new int[n]`, indexing with `a[i]` (bounds-checked, so you get a
+  clear error instead of a crash), and `a.length`.
+- **Comments:** `// like this`.
+- **Garbage collection:** you don't free memory by hand. Call `collect()` when
+  you want a cleanup pass; `__live()` tells you how many objects are still around.
+
+There's a runnable example for pretty much every feature in `examples/` — poke
+around in there to see how things look in practice.
+
+## How it works, roughly
+
+`tawlac` runs your code through the usual compiler stages:
+
+```
+source.twl -> lexer -> parser -> sema -> codegen -> LLVM -> JIT -> runs
+```
+
+- the **lexer** chops the text into tokens
+- the **parser** builds a tree out of those tokens
+- **sema** checks the types and catches mistakes before any code is generated
+- **codegen** turns the checked tree into LLVM instructions
+- LLVM compiles that to machine code and the **JIT** runs it immediately
+
+Each piece lives in its own file under `tawla/`, so it's not hard to follow if
+you want to read along.
+
+## Running the tests
+
+```
+./venv/Scripts/python -m pytest
+```
+
+There are around 200 tests. Programs that print output are checked by running
+`tawlac` as a separate process and looking at what it prints (this sidesteps a
+Windows quirk where output from JIT-compiled code is hard to capture in-process).
+
+## What's not done yet
+
+It's a real language, but it's still a young one. A few honest gaps:
+
+- `tawlac build` (making a standalone `.exe` *from your Tawla program*) isn't
+  done — for now everything runs through `tawlac run`.
+- Generics only cover classes, not standalone functions, and you can't nest them
+  like `Box<Box<int>>`.
+- Garbage collection has to be triggered with `collect()`; it doesn't kick in on
+  its own yet.
+- No file imports, modules, or a standard library to speak of.
+
+The full design and the step-by-step history of how it was built are in
+`docs/superpowers/specs/2026-05-29-tawla-language-design.md` if you're curious.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tawla-0.1.0/README.md

@@ -0,0 +1,130 @@
+# Tawla
+
+Tawla is a small programming language with its own compiler, `tawlac`, built
+from scratch. It looks a lot like C#: you write classes with fields and methods,
+you get inheritance and interfaces, and everything is statically typed. Under the
+hood `tawlac` turns your code into real machine code using LLVM and runs it on
+the spot, so there's no separate "compile then run" dance.
+
+It started as a learning project to understand how compilers actually work, and
+it grew into a genuinely usable little language. Source files end in `.twl`.
+
+Here's the whole "hello world":
+
+```tawla
+class Main {
+    void main() {
+        print("Hello, Tawla!");
+    }
+}
+```
+
+```
+$ tawlac run hello.twl
+Hello, Tawla!
+```
+
+## Getting it running
+
+You need Python 3.11 or newer. The easiest way to install `tawlac` is with
+[pipx](https://pipx.pypa.io/), which puts it in its own isolated environment and
+on your PATH. It works the same on Windows, macOS, and Linux:
+
+```
+pipx install tawla
+```
+
+(That works once Tawla is published to PyPI. Until then, install from a clone of
+this repo: `pipx install .` from the project folder, or once it's pushed:
+`pipx install git+https://github.com/HaddajiDev/tawla-lang`.)
+
+Prefer plain pip, or just hacking on it from a checkout? That's fine too:
+
+```
+pip install llvmlite
+python -m tawla run examples/hello.twl
+```
+
+Either way you get the `tawlac` command (or `python -m tawla`) with a few
+subcommands:
+
+```
+tawlac run app.twl     # compile and run a file
+tawlac new myapp       # scaffold a new project (like cargo new)
+tawlac init            # scaffold one in the current folder
+tawlac run             # run the current project (reads Tawla.toml)
+tawlac version         # what version is this
+tawlac help            # or: tawlac help run
+```
+
+## What the language can do
+
+- **The basics:** `int`, `bool`, and `string`; arithmetic and comparisons;
+  `if`/`else`, `while`, and functions (recursion works fine).
+- **`var`:** skip the type and let it be inferred — `var x = 5;`.
+- **Classes:** fields, methods, constructors, `this`, and `new`. Objects live on
+  the heap.
+- **Inheritance:** `class Dog : Animal { ... }`, with method overriding and
+  `super(...)` to call the base constructor.
+- **Polymorphism:** methods are virtual, so the right one gets picked at runtime
+  based on the actual object type (this is done with vtables).
+- **Interfaces:** `interface Shape { int area(); }`, and any class can implement
+  it, even classes that share no common parent.
+- **Abstract classes:** mark a class `abstract` and leave some methods without a
+  body for subclasses to fill in.
+- **Generics:** `class Box<T> { ... }`, used as `Box<int>` or `Box<string>`.
+- **Strings:** literals with escapes, `s.length`, `==`, and `+` to join them.
+- **Arrays:** `new int[n]`, indexing with `a[i]` (bounds-checked, so you get a
+  clear error instead of a crash), and `a.length`.
+- **Comments:** `// like this`.
+- **Garbage collection:** you don't free memory by hand. Call `collect()` when
+  you want a cleanup pass; `__live()` tells you how many objects are still around.
+
+There's a runnable example for pretty much every feature in `examples/` — poke
+around in there to see how things look in practice.
+
+## How it works, roughly
+
+`tawlac` runs your code through the usual compiler stages:
+
+```
+source.twl -> lexer -> parser -> sema -> codegen -> LLVM -> JIT -> runs
+```
+
+- the **lexer** chops the text into tokens
+- the **parser** builds a tree out of those tokens
+- **sema** checks the types and catches mistakes before any code is generated
+- **codegen** turns the checked tree into LLVM instructions
+- LLVM compiles that to machine code and the **JIT** runs it immediately
+
+Each piece lives in its own file under `tawla/`, so it's not hard to follow if
+you want to read along.
+
+## Running the tests
+
+```
+./venv/Scripts/python -m pytest
+```
+
+There are around 200 tests. Programs that print output are checked by running
+`tawlac` as a separate process and looking at what it prints (this sidesteps a
+Windows quirk where output from JIT-compiled code is hard to capture in-process).
+
+## What's not done yet
+
+It's a real language, but it's still a young one. A few honest gaps:
+
+- `tawlac build` (making a standalone `.exe` *from your Tawla program*) isn't
+  done — for now everything runs through `tawlac run`.
+- Generics only cover classes, not standalone functions, and you can't nest them
+  like `Box<Box<int>>`.
+- Garbage collection has to be triggered with `collect()`; it doesn't kick in on
+  its own yet.
+- No file imports, modules, or a standard library to speak of.
+
+The full design and the step-by-step history of how it was built are in
+`docs/superpowers/specs/2026-05-29-tawla-language-design.md` if you're curious.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tawla-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "tawla"
+version = "0.1.0"
+description = "The Tawla programming language and its tawlac compiler"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Ahmed Haddaji", email = "ahmedhaddajiahmed@gmail.com" }]
+dependencies = ["llvmlite>=0.44"]
+keywords = ["compiler", "programming-language", "llvm", "tawla"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Compilers",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/HaddajiDev/tawla-lang"
+Repository = "https://github.com/HaddajiDev/tawla-lang"
+
+[project.scripts]
+tawlac = "tawla.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+packages = ["tawla"]

tawla-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tawla-0.1.0/tawla/__init__.py

@@ -0,0 +1,3 @@
+"""Tawla — a little programming language and its compiler, `tawlac`."""
+
+__version__ = "0.1.0"

tawla-0.1.0/tawla/__main__.py

@@ -0,0 +1,8 @@
+"""Lets you run the CLI with `python -m tawla ...`."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

tawla-0.1.0/tawla/ast_nodes.py

@@ -0,0 +1,199 @@
+"""The AST node types — the little tree the parser builds and codegen walks over."""
+
+from dataclasses import dataclass, field
+
+
+class Expr:
+    """Parent of everything that's an expression (i.e. produces a value)."""
+
+
+class Stmt:
+    """Parent of everything that's a statement (i.e. does something)."""
+
+
+@dataclass
+class IntLiteral(Expr):
+    value: int
+
+
+@dataclass
+class BoolLiteral(Expr):
+    value: bool
+
+
+@dataclass
+class StringLiteral(Expr):
+    value: str
+
+
+@dataclass
+class Identifier(Expr):
+    name: str
+
+
+@dataclass
+class Call(Expr):
+    name: str
+    args: list[Expr]
+
+
+@dataclass
+class ThisExpr(Expr):
+    pass
+
+
+@dataclass
+class New(Expr):
+    class_name: str
+    args: list[Expr]
+
+
+@dataclass
+class NewArray(Expr):
+    elem_type: str
+    size: Expr
+
+
+@dataclass
+class Index(Expr):
+    arr: Expr
+    index: Expr
+
+
+@dataclass
+class FieldAccess(Expr):
+    obj: Expr
+    field: str
+
+
+@dataclass
+class MethodCall(Expr):
+    obj: Expr
+    method: str
+    args: list[Expr]
+
+
+@dataclass
+class UnaryOp(Expr):
+    op: str
+    operand: Expr
+
+
+@dataclass
+class BinaryOp(Expr):
+    op: str
+    left: Expr
+    right: Expr
+
+
+
+
+@dataclass
+class VarDecl(Stmt):
+    var_type: str
+    name: str
+    init: Expr
+
+
+@dataclass
+class Assign(Stmt):
+    target: Expr
+    value: Expr
+
+
+@dataclass
+class ExprStmt(Stmt):
+    expr: Expr
+
+
+@dataclass
+class PrintStmt(Stmt):
+    expr: Expr
+
+
+@dataclass
+class If(Stmt):
+    cond: Expr
+    then_body: list[Stmt]
+    else_body: list[Stmt] | None
+
+
+@dataclass
+class While(Stmt):
+    cond: Expr
+    body: list[Stmt]
+
+
+@dataclass
+class Return(Stmt):
+    value: Expr | None
+
+
+@dataclass
+class SuperCall(Stmt):
+    args: list[Expr]
+
+
+
+
+@dataclass
+class Param:
+    var_type: str
+    name: str
+
+
+@dataclass
+class FuncDecl:
+    ret_type: str
+    name: str
+    params: list[Param]
+    body: list[Stmt]
+
+
+
+
+@dataclass
+class FieldDecl:
+    var_type: str
+    name: str
+
+
+@dataclass
+class MethodDecl:
+    ret_type: str
+    name: str
+    params: list[Param]
+    body: list[Stmt]
+    is_abstract: bool = False
+
+
+@dataclass
+class MethodSig:
+    ret_type: str
+    name: str
+    params: list[Param]
+
+
+@dataclass
+class CtorDecl:
+    params: list[Param]
+    body: list[Stmt]
+
+
+@dataclass
+class ClassDecl:
+    name: str
+    fields: list[FieldDecl]
+    methods: list[MethodDecl]
+    ctor: CtorDecl | None
+    bases: list[str] = field(default_factory=list)
+    is_abstract: bool = False
+    type_params: list[str] = field(default_factory=list)
+    parent: str | None = None
+    interfaces: list[str] = field(default_factory=list)
+
+
+@dataclass
+class InterfaceDecl:
+    name: str
+    methods: list[MethodSig]

tawla-0.1.0/tawla/cli.py

@@ -0,0 +1,104 @@
+"""The `tawlac` command line — this is what runs when you type `tawlac ...`."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+from .compiler import run_source
+from .project import entry_path, find_manifest, scaffold
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="tawlac",
+        description="The Tawla compiler",
+        epilog="Run 'tawlac help <command>' for details on a command.",
+    )
+    parser.add_argument(
+        "-V", "--version", action="version", version=f"tawlac {__version__}",
+        help="show the tawlac version and exit",
+    )
+    sub = parser.add_subparsers(dest="command", metavar="<command>")
+
+    run_p = sub.add_parser("run", help="compile and run a .twl file or project (JIT)")
+    run_p.add_argument(
+        "file", nargs="?", type=Path,
+        help="a .twl file; omit to run the project in the current directory",
+    )
+
+    build_p = sub.add_parser("build", help="emit a native binary (not implemented yet)")
+    build_p.add_argument("file", nargs="?", type=Path, help="a .twl file")
+
+    new_p = sub.add_parser("new", help="create a new project in a new directory")
+    new_p.add_argument("name", help="project name (also the directory created)")
+
+    sub.add_parser("init", help="create a project in the current directory")
+    sub.add_parser("version", help="print the tawlac version")
+    help_p = sub.add_parser("help", help="show help for tawlac or a command")
+    help_p.add_argument("topic", nargs="?", help="a command to describe")
+
+    return parser, sub
+
+
+def main(argv=None) -> int:
+    parser, sub = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command in (None, "help"):
+        topic = getattr(args, "topic", None)
+        if topic and topic in sub.choices:
+            sub.choices[topic].print_help()
+        else:
+            parser.print_help()
+        return 0
+
+    if args.command == "version":
+        print(f"tawlac {__version__}")
+        return 0
+    if args.command == "run":
+        return _run(args.file)
+    if args.command == "build":
+        return _build()
+    if args.command == "new":
+        return _new(args.name)
+    if args.command == "init":
+        return _init()
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+def _build() -> int:
+    print(
+        "tawlac build isn't implemented yet. For now, run programs with "
+        "'tawlac run' (they're JIT-compiled and run in memory). Emitting a "
+        "standalone native binary is planned.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def _run(file: Path | None) -> int:
+    if file is not None:
+        src = file.read_text(encoding="utf-8")
+    else:
+        src = entry_path(find_manifest(Path.cwd())).read_text(encoding="utf-8")
+    return run_source(src)
+
+
+def _new(name: str) -> int:
+    root = Path(name)
+    scaffold(root, name)
+    print(f"Created project '{name}' (run it with: cd {name} && tawlac run)")
+    return 0
+
+
+def _init() -> int:
+    root = Path.cwd()
+    scaffold(root, root.name)
+    print("Initialized project in the current directory (run it with: tawlac run)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())