Start Here
This page introduces UniversalToolchain and the Wist reference language, explains the practical reason the project exists, and helps you choose your route through the documentation.
When to read this page
Read this page if you have just discovered the repository and want to understand the project before going deep into implementation details.
Goal
Understand what UniversalToolchain is, what Wist is, when the project is useful, and where to start.
Project overview
- UniversalToolchain is a Wist-first modular .NET framework for building embeddable DSL runtimes. It provides infrastructure for lexing, parsing, abstract syntax trees (AST), bytecode/AIR layers, optimizers and execution backends.
- Wist is the reference language built on top of UniversalToolchain. It demonstrates how to assemble modules into a usable language and provides CLI and programmatic entry points.
- Modules are reusable language features. They can contribute lexer, parser, AST translation, bytecode and IR behavior.
- Dialects select modules, backends and optimizations. They describe a chosen language/runtime surface instead of hardcoding one compiler profile.
Use it when
- you want configurable formulas or restricted business rules inside a .NET application;
- you need language features to be selectable and testable as modules;
- you want a reference language that demonstrates a modular compiler/runtime pipeline;
- you need to compare interpreter and compiled execution paths for the same language surface.
Do not treat it as
- a hardened sandbox for untrusted code;
- a drop-in replacement for C# scripting;
- a mature general-purpose language workbench;
- a simple expression evaluator with no compiler/runtime concepts.
For the current maturity boundaries, read Current Limitations.
Identify your route
| User type | What to read first | Then read |
|---|---|---|
| Wist user (run programs, learn syntax) | First Program, CLI Reference | Syntax Tour, Examples |
| DSL developer (compose your own language) | Mental Model, Dialect Files | Minimal DSL, Embedding in .NET |
| Module author (add new language features) | Write Modules | Module Contracts, Testing a Module |
| Runtime/compiler engineer | Pipeline | Bytecode, AIR, Backends |
| Contributor/maintainer | Internals | Project Rules, Documentation Rules |
| Reference user | Reference | Backend Contracts, Module Reference |
Recommended order
- First Program
- CLI Reference
- Mental Model
- Syntax Tour
- Dialect Files
- Minimal DSL
- Embedding in .NET
- Write Modules
- Pipeline overview
- Reference
Next
Continue with First Program to run your first Wist expression.