README

Project Archived: Development Continues with PaskalCPP

This project is now archived and read-only. No further development, updates, or bug fixes are planned.

Over the past year, I've explored various approaches to language and compiler design, particularly my long-term vision of bringing Pascal-style programming and modern C/C++ interoperability together.

Each of these projects has been an important part of that journey, providing valuable experience, ideas, and lessons that have ultimately led to PaskalCPP.

Going forward, PaskalCPP will be my primary focus and long-term language development project. All future development efforts, new features, improvements, and innovations will be concentrated there.

🚀 Follow the Journey

PaskalCPP Programming Language

• GitHub: https://github.com/tinyBigGAMES/PaskalCPP
• Website: https://paskalcpp.org

This repository will remain available for historical reference and for anyone who may find its code, ideas, or approach useful.

The journey continues with PaskalCPP. I hope you'll join me!

© 2026-present tinyBigGAMES LLC

What is Metamorf?

Metamorf is a Turing complete programming language for building compilers. You describe a complete programming language in a .mor file, covering tokens, types, grammar rules, semantic analysis, and C++23 code generation. Metamorf reads that file and immediately uses it to compile source files to native Win64/Linux64 binaries via Zig/Clang.

Mor -l pascal.mor -s hello.pas -r

One file defines your language. One command compiles and runs your program.

Why Metamorf?

Most language definition tools (YACC, ANTLR, traditional BNF grammars) give you a declarative grammar and then punt to a host language for anything non-trivial. Metamorf is different. It is a complete, Turing complete language with variables, assignment, unbounded loops, conditionals, arithmetic, string operations, and user-defined routines with recursion, all first-class constructs alongside declarative grammar rules and token definitions.

No host language glue code. No build system integration. No escape hatch to C, Java, or Python. A single .mor file is a complete, portable, standalone language specification that produces native binaries.

What you get:

• Single-file language definitions covering the entire pipeline: lexer tokens, Pratt parser grammar, semantic analysis, and C++23 code generation
• Turing complete language with variables, loops, conditionals, recursion, and string operations as first-class constructs
• Pratt parser grammar rules with declarative prefix/infix/statement patterns and full imperative constructs for complex parsing
• IR builder code generation producing structured C++23 through typed builders
• Automatic C++ passthrough so your language can interoperate with C/C++ without any .mor configuration
• Modular imports for splitting large language definitions across multiple .mor files
• Native source-level debugger with PDB support and a built-in REPL for breakpoints, stepping, call stack inspection, and variable evaluation
• Native binary output for Win64 and Linux64 via Zig/Clang, with cross-compilation through WSL2

How It Works

Metamorf reads your .mor file, populates its internal dispatch tables (token definitions, grammar rules, semantic handlers, emitter handlers), then uses those tables to lex, parse, analyze, and generate C++ 23 from your source file. The generated C++ is compiled to a native binary via Zig/Clang.

  ?????????????????????????????????????????????     ????????????????????????????????????????????????     ????????????????????????????????????????????????????????????
  ??? mylang.mor  ????????????????????? .mor parser  ????????????????????? dispatch tables  ???
  ?????????????????????????????????????????????     ????????????????????????????????????????????????     ????????????????????????????????????????????????????????????
                                                    ???
  ?????????????????????????????????????????????????????????                               ???
  ??? myprogram.src   ???????????????                           ???
  ?????????????????????????????????????????????????????????   ???                           ???
                        ???                           ???
                  ?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
                  ??? lex ????????? parse ????????? analyze ????????? C++23 ???
                  ?????????????????????????????????????????????????????????????????????????????????????????????????????????????????????
                                     ???
                               ???????????????????????????????????????
                               ??? Zig/Clang ???
                               ???????????????????????????????????????
                                     ???
                             ???????????????????????????????????????????????????
                             ??? native binary ???
                             ???????????????????????????????????????????????????

See the Metamorf Manual for the complete guide: architecture, grammar rules, semantic analysis, code emission, type inference, worked examples, and a checklist for building a new language.

Bake a Standalone Compiler

Turn any .mor language definition into a standalone compiler executable. The baked exe embeds the pre-validated AST as a resource, so end users never need .mor files or Metamorf itself. The Zig/Clang toolchain is still required at compile time for native code generation.

Mor --bake pascal.mor -o mypascal.exe --product "MyPascal Compiler" --version 1.0.0

The result is a self-contained compiler with a stripped-down CLI:

mypascal -s hello.pas -r

Add custom branding with --company, --copyright, --icon, --url, and --description. See the Metamorf Manual for the full bake reference.

Getting Started

Download the Release

Always download the most recent release from GitHub Releases. The release archive contains everything you need: compiled binaries, the Zig/Clang toolchain, a source checkpoint matching the binaries, test files, and documentation. No separate toolchain download, no configuration.

1. Download the latest release archive
2. Extract it to any directory
3. Write a .mor language definition and a source file, then compile:

Mor -l mylang.mor -s hello.src

To build and run in one step:

Mor -l mylang.mor -s hello.src -r

To build and launch the interactive debugger:

Mor -l mylang.mor -s hello.src -d

To target Linux from Windows, install WSL2 with Ubuntu:

wsl --install -d Ubuntu

Release Contents

Each release ships the following:

Getting Source Between Releases

The repository contains the latest source code, which may include bug fixes made after the most recent official release. To use these fixes:

1. Clone or pull the latest source from the repository
2. Copy the updated src/ files into your release directory, overwriting the existing source checkpoint
3. Rebuild from source (see Building from Source)

git clone https://github.com/tinyBigGAMES/Metamorf.git

System Requirements

Building from Source

Each release includes the full source alongside the binaries.

1. Download the latest release from GitHub Releases and extract it
2. Open projects\Metamorf - Language Engineering Platform.groupproj in Delphi 12 or higher
3. Build the project group

The project group contains five sub-projects:

[!IMPORTANT] This repository is under active development. Language surfaces may change without notice. Each release aims to be stable and usable as we work toward v1.0. Follow the repo or join the Discord to track progress.

Language Server Protocol (LSP)

Metamorf includes a full LSP implementation that provides editor integration for any language defined with a .mor file. The out-of-process server (MorLSP.exe) supports completions, hover, go-to-definition, find references, document symbols, semantic tokens, folding ranges, inlay hints, rename, formatting, code actions, and signature help. See the Metamorf Manual for setup details and the full capabilities list.

C API

Metamorf.dll exposes the entire compilation pipeline as a flat, C-callable API using opaque handles and UTF-8 strings. Any language that can load a shared library (C, C++, C#, Python, Rust, Go, and others) can drive Metamorf programmatically. The API supports one-shot compilation, stepped pipeline control with grammar reuse, full AST traversal for building custom tools like formatters and linters, and custom emit handler registration. See the Metamorf Manual for the complete function reference.

Contributing

Metamorf is an open project. Whether you are fixing a bug, improving documentation, adding a new showcase language, or proposing a feature, contributions are welcome.

• Report bugs: Open an issue with a minimal reproduction. The smaller the example, the faster the fix.
• Suggest features: Describe the use case first. Features that emerge from real problems get traction fastest.
• Submit pull requests: Bug fixes, documentation improvements, new language examples, and well-scoped features are all welcome. Keep changes focused.

Join the Discord to discuss development, ask questions, and share what you are building.

Support the Project

Metamorf is built in the open. If it saves you time or sparks something useful:

• ⭐ Star the repo: it costs nothing and helps others find the project
• 🗣️ Spread the word: write a post, mention it in a community you are part of
• 💬 Join us on Discord: share what you are building and help shape what comes next
• 💖 Become a sponsor: sponsorship directly funds development and documentation
• 🦋 Follow on Bluesky: stay in the loop on releases and development

License

Metamorf is licensed under the Apache License 2.0. See LICENSE for details.

Apache 2.0 is a permissive open source license that lets you use, modify, and distribute Metamorf freely in both open source and commercial projects. You are not required to release your own source code. The license includes an explicit patent grant. Attribution is required; keep the copyright notice and license file in place.

Links

• metamorf.dev
• Discord
• Bluesky
• Facebook Group
• tinyBigGAMES

Metamorf™ - Define It. Compile It. Ship It.

Copyright © 2025-present tinyBigGAMES™ LLC
All Rights Reserved.