Language extensions
TypeScriptToLua provides several extensions to the TypeScript language in the form of types and helper functions. To use these language extensions, add the types to your tsconfig.json
:
#
LuaMultiReturn TypeThis language extension allows typing of Lua functions that return multiple values. For example, consider Lua's string.find
, it returns two indices: the start of the found substring and the end of the found substring. In TypeScript, functions can only return one value so a special type is needed to indicate to tstl there are multiple return values. This is the LuaMultiReturn<>
type.
It allows us to declare string.find
like this:
Translating into:
note
Prefer LuaMultiReturn over the similar @tupleReturn annotation. LuaMultiReturn can do anything tupleReturn can, with the added benefit of being able to distinguish between actual tuple tables and multiple return values in the type system.
#
$multiIn order to create a function that returns multiple values it needs to return a LuaMultiReturn<>
type. This is where the $multi
function comes in. Calling $multi
in a return statement will create an instance of the LuaMultiReturn<>
type:
Translates into:
#
$range Iterator FunctionTypeScript's numeric for loops are less restrictive than Lua's, so they are transpiled into while loops instead. To create a Lua-style numeric for loop, you can use the $range
language extension in a for...of loop.
Example:
#
LuaIterable TypeIterators in Lua work quite differently than in TypeScript/JavaScript, so a special type is needed to use them.
For example, to declare and use a Lua function that returns an iterator for a set of strings, you can do this:
Some iterators return multiple values each iteration. To declare these, combine LuaIterable
with LuaMultiReturn
:
Lua iterators support passing an invisible state object each iteration. If your iterator type does this, you can declare the state type as a second type parameter:
This is only really required if you need to use the iterator outside of a for...of
loop.
See the Lua Reference Manual for more information on Lua for loops.
#
LuaPairsIterable TypeSome types can be iterated with pairs()
(for example, if the __pairs
method is set in their metatable). These can be iterated without explicitly calling pairs
by extending them from LuaPairsIterable
.
#
Operator Map TypesLua supports overloading operators on types using metatable methods such as __add
. But, JavaScript and TypeScript do not support this. In order to use overloaded operators on types that support them, you can declare special mapping functions in TS that will translate to those operators in Lua.
A common example of an overloaded operator is addition of a mathematical vector type:
To support addition for this type, you can declare a special function:
The mapping function does not have to be declared as global. For example, you could use declaration merging to declare it as a static function on Vector
:
There are also special variants for the mapping types that allow you do declare operator overloads as methods:
Some operators may have a different return type based on their inputs. You can support this by using intersection types. For example, our Vector
type might overload the multiplication operator to scale by a number, or perform a dot product on two Vectors
:
#
Supported Operators:- Math operators
- LuaAddition / LuaAdditionMethod (
a + b
) - LuaSubtraction / LuaSubtractionMethod (
a - b
) - LuaMultiplication / LuaMultiplicationMethod (
a * b
) - LuaDivision / LuaDivisionMethod (
a / b
) - LuaModulo / LuaModuloMethod (
a % b
) - LuaPower / LuaPowerMethod (
a ^ b
) - LuaFloorDivision / LuaFloorDivisionMethod (
a // b
, only when targeting Lua 5.3 or later) - LuaNegation / LuaNegationMethod (
-x
)
- LuaAddition / LuaAdditionMethod (
- Bitwise operators (only when targeting Lua 5.3 or later)
- LuaBitwiseAnd / LuaBitwiseAndMethod (
a & b
) - LuaBitwiseOr / LuaBitwiseOrMethod (
a | b
) - LuaBitwiseExclusiveOr / LuaBitwiseExclusiveOrMethod (
a ~ b
) - LuaBitwiseLeftShift / LuaBitwiseLeftShiftMethod (
a << b
) - LuaBitwiseRightShift / LuaBitwiseRightShiftMethod (
a >> b
) - LuaBitwiseNot / LuaBitwiseNotMethod (
~x
)
- LuaBitwiseAnd / LuaBitwiseAndMethod (
- LuaConcat / LuaConcatMethod (
a .. b
) - LuaLength / LuaLengthMethod (
#x
)
note
You can also map functions to table accessors (__index
and __newindex
). See Lua Table Types.
#
Lua Table TypesThe LuaTable
type is provided to allow direct creation and manipulation of Lua tables. This is useful if you want to use a table that uses types other than string for its keys, as that is not supported by TypeScript. Calls to lua method tables are translated to simple lua:
table.get(key)
Get a value by key ->table[key]
table.set(key, value)
Set a value for key ->table[key] = value
table.has(key)
Check if key is in table ->table[key] ~= nil
table.delete(key)
Remove key (and its value) from table ->table[key] = nil
#
Generic key and value typesLuaTable
can be used without explicitly providing types for the keys and values, but also allows you to specify the type of keys and values in the table:
#
Getting and SettingCalls to get
and set
on the table will transpile directly to value = table[key]
and table[key] = value
.
Example:
#
IteratingTo iterate over a LuaTable
, use for...of
. This will generate a for...in
statement using pairs()
.
(Remember that in Lua, pairs()
returns the keys in a random order.)
#
Custom Getters and SettersIf you have a type that uses non-string keys, you can use LuaTableGet
and LuaTableSet
function types to declare your own getters & setters, similar to Operator Map Types.
Example:
That example uses the Method
versions of LuaTableGet
and LuaTableSet
. There are also stand-alone versions.
Example:
#
All custom LuaTable functionsThere are more LuaTable functions other than LuaTableGet
and LuaTableSet
that you can use:
LuaTableGet
- Standalone function that gets a value by key from a table.LuaTableGetMethod
- Method that gets a value by key from the table containing this method.LuaTableSet
- Standlone function that sets a value to a key in a table.LuaTableSetMethod
- Method that sets a value to a key in the table containing this method.LuaTableHas
- Standalone function that checks if a key is present in a table.LuaTableHasMethod
- Method that checks if a key is present in the table containing this method.LuaTableDelete
- Standalone function that removes a key and its value from a table.LuaTableDeleteMethod
- Method that removes a key and its value from table containing this method.
#
$vararg ConstantLua allows use of the ellipsis operator (...
) to access command line arguments passed when executing a script file. To access this from TypeScript, you can use the $vararg
constant in a spread expression.
Example:
When run:
Use of $vararg
is only allowed at file scope, and only in a spread expression (...$vararg
).