luars

A Lua 5.5 runtime implementation in Rust, providing both interpreter and embedding capabilities.

⚠️ Work in Progress: This library is under active development and not yet feature-complete. While core functionality is working, some advanced features and edge cases may not be fully implemented. Use in production environments at your own risk.

Features

• Lua 5.5 Core: Implements Lua 5.5 language semantics
• Pure Rust: Written entirely in Rust with no C dependencies
• Embeddable: Designed to be embedded in Rust applications
• Standard Libraries: Comprehensive coverage of Lua standard libraries
• UTF-8 Strings: All Lua strings are valid UTF-8 (non-standard but safer)
• Optional Serde: JSON serialization support for Lua values (feature-gated)

Current Status

✅ Implemented

• Core language features (operators, control flow, functions, tables)
• Metatables and metamethods
• Coroutines
• Garbage collection
• Most standard libraries: string, table, math, io, os, coroutine, utf8, package
• String pack/unpack with Lua 5.4+ formats (i[n], I[n], j, n, T)
• Lua reference mechanism (luaL_ref/luaL_unref)
• Optional JSON serialization via serde feature

⚠️ Known Limitations

• UTF-8 Only Strings: Unlike standard Lua, strings must be valid UTF-8. Binary data should use the binary type from string.pack/string.unpack.
• Custom Bytecode Format: Uses LuaRS-specific bytecode format, not compatible with standard Lua bytecode.
• Partial Debug Library: Some introspection features are not yet implemented.
• Performance: While functional, performance optimizations are ongoing.

🚧 Incomplete Features

• Some advanced metatable behaviors
• Full debug library introspection
• Complete compliance with all Lua 5.5 edge cases

Usage

Add to your Cargo.toml:

[dependencies]
luars = "0.1"

# Optional: Enable JSON serialization support
luars = { version = "0.1", features = ["serde"] }

Basic Example

use luars::lua_vm::LuaVM;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut vm = LuaVM::new(SafeOption::default());
    vm.open_stdlib(crate::stdlib::Stdlib::All).unwrap();
    let result = vm.execute_string(r#"
        function greet(name)
            return "Hello, " .. name .. "!"
        end
        
        print(greet("World"))
    "#);
    
    Ok(())
}

Standard Library Coverage

Differences from Standard Lua

1. UTF-8 Strings: All Lua strings must be valid UTF-8. The \xNN escape sequences that would produce invalid UTF-8 are not supported. Use string.pack() for binary data.

2. Bytecode Format: Uses a custom LuaRS bytecode format. string.dump() output is not compatible with standard Lua.

3. String/Binary Comparison: String and binary values can be compared for equality, unlike standard Lua where they would be different types.

Building from Source

# Clone the repository
git clone https://github.com/CppCXY/lua-rs
cd lua-rs

# Build the library
cargo build --release

# Run tests
cargo test

# Build with serde support
cargo build --release --features serde

Contributing

Contributions are welcome! This project is actively developed and we appreciate:

• Bug reports and fixes
• Performance improvements
• Documentation improvements
• Test cases for edge cases
• Feature implementations

Please open an issue before starting major work to discuss the approach.

Roadmap

• Complete debug library implementation
• Performance optimizations
• More comprehensive test coverage
• Better error messages and stack traces

License

MIT License - See LICENSE file for details.