#tonyfettes/mua

#Features

• Safe Lua State Management: Automatic cleanup of Lua states through MoonBit's memory management
• Type-Safe Value Exchange: High-level Value enum for seamless data conversion between MoonBit and Lua
• Table Support: First-class support for Lua tables with iteration, indexing, and JSON conversion
• Error Handling: Comprehensive error types using MoonBit's error handling system
• Multiple Lua Types: Support for all Lua types including functions, userdata, threads, and light userdata
• Standard Libraries: All Lua 5.4 standard libraries pre-loaded
• Memory Safe: Uses registry references to keep Lua values alive across the FFI boundary

#Installation

moon update
moon add tonyfettes/mua

#Quick Start

///|
enum Value {
  Integer(Int64)
  Number(Double)
  String(String)
  Boolean(Bool)
  Nil
  Thread(Lua)
  Table(Table)
  LightUserdata(LightUserdata)
  Userdata(Userdata)
  Function(Function)
}

#Creating a Lua State

///|
let lua : @mua.Lua = try! @mua.new()

#Evaluating Lua Code

// Simple evaluation
let results = lua.eval("return 1 + 2", [])
@json.inspect(results)

// With arguments
let results = lua.eval("return ... * 2", [Integer(21)])
@json.inspect(results)

// Multiple return values
let results = lua.eval("return 1, 'two', 3.0", [])
@json.inspect(results)

#Pushing and Getting Values

// Push a value onto the stack
lua.push(Integer(42))

// Get a value from the stack
let value = lua.get(-1)
@json.inspect(value, content=[42])

#Working with Tables

let results = lua.eval("return {1, 2, 3, x = 'hello'}", [])
match results[0] {
  Table(table) => {
    // Get table length
    let len = table.length()
    @json.inspect(len, content=3)

    // Get value by key
    let value = table.get(Integer(1))
    @json.inspect(value, content=[1])
    let x = table.get(String("x"))
    @json.inspect(x, content=["hello"])

    // Convert to array
    let array = table.to_array()
    @json.inspect(array, content=[1, 2, 3])

    // Iterate over all key-value pairs
    for k, v in table {
      println("\{k} => \{v}")
    }
  }
  _ => ()
}

#Error Handling

let _ = lua.eval("error('something went wrong')", []) catch {
  err => {
    // err is of type Err
    match err {
      RuntimeError(value) => println("Runtime error: \{value}")
      SyntaxError(value) => println("Syntax error: \{value}")
      MemoryError(value) => println("Memory error: \{value}")
      _ => println("Other error")
    }
    []
  }
}

• RuntimeError(Value) - Runtime errors
• SyntaxError(Value) - Syntax errors during compilation
• MemoryError(Value) - Memory allocation failures
• MessageHandlerError(Value) - Errors in the message handler
• FileError(Value) - File-related errors
• UnknownError(Int, Value) - Unknown error codes

#Testing

moon test

moon test --update

#Development

#Code Style

• Code is organized in blocks separated by ///|
• Run moon fmt to format code
• Run moon info to update generated interfaces (.mbti files)
• Run moon check for linting

#Building

moon check              # Type check and lint
moon test               # Run tests
moon info && moon fmt   # Update interfaces and format

#Contributing

1. All tests pass (moon test)
2. Code is formatted (moon fmt)
3. Interface files are updated (moon info)
4. New features include tests

#License

#Related Projects

• tonyfettes/lua - Low-level Lua 5.4 FFI bindings for MoonBit
• MoonBit - The MoonBit programming language

#Acknowledgments