A C# (G)Lua lexer, parser, code analysis, transformation and code generation toolkit.
This is (another) rewrite from scratch based on Roslyn and The Complete Syntax of Lua with a few extensions:
- Operators introduced in Garry's Mod Lua (glua):
&&
forand
;||
foror
;!=
for~=
;!
fornot
;
- Comment types introduced in Garry's Mod Lua (glua):
- C style single line comment:
// ...
; - C style multi line comment:
/* */
;
- C style single line comment:
- Characters accepted as part of identifiers by LuaJIT (emojis, non-rendering characters, or basically any byte above
127
/0x7F
); - Roblox compound assignment:
+=
,-=
,*=
,/=
,^=
,%=
,..=
; - Lua 5.3 bitwise operators.
- (Optional) Pick a
LuaSyntaxOptions
preset and then create aLuaParseOptions
from it. If no preset is picked,LuaSyntaxOptions.All
is used by default; - (Optional) Create a
SourceText
from your code (using one of theSourceText.From
overloads); - Call
LuaSyntaxTree.ParseText
with yourSourceText
/string
, (optional)LuaParseOptions
, (optional)path
and (optional)CancellationToken
; - Do whatever you want with the returned
LuaSyntaxTree
.
The NormalizeWhitespace
method replaces all whitespace and and end of line trivia by normalized (standard code style) ones.
If you'd like to get scoping and variable information, create a new Script
from your SyntaxTree
s and then do one of the following:
- Access
Script.RootScope
to get the global scope; - Call
Script.GetScope(SyntaxNode)
to get anIScope
; - Call
Script.GetVariable(SyntaxNode)
to get anIVariable
; - Call
Script.GetLabel(SyntaxNode)
on aGotoStatementSyntax
or aGotoLabelStatementSyntax
to get anIGotoLabel
;
There are 4 kinds of variables:
VariableKind.Local
a variable declared in aLocalVariableDeclarationStatementSyntax
;VariableKind.Global
a variable used without a previous declaration;VariableKind.Parameter
a function parameter;VariableKind.Iteration
a variable that is an iteration variable from aNumericForLoopSyntax
orGenericForLoopSyntax
;
The interface for variables is IVariable
which exposes the following information:
IVariable.Kind
- TheVariableKind
;IVariable.Scope
- The containing scope;IVariable.Name
- The variable name (might be...
for varargs);IVariable.Declaration
- The place where the variable was declared (null
for the implcitarg
and...
variables available in all files and global variables);IVariable.ReferencingScopes
- The scopes that have statements that directly reference this variable;IVariable.CapturingScopes
- Scopes that capture this variable as an upvalue;IVariable.ReadLocations
- Nodes that read from this variable;IVariable.WriteLocations
- Nodes that write to this variable;
There are 4 kinds of scopes:
ScopeKind.Global
- There is only one of these, theScript.RootScope
. It implementsIScope
and only contains globals;ScopeKind.File
- These implementIFileScope
and are the root scopes for files (LuaSyntaxTree
s);ScopeKind.Function
- These implementIFunctionScope
and are generated for these nodes:AnonymousFunctionExpressionSyntax
;LocalFunctionDeclarationStatementSyntax
;FunctionDeclarationStatementSyntax
.
ScopeKind.Block
- These implement onlyIScope
and are generated for normal blocks from these nodes:NumericForStatementSyntax
;GenericForStatementSyntax
;WhileStatementSyntax
;RepeatUntilStatementSyntax
;IfStatementSyntax
;ElseIfClauseSyntax
;ElseClauseSyntax
;DoStatementSyntax
.
IScope
s are the most basic kind of scope and all other scopes derive from it.
The information exposed by them is:
IScope.Kind
- TheScopeKind
;IScope.Node
- TheSyntaxNode
that originated the scope. Will benull
for global and file scopes;IScope.Parent
- The scope's parentIScope
. Will benull
for the global scope;IScope.DeclaredVariables
- TheIVariable
s that were declared in this scope;IScope.ReferencedVariables
- TheIVariable
s that are referenced by this scope or its children;IScope.GotoLabels
- TheIGotoLabel
s directly contained by this scope.
IFunctionScope
s are scopes from function declarations.
They have everything from IScope
s and also:
IFunctionScope.Parameters
- TheIVariable
parameters for this function;IFunctionScope.CapturedVariables
- TheIVariable
s captured as upvalues by this function.
IFileScope
s are scopes for entire files (LuaSyntaxTree
s).
They have everything from IScope
s and also:
IFileScope.ArgsVariable
- The implicitargs
variable available in all lua script files;IFileScope.VarArgParameter
- The implicit vararg parameter available in all lua script files.