Skip to main content

​
What is Loretta?

Loretta is a comprehensive C# library for working with Lua code. It provides a complete toolkit for lexing, parsing, code analysis, transformation, and code generation for Lua and its dialects. Built on the foundations of Roslyn, Loretta gives you the same powerful code analysis capabilities for Lua that Roslyn provides for C#. Whether you’re building development tools, code analyzers, formatters, or transpilers for Lua, Loretta provides the building blocks you need.

​
Why use Loretta?

Loretta solves the challenge of working programmatically with Lua code in .NET applications. Instead of writing custom parsers or using regex patterns, you get a production-ready, battle-tested solution.

Comprehensive parsing

Full lexer and parser implementation following the official Lua grammar with extensions for popular dialects

Rich syntax trees

Immutable syntax trees with full fidelity including comments, whitespace, and trivia

Code transformation

Powerful rewriter API for transforming and generating Lua code programmatically

Error diagnostics

Detailed error reporting with line numbers, positions, and descriptive messages

​
Supported Lua versions

Loretta supports multiple Lua versions and dialects out of the box through configurable syntax presets:
  • Lua 5.1 - The classic version found in many embedded applications
  • Lua 5.2 - Added goto statements, empty statements, and hex escapes
  • Lua 5.3 - Introduced bitwise operators and integer types
  • Lua 5.4 - Added local variable attributes
  • LuaJIT 2.0 - High-performance JIT compiler with extended identifier rules
  • LuaJIT 2.1 - LuaJIT beta with binary numbers and Unicode escapes
  • GLua (Garry’s Mod Lua) - Supports C-style comments (//, /* */) and boolean operators (&&, ||, !=, !), plus continue keyword
  • Luau (Roblox Lua) - Supports compound assignment (+=, -=, etc.), type annotations, if expressions, and interpolated strings
  • FiveM - Lua 5.3 with hash string syntax support
You can also create custom syntax options by mixing and matching features from different versions.

​
Architecture overview

Loretta follows a layered architecture similar to Roslyn:

​
Lexer

The lexer (Loretta.CodeAnalysis.Lua.Syntax.InternalSyntax.Lexer) breaks source code into tokens. It handles all the syntactic details like string escapes, number formats, and comment styles based on your chosen LuaSyntaxOptions.

​
Parser

The parser (Loretta.CodeAnalysis.Lua.Syntax.InternalSyntax.LanguageParser) consumes tokens from the lexer and builds a syntax tree. It understands Lua’s grammar and produces a hierarchical representation of your code.

​
Syntax trees

Syntax trees (LuaSyntaxTree) are immutable, thread-safe representations of parsed code. Every node retains its exact position in the source, including all trivia (whitespace, comments). This enables:
  • Precise source location reporting
  • Full-fidelity code transformation
  • Rich tooling experiences

​
Nodes and tokens

  • Syntax nodes (LuaSyntaxNode) represent language constructs like statements and expressions
  • Syntax tokens (SyntaxToken) represent keywords, operators, identifiers, and literals
  • Trivia (SyntaxTrivia) represents comments, whitespace, and other non-semantic content

​
Visitors and rewriters

  • LuaSyntaxWalker - Visit and inspect syntax nodes
  • LuaSyntaxRewriter - Transform syntax trees by replacing nodes

​
Key features

​
Full-fidelity parsing

Loretta preserves everything in your source code - every space, comment, and formatting detail. This means you can parse code, transform it, and write it back without losing any information.

​
Configurable syntax support

Choose a preset like LuaSyntaxOptions.Lua53 or LuaSyntaxOptions.Luau, or build your own by enabling specific features. Loretta adapts to your exact Lua dialect.

​
Comprehensive diagnostics

Get detailed error messages with precise locations when parsing invalid code. Diagnostics include error codes, descriptions, and source spans.

​
Code generation

Generate Lua code programmatically using the SyntaxFactory API. Create any valid Lua construct through a fluent C# interface.

​
Get started

Ready to start working with Lua code in C#?

Quickstart

Parse your first Lua code in under 5 minutes

Installation

Add Loretta to your .NET project

​
Next steps

After getting started, explore these guides:
  • Core concepts - Understand syntax trees, nodes, and tokens in depth
  • Parsing guide - Learn about parse options and syntax presets
  • Transformation guide - Rewrite and transform Lua code
  • Code generation - Build Lua code programmatically
  • Diagnostics - Work with parse errors and warnings

​
Package information

Loretta is distributed as two NuGet packages:
  • Loretta.CodeAnalysis.Lua - The main package with stable APIs
  • Loretta.CodeAnalysis.Lua.Experimental - Experimental features that may change
Both packages target .NET 8.0 and .NET Standard 2.0, giving you broad compatibility across .NET platforms.

Build docs developers (and LLMs) love

Get started for freeTalk to us