LuaSyntaxOptions

LuaSyntaxOptions defines which language features and syntax variants the Lua parser should accept. Loretta provides built-in presets for all major Lua versions and variants.

Presets

Standard Lua Versions

Lua51

public static readonly LuaSyntaxOptions Lua51

Lua 5.1 syntax (2006). The most widely compatible version.

Lua52

public static readonly LuaSyntaxOptions Lua52

Lua 5.2 syntax (2011). Adds goto, hex escapes, and empty statements.

Lua53

public static readonly LuaSyntaxOptions Lua53

Lua 5.3 syntax (2015). Adds bitwise operators, integers, and floor division.

Lua54

public static readonly LuaSyntaxOptions Lua54

Lua 5.4 syntax (2020). Adds local variable attributes (<const>, <close>).

LuaJIT

LuaJIT20

public static readonly LuaSyntaxOptions LuaJIT20

LuaJIT 2.0 syntax. Based on Lua 5.1 with JIT-specific extensions.

LuaJIT21

public static readonly LuaSyntaxOptions LuaJIT21

LuaJIT 2.1-beta3 syntax. Adds binary numbers and Unicode escapes.

Lua Variants

GMod

public static readonly LuaSyntaxOptions GMod

Garry’s Mod (GLua) syntax. Based on LuaJIT with C-style comments and boolean operators.

Luau

public static readonly LuaSyntaxOptions Luau

Roblox Luau syntax. Includes type annotations, compound assignment, and string interpolation.

FiveM

public static readonly LuaSyntaxOptions FiveM

FiveM/CitizenFX syntax. Based on Lua 5.3 with hash string literals.

Special Presets

All

public static readonly LuaSyntaxOptions All

Accepts all syntax features except integer formats. Useful for maximum compatibility.

AllWithIntegers

public static readonly LuaSyntaxOptions AllWithIntegers

Accepts all syntax features including 64-bit integers.

Constructor

Creates custom syntax options by specifying all parameters.

var options = new LuaSyntaxOptions(
    acceptBinaryNumbers: true,
    acceptCCommentSyntax: false,
    acceptCompoundAssignment: true,
    acceptEmptyStatements: true,
    acceptCBooleanOperators: false,
    acceptGoto: true,
    acceptHexEscapesInStrings: true,
    acceptHexFloatLiterals: true,
    acceptOctalNumbers: false,
    acceptShebang: true,
    acceptUnderscoreInNumberLiterals: true,
    useLuaJitIdentifierRules: false,
    acceptBitwiseOperators: true,
    acceptWhitespaceEscape: true,
    acceptUnicodeEscape: true,
    continueType: ContinueType.ContextualKeyword,
    acceptIfExpression: false,
    acceptInvalidEscapes: false,
    acceptLocalVariableAttributes: true,
    binaryIntegerFormat: IntegerFormats.NotSupported,
    octalIntegerFormat: IntegerFormats.NotSupported,
    decimalIntegerFormat: IntegerFormats.Int64,
    hexIntegerFormat: IntegerFormats.Int64,
    acceptTypedLua: false,
    acceptFloorDivision: true,
    acceptLuaJITNumberSuffixes: false,
    acceptNestingOfLongStrings: true,
    backtickStringType: BacktickStringType.None
);

It’s usually easier to start with a preset and use the With method to modify specific options.

With Method

Creates a modified copy with specific options changed.

public LuaSyntaxOptions With(
    Option<bool> acceptBinaryNumbers = default,
    Option<bool> acceptCCommentSyntax = default,
    // ... all other parameters
)

All parameters are optional. Only specified parameters are changed.

Example

// Start with Lua 5.1 and enable goto
var customOptions = LuaSyntaxOptions.Lua51.With(
    acceptGoto: true
);

// Start with Lua 5.4 and enable C comments
var gmodLike = LuaSyntaxOptions.Lua54.With(
    acceptCCommentSyntax: true,
    acceptCBooleanOperators: true
);

Boolean Properties

Number Literals

Property	Description	Example
`AcceptBinaryNumbers`	Binary number literals	`0b1010`
`AcceptOctalNumbers`	Octal number literals	`0o755`
`AcceptHexFloatLiterals`	Hexadecimal float literals	`0x1.8p3`
`AcceptUnderscoreInNumberLiterals`	Underscores in numbers	`1_000_000`
`AcceptLuaJITNumberSuffixes`	LuaJIT number suffixes	`42ULL`, `3.14i`

String Features

Property	Description	Example
`AcceptHexEscapesInStrings`	Hex escape sequences	`"\x48ello"`
`AcceptWhitespaceEscape`	`\z` whitespace skip	`"line1\z\n line2"`
`AcceptUnicodeEscape`	Unicode escapes	`"\u{1F600}"`
`AcceptInvalidEscapes`	Lua 5.1 bug: accept invalid escapes	`"\q"` → `"q"`
`AcceptNestingOfLongStrings`	Nested long brackets	`[=[ [=[ ]=] ]=]`

Operators

Property	Description	Example
`AcceptBitwiseOperators`	Bitwise operators	`a & b`, `x	y`,` ~z`
`AcceptCBooleanOperators`	C-style boolean operators	`a && b`, `x \|\| y`, `!z`
`AcceptFloorDivision`	Floor division operator	`a // b`
`AcceptCompoundAssignment`	Compound assignment	`x += 1`, `y *= 2`

Statements

Property	Description	Example
`AcceptGoto`	Goto statements and labels	`goto skip; ::skip::`
`AcceptEmptyStatements`	Standalone semicolons	`;;`
`AcceptLocalVariableAttributes`	Variable attributes	`local x <const> = 1`

Type System

Property	Description	Example
`AcceptTypedLua`	Type annotations (Luau)	`local x: number = 1`
`AcceptIfExpressions`	If expressions (Luau)	`if cond then a else b`

Comments

Property	Description	Example
`AcceptCCommentSyntax`	C-style comments	`// comment`, `/* block */`
`AcceptShebang`	Shebang lines	`#!/usr/bin/env lua`

Other

Property	Description
`UseLuaJitIdentifierRules`	Allow characters ≥ 0xF7 in identifiers (LuaJIT)

Enum Properties

ContinueType

public ContinueType ContinueType { get; }

How the parser treats continue:

ContinueType.None - Not recognized
ContinueType.Keyword - Reserved keyword (GMod)
ContinueType.ContextualKeyword - Contextual keyword (Luau)

Integer Formats

public IntegerFormats BinaryIntegerFormat { get; }
public IntegerFormats OctalIntegerFormat { get; }
public IntegerFormats DecimalIntegerFormat { get; }
public IntegerFormats HexIntegerFormat { get; }

How integer literals are stored:

IntegerFormats.NotSupported - Integers not supported (stored as doubles)
IntegerFormats.Double - Parsed as integer, stored as double
IntegerFormats.Int64 - Stored as 64-bit integer

BacktickStringType

public BacktickStringType BacktickStringType { get; }

How backtick strings are parsed:

BacktickStringType.None - Not recognized
BacktickStringType.HashLiteral - FiveM hash strings: `string` → hash value
BacktickStringType.InterpolatedStringLiteral - Luau interpolation: `Hello {name}`

Complete Feature Matrix

View Complete Feature Matrix

Feature	5.1	5.2	5.3	5.4	JIT 2.0	JIT 2.1	GMod	Luau	FiveM
Binary numbers	❌	❌	❌	❌	❌	✅	❌	✅	❌
C comments	❌	❌	❌	❌	❌	❌	✅	❌	❌
Compound assignment	❌	❌	❌	❌	❌	❌	❌	✅	❌
Empty statements	❌	✅	✅	✅	❌	❌	❌	❌	✅
C boolean operators	❌	❌	❌	❌	❌	❌	✅	❌	❌
Goto	❌	✅	✅	✅	✅	✅	✅	❌	✅
Hex escapes	❌	✅	✅	✅	✅	✅	✅	✅	✅
Hex float literals	❌	✅	✅	✅	✅	✅	✅	❌	✅
Octal numbers	❌	❌	❌	❌	❌	❌	❌	❌	❌
Bitwise operators	❌	❌	✅	✅	❌	❌	❌	❌	✅
Whitespace escape	❌	✅	✅	✅	✅	✅	✅	✅	✅
Unicode escape	❌	❌	✅	✅	❌	✅	❌	✅	✅
Continue	❌	❌	❌	❌	❌	❌	keyword	contextual	❌
If expressions	❌	❌	❌	❌	❌	❌	❌	✅	❌
Variable attributes	❌	❌	❌	✅	❌	❌	❌	❌	❌
Integers (decimal)	❌	❌	✅	✅	❌	❌	❌	❌	✅
Typed Lua	❌	❌	❌	❌	❌	❌	❌	✅	❌
Floor division	❌	❌	✅	✅	❌	❌	❌	✅	✅
Backtick strings	❌	❌	❌	❌	❌	❌	❌	interp.	hash

Usage Examples

Detect Lua Version

var code = File.ReadAllText("script.lua");

// Try each version until parsing succeeds
var presets = new[]
{
    ("Lua 5.4", LuaSyntaxOptions.Lua54),
    ("Lua 5.3", LuaSyntaxOptions.Lua53),
    ("Lua 5.2", LuaSyntaxOptions.Lua52),
    ("Lua 5.1", LuaSyntaxOptions.Lua51),
    ("Luau", LuaSyntaxOptions.Luau),
    ("LuaJIT", LuaSyntaxOptions.LuaJIT21)
};

foreach (var (name, preset) in presets)
{
    var tree = LuaSyntaxTree.ParseText(
        code,
        new LuaParseOptions(preset)
    );
    
    if (!tree.GetDiagnostics().Any())
    {
        Console.WriteLine($"Detected: {name}");
        break;
    }
}

Custom Lua Dialect

// Create a custom dialect with Lua 5.3 + continue + C comments
var customLua = LuaSyntaxOptions.Lua53.With(
    acceptCCommentSyntax: true,
    continueType: ContinueType.Keyword
);

var code = @"
for i = 1, 10 do
    // Skip even numbers
    if i % 2 == 0 then
        continue
    end
    print(i)
end
";

var tree = LuaSyntaxTree.ParseText(
    code,
    new LuaParseOptions(customLua)
);

Important Constraints

Incompatible OptionsAcceptFloorDivision and AcceptCCommentSyntax cannot be enabled simultaneously because // is ambiguous:

Floor division: a // b
Single-line comment: // comment

The constructor throws ArgumentException if both are true.

Core API

Syntax Nodes

Visitors & Rewriters

Scoping & Variables

Diagnostics

​Presets

​Standard Lua Versions

​Lua51

​Lua52

​Lua53

​Lua54

​LuaJIT

​LuaJIT20

​LuaJIT21

​Lua Variants

​GMod

​Luau

​FiveM

​Special Presets

​All

​AllWithIntegers

​Constructor

​With Method

​Boolean Properties

​Number Literals

​String Features

​Operators

​Statements

​Type System

​Comments

​Other

​Enum Properties

​ContinueType

​Integer Formats

​BacktickStringType

​Complete Feature Matrix

​Usage Examples

​Detect Lua Version

​Custom Lua Dialect

​Important Constraints

​See Also

Build docs developers (and LLMs) love

Presets

Standard Lua Versions

Lua51

Lua52

Lua53

Lua54

LuaJIT

LuaJIT20

LuaJIT21

Lua Variants

GMod

Luau

FiveM

Special Presets

All

AllWithIntegers

Constructor

With Method

Boolean Properties

Number Literals

String Features

Operators

Statements

Type System

Comments

Other

Enum Properties

ContinueType

Integer Formats

BacktickStringType

Complete Feature Matrix

Usage Examples

Detect Lua Version

Custom Lua Dialect

Important Constraints

See Also