Basics & Core Concepts

This section covers the fundamental building blocks of ktox-lua and how Kotlin's basic syntax maps to Lua.

Packages and Imports

ktox-lua handles Kotlin packages by transpiling them into directory structures and using require statements in Lua.

Kotlin:

package com.example.math

fun add(a: Int, b: Int): Int = a + b

Lua:

-- package: com.example.math

function add(a, b)
    return a + b
end

When you import a Kotlin class or function from another package, it is transpiled to a standard Lua require call. The transpiler ensures that the module path matches the Kotlin package structure.

Example: import com.example.math.Calculator becomes require("com/example/math/Calculator").

Variables (val vs var)

Kotlin's distinction between immutable (val) and mutable (var) variables is preserved during transpilation. Both are transpiled to Lua local variables within the appropriate scope.

Kotlin:

val name = "Kotlin"      // Immutable
var version = 1          // Mutable
version += 1

Lua:

local name = "Kotlin"
local version = 1
version = version + 1

Basic Types

Kotlin types are mapped to their nearest Lua equivalents:

Kotlin Type	Lua Type	Notes
Int, Float, Double	number	Lua 5.1/5.2 uses doubles for all numbers. Lua 5.3+ supports integers.
String	string
Boolean	boolean
List, Map, Set	table	Uses standard Lua tables with helper functions from ktox-lib.lua.
null	nil

Functions

Top-level functions in Kotlin become local functions (if private) or global functions (if public) within the generated Lua module.

Kotlin:

fun greet(name: String): String {
    return "Hello, $name!"
}

private fun internalCalc(x: Int): Int = x * 2

Lua:

function greet(name)
    return "Hello, " .. tostring(name) .. "!"
end

local function internalCalc(x)
    return x * 2
end

String Interpolation & Templates

Kotlin's string interpolation ("Hello, $name") is transpiled into Lua string concatenation (..) with tostring() calls where necessary to ensure safety.

Kotlin:

val count = 5
val message = "The count is $count"
val lang = "Lua"
val msg2 = "Running on $lang ${version + 0}"

Lua:

local count = 5
local message = "The count is " .. tostring(count)
local lang = "Lua"
local msg2 = "Running on " .. tostring(lang) .. " " .. tostring(version + 0)

Multi-line Raw Strings

Raw strings with trimIndent() or trimMargin() are supported. The transpiler escapes newlines and special characters into a standard Lua string literal and passes it to the corresponding ktox_ helper function at runtime.

Kotlin:

val poem = """
    Roses are red,
    Violets are blue.
""".trimIndent()

Lua:

local poem = ktox_trimIndent("\n    Roses are red,\n    Violets are blue.\n")

Control Flow

ktox-lua supports standard Kotlin control-flow constructs, including if expressions, when expressions, for loops with ranges, and while loops.

If Expressions

In Kotlin, if is an expression, meaning it returns a value. ktox-lua transpiles this into Lua's ternary-like logic ((condition and true_val or false_val)) or an Immediately Invoked Function Expression (IIFE) for more complex branches.

Kotlin:

val result = if (sum == 15) { sum + x } else 0

Lua:

local result = (sum == 15 and sum + x or 0)

For more complex blocks:

Kotlin:

val result = if (sum == 15) {
    val x = compute()
    sum + x
} else 0

Lua:

local result = (function()
    if sum == 15 then
        local x = compute()
        return sum + x
    else
        return 0
    end
end)()

When Expressions

Kotlin's when expression is a powerful replacement for the traditional switch statement. ktox-lua transpiles when into a series of if-elseif-else statements in Lua.

Kotlin:

val color = when (id) {
    1 -> "Red"
    2 -> "Green"
    else -> "Unknown"
}

Lua:

local color
if id == 1 then
    color = "Red"
elseif id == 2 then
    color = "Green"
else
    color = "Unknown"
end

For Loops and Ranges

ktox-lua supports Kotlin's for loops with various range expressions, mapping them to Lua's numeric for loop.

Simple Ranges (..)

Kotlin:

for (i in 1..5) {
    sum += i
}

Lua:

for i = 1, 5 do
    sum = sum + i
end

Until, downTo, and step

Kotlin:

// until: 0 to 4 (exclusive of 5)
for (i in 0 until 5) { total += i }

// downTo: 5 down to 1
for (i in 5 downTo 1) { total += i }

// step: increment by 2
for (i in 0..4 step 2) { total += i }

Lua:

-- until
for i = 0, 5 - 1 do
    total = total + i
end

-- downTo
for i = 5, 1, -1 do
    total = total + i
end

-- step
for i = 0, 4, 2 do
    total = total + i
end

Iterating over Collections

You can also iterate over lists and maps using the standard Kotlin for syntax.

Kotlin:

for (item in listOf("a", "b")) {
    println(item)
}

Lua:

for _, item in ipairs({"a", "b"}) do
    print(item)
end

While Loops

while and do-while loops are supported and map directly to Lua's while and repeat-until.

Kotlin:

while (x > 5) {
    if (x == 10) {
        x -= 2
        continue
    }
    x -= 1
}

Lua:

while x > 5 do
    if x == 10 then
        x = x - 2
        goto continue
    end
    x = x - 1
    ::continue::
end

Destructuring Declarations

ktox-lua supports destructuring declarations for Pair and Triple (and other types that provide componentN methods).

Kotlin:

val (x, y) = Pair(1, 2)

Lua:

local __ktox_d = {1, 2}
local x = __ktox_d[1]
local y = __ktox_d[2]