luars 0.4.0

# luars

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Crates.io](https://img.shields.io/crates/v/luars.svg)](https://crates.io/crates/luars)

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

## 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.

### 🚧 Incomplete Features
- Full debug library introspection

## Usage

Add to your `Cargo.toml`:

```toml
[dependencies]
luars = "0.4"

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

### Basic Example

```rust
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

| Library | Status | Notes |
|---------|--------|-------|
| `basic` | ✅ Complete | All core functions implemented |
| `string` | ✅ Complete | UTF-8 strings only |
| `table` | ✅ Complete | All table manipulation functions |
| `math` | ✅ Complete | Full math library including random |
| `io` | ✅ Complete | File I/O operations |
| `os` | ✅ Complete | Operating system facilities |
| `coroutine` | ✅ Complete | Full coroutine support |
| `utf8` | ✅ Complete | UTF-8 string operations |
| `package` | ✅ Complete | Module system with require |
| `debug` | ⚠️ Partial | Some introspection features missing |

## 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

```bash
# 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


## License

MIT License - See [LICENSE](../../LICENSE) file for details.