# LuaR

**Repository Path**: seafuture/luaR

## Basic Information

- **Project Name**: LuaR
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-24
- **Last Updated**: 2026-02-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Lua 5.4.8 - Rust Implementation

A complete implementation of Lua 5.4.8 in Rust, compatible with the official C implementation.

## Features

### Core Components

- **Lexer** - Full lexical analysis with token tracking and location information
- **Parser** - Complete Lua 5.4 grammar support including:
  - Local and global variables
  - Functions and closures
  - Control structures (if/else, while, for, repeat)
  - Tables and metatables
  - Coroutines
  - Error handling (pcall, xpcall)

- **Compiler** - Bytecode generation compatible with Lua 5.4 instruction set
- **Virtual Machine** - Stack-based VM with full instruction set support
- **Garbage Collector** - Mark-and-sweep GC with incremental collection

### Standard Libraries

| Library | Status | Functions |
|---------|--------|-----------|
| **basic** | Complete | print, type, tostring, tonumber, error, assert, pairs, ipairs, next, select, getmetatable, setmetatable, rawget, rawset, rawequal, rawlen, pcall, xpcall, load, loadfile, dofile, collectgarbage |
| **string** | Complete | len, sub, upper, lower, rep, reverse, byte, char, find, gsub, gmatch, match, format, dump |
| **table** | Complete | concat, insert, move, pack, remove, sort, unpack |
| **math** | Complete | abs, ceil, floor, max, min, sqrt, pow, exp, log, sin, cos, tan, asin, acos, atan, modf, fmod, ult, tointeger, type, random, randomseed, pi, huge, maxinteger, mininteger |
| **io** | Complete | close, flush, input, lines, open, output, popen, read, tmpfile, type, write |
| **os** | Complete | clock, date, difftime, execute, exit, getenv, remove, rename, setlocale, time, tmpname |
| **package** | Complete | require, searchpath, loaders, config, path, cpath, loaded, preload |
| **coroutine** | Complete | create, isyieldable, resume, running, status, wrap, yield, close |
| **utf8** | Complete | char, codes, codepoint, len, offset, charpattern |
| **debug** | Complete | getlocal, setlocal, getinfo, getmetatable, setmetatable, getuservalue, setuservalue, getregistry, gethook, sethook, debug, upvalueid, upvaluejoin, setupvalue, getupvalue, traceback |

## Building

```bash
# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test
```

## Usage

### Command Line

```bash
# Run a Lua file
cargo run -- script.lua

# Or after building
./target/debug/lua script.lua
./target/release/lua script.lua

# Interactive REPL
cargo run
```

### As a Library

```rust
use lua_rs::{parse, compile, execute};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = r#"
        local function factorial(n)
            if n <= 1 then return 1 end
            return n * factorial(n - 1)
        end
        print(factorial(10))
    "#;

    // Parse
    let block = parse(source)?;

    // Compile
    let proto = compile(source, &block)?;

    // Execute
    execute(&proto)?;

    Ok(())
}
```

## Examples

### Coroutines

```lua
local function counter()
    local count = 0
    while true do
        local inc = coroutine.yield(count)
        if inc then
            count = count + inc
        end
    end
end

local co = coroutine.create(counter)
print(coroutine.resume(co))      -- true, 0
print(coroutine.resume(co, 5))   -- true, 5
print(coroutine.resume(co, 10))  -- true, 15
```

### Metatables

```lua
local Vector = {}
Vector.__index = Vector

function Vector:new(x, y)
    return setmetatable({x = x, y = y}, Vector)
end

function Vector:__add(other)
    return Vector:new(self.x + other.x, self.y + other.y)
end

function Vector:__tostring()
    return string.format("(%d, %d)", self.x, self.y)
end

local v1 = Vector:new(1, 2)
local v2 = Vector:new(3, 4)
print(v1 + v2)  -- (4, 6)
```

### Pattern Matching

```lua
local text = "Hello, World! 123"

-- Find words
for word in string.gmatch(text, "%a+") do
    print(word)  -- Hello, World
end

-- Find numbers
local num = string.match(text, "%d+")
print(num)  -- 123

-- Replace
local result = string.gsub("hello world", "(%w+)", "%1!")
print(result)  -- hello! world!
```

## Project Structure

```
src/
  core/
    types.rs      - Lua type system (TValue, Table, etc.)
    state.rs      - Lua state and API
    thread.rs     - Coroutine/thread implementation
    object.rs     - Object system
    string.rs     - String interning
    table.rs      - Table implementation
  lexer/
    lexer.rs      - Lexical analyzer
    token.rs      - Token definitions
  parser/
    parser.rs     - Parser
    ast.rs        - Abstract syntax tree
  compiler/
    codegen.rs    - Bytecode generator
  vm/
    execute.rs    - Virtual machine
  gc/
    collector.rs  - Garbage collector
  libs/
    basic.rs      - Basic library
    string.rs     - String library
    table.rs      - Table library
    math.rs       - Math library
    io.rs         - I/O library
    os.rs         - OS library
    package.rs    - Package library
    coroutine.rs  - Coroutine library
    utf8.rs       - UTF-8 library
    debug.rs      - Debug library
```

## Features Flags

- `debug_trace` - Enable execution tracing
- `gc_debug` - Enable garbage collector debugging

```bash
cargo build --features debug_trace
```

## Compatibility

This implementation aims for full compatibility with Lua 5.4.8. Most Lua programs should run without modification.

### Tested Compatible With
- Lua 5.4.8 official test suite (partial)
- Common Lua patterns and idioms
- Popular Lua libraries

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## License

MIT License

## Acknowledgments

- [Lua.org](https://www.lua.org/) - Original Lua implementation
- Lua 5.4.8 Reference Manual
- The Rust community

## Lua Version

```
Lua 5.4.8
Copyright (C) 1994-2024 Lua.org, PUC-Rio
(Rust implementation)
```