CDTk 6.0.0

CDTk - Compiler Description Toolkit

CDTk is a .NET library for building compilers, transpilers, and code generators. It provides a clean, unified API that makes language creation simple and intuitive.

Why CDTk?

Traditional compiler construction requires managing separate lexers, parsers, and code generators. CDTk unifies these components into a single, coherent workflow:

1. Define tokens - Describe what words your language recognizes
2. Define rules - Specify how those words combine into valid programs
3. Define mappings - Transform parsed programs into output code
4. Compile - One simple method call to process everything

Hello, Compiler!

Here's a complete compiler in just a few lines:

using CDTk;

// Define tokens
var tokens = new TokenSet
{
    new Token("Number", @"\d+"),
    new Token("Identifier", @"\w+"),
    new Token("Equals", @"="),
    new Token("WS", @"\s+").Ignore()
};

// Define grammar rules
var rules = new RuleSet
{
    new Rule("Assignment", "@Identifier '=' @Number")
        .Returns("AssignmentNode", "variable", "value")
};

// Define code generation
var mapping = new MapSet
{
    new Map("AssignmentNode", "let {variable} = {value};")
};

// Build the compiler
var compiler = new Compiler()
    .WithTokens(tokens)
    .WithRules(rules)
    .WithTarget(mapping)
    .Build();

// Compile code
var result = compiler.Compile("x = 42");

if (result.Success)
{
    Console.WriteLine(result.Output);  // Output: let x = 42;
}

How It Works

TokenSet → Define Your Vocabulary

TokenSet defines what text patterns your language recognizes. Each Token has a name and a regex pattern:

var tokens = new TokenSet
{
    new Token("Keyword", @"if|while|return"),
    new Token("Number", @"\d+"),
    new Token("WS", @"\s+").Ignore()  // Whitespace is ignored
};

RuleSet → Define Your Grammar

RuleSet specifies how tokens combine to form valid programs. Rules reference tokens with @TokenName:

var rules = new RuleSet
{
    new Rule("Statement", "@Keyword '(' Expression ')'")
        .Returns("StatementNode", "keyword", "expr")
};

MapSet → Generate Output

MapSet transforms your parsed program into the target language.

Naming Recommendation: Name your MapSet variable after the target language it generates:

var C = new MapSet
{
    new Map("StatementNode", "{keyword}({expr});")
};

var Ruby = new MapSet
{
    new Map("StatementNode", "{keyword}({expr})")
};

This naming convention makes your code more readable and enables natural multi-target compilation.

Compiler → One Entry Point

The Compiler orchestrates everything automatically.

Naming Recommendation: Name your compiler instance after your source language:

var Python = new Compiler()
    .WithTokens(tokens)
    .WithRules(rules)
    .WithTarget(C)
    .Build();

var result = Python.Compile(sourceCode);

This reads naturally: "Python compiles to C"

Multi-Target Compilation

Compile to multiple targets in a single pass:

var Python = new Compiler()
    .WithTokens(tokens)
    .WithRules(rules)
    .WithTargets(("C", C), ("Ruby", Ruby), ("Wasm", Wasm))
    .Build();

var result = Python.Compile(sourceCode);

// Access each output
Console.WriteLine(result.Outputs["C"]);
Console.WriteLine(result.Outputs["Ruby"]);
Console.WriteLine(result.Outputs["Wasm"]);

The compiler parses input once and applies each MapSet to generate multiple outputs.

Getting Started

1. Install - Add CDTk to your .NET project
2. Learn - Read the complete guide in Learn.md
3. Explore - Check out examples in Examples.md
4. Ask - Common questions answered in FAQ.md

Documentation

• Learn.md - Complete guided walkthrough
• Examples.md - Sample compilers and languages
• FAQ.md - Common questions and solutions
• Contributing.md - How to report issues and contribute

Quick Links

• Token Definition Guide
• Grammar Rules Guide
• Code Generation Guide
• Compiler API Reference
• Architecture Overview

License

See LICENSE.md for details.