repository·main·Indexed 41 days ago
https://github.com/lorettadevs/lorettaA Roslyn-based C# and (G)Lua toolkit for lexing, parsing, code analysis, transformation, and code generation. It supports various Lua dialects including Standard Lua (5.1-5.4), LuaJIT (2.0, 2.1), Luau (Roblox), Garry's Mod (GLua), and FiveM. Available via NuGet as Loretta.CodeAnalysis.Lua and Loretta.CodeAnalysis.Lua.Experimental, the latter providing experimental features like constant folding and a Lua minifier.
SourceText is a core abstraction in Loretta.CodeAnalysis.Text designed for efficient code representation.
Key Responsibilities:
TextLines.TextSpan to a LinePositionSpan for accurate error reporting.SourceText.GetTextChanges, or apply changes via SourceText.WithChanges.The LuaSyntaxRewriter is a fundamental building block for transforming syntax trees. It allows you to replace specific nodes in a tree without manually managing parent-child relationships. You implement a custom rewriter by inheriting from LuaSyntaxRewriter and overriding Visit methods for the specific node types you want to transform (e.g., VisitCompilationUnit or VisitFunctionCallExpression).
When a node is modified, you typically return the new node using methods like node.Update(...) or by returning a newly constructed node via SyntaxFactory.
class MyRewriter : LuaSyntaxRewriter
{
public override SyntaxNode? VisitSomeNode(SomeNodeSyntax node)
{
// Transform the node and return it
return node.Update(...);
}
}Trivia refers to extraneous syntax that does not impact parsing, such as whitespaces, line breaks, comments, and shebangs (#!). Trivia is attached to the preceding or following token:
You can manipulate trivia using GetTrailingTrivia() and WithTrailingTrivia(SyntaxTriviaList).
A LuaSyntaxWalker is a fundamental building block used to traverse a syntax tree recursively. By inheriting from LuaSyntaxWalker, you can override specific Visit... methods to perform actions when the walker encounters certain node types (e.g., VisitFunctionCallExpression).
Key implementation details:
SyntaxWalkerDepth.Node to limit traversal to nodes, ignoring everything below them.Visit method, you must call base.Visit[MethodName](node) if you want the walker to continue traversing the children of that node. Failing to do so will stop the traversal for that branch.internal class MyWalker : LuaSyntaxWalker
{
public MyWalker() : base(SyntaxWalkerDepth.Node) { }
public override void VisitFunctionCallExpression(FunctionCallExpressionSyntax node)
{
// Do something with the node
base.VisitFunctionCallExpression(node); // Crucial for continued traversal
}
}To perform semantic analysis like retrieving scopes or variables, you must first create a Script instance from your LuaSyntaxTrees.
Once a Script is created, you can:
Script.RootScope.Script.GetScope(SyntaxNode) or Script.FindScope(SyntaxNode, ScopeKind).Script.GetVariable(SyntaxNode).goto statements using Script.GetLabel(SyntaxNode) (works on GotoStatementSyntax or GotoLabelStatementSyntax).Loretta provides broad compatibility across several Lua environments and extensions:
// and /* */) and logical operators (&&, ||, !=, !).+=, -=, *=, /=, ^=, %=, ..=), if expressions (if a then b else c), and typed Lua syntax.127/0x7F (e.g., emojis).continue Keyword SupportLoretta allows configuring how the continue keyword is handled via different options:
continue support.continue is treated as a contextual keyword.continue is treated as a full-fledged keyword.Loretta is a toolkit for lexing, parsing, and analyzing Lua-based code. It supports a wide range of dialects including:
0x7F).+=, -=, etc.), if expressions, and typed Lua syntax.// and /* */) and specific operators (&&, ||, !=, !).Continue Keyword Support:
You can configure how the continue keyword is handled via options:
continue support.continue is treated as a contextual keyword.continue is treated as a full-fledged keyword.A Lua syntax node is considered eligible to be turned into a local variable if it is either:
IdentifierNameSyntax (e.g., print).MemberAccessExpressionSyntax whose base expression is also eligible (e.g., math.ceil or a.b.c).Complex expressions like (1 + 1).a are not eligible.
You can implement this check using the IsKind extension method from Loretta.CodeAnalysis.LuaExtensions to verify the SyntaxKind of the node.
static bool canTurnIntoLocal(SyntaxNode node)
{
if (node.IsKind(SyntaxKind.IdentifierName))
return true;
else if (node.IsKind(SyntaxKind.MemberAccessExpression))
return canTurnIntoLocal(((MemberAccessExpressionSyntax) node).Expression;
else
return false;
}The SyntaxFactory is a static class used to instantiate all types of Lua syntax nodes, including identifiers, statements, and lists. Because Loretta syntax trees are immutable, all operations that modify a node return a new instance.
Common factory methods include:
SyntaxFactory.IdentifierName(string text): Creates an identifier.SyntaxFactory.LocalVariableDeclarationStatement(...): Creates a local variable declaration.SyntaxFactory.SeparatedList(IEnumerable<T> items): Creates a syntax list where items are separated by specific tokens.The minifier operates in two main stages:
The renamer iterates through the script and manages variable names using slots:
ISlotAllocator and converts that slot into a name using the NamingStrategy.This step removes all 'trivia' (comments and whitespace) from the tree, inserting spaces only where they are syntactically necessary.
The SegmentedArray<T> type is a specialized collection designed as a high-performance alternative to T[]. It provides O(1) reads and writes and maintains storage density/data locality similar to a standard array, but segments the underlying storage to prevent the underlying arrays from being allocated in the Large Object Heap (LOH).
When to use SegmentedArray<T>:
T[] and need to maintain its performance characteristics (O(1) access)..AsMemory() or .AsSpan() on the instance, as these operations require the entire collection to be continuous in memory.T[] allocations in the Large Object Heap are causing performance issues.