Lua Interpreter in Rust

https://github.com/wubingzheng/build-lua-in-rust
Admin
This project guides you through building a Lua Interpreter in Rust from scratch, serving as an...
Tokens:134,833
Snippets:1,425
Trust Score:8.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Lua Table Constructor Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch04-02.table_constructor.md

Demonstrates list, record, and general style table construction in Lua.

```lua
local key = "kkk"
print { 100, 200, 300;  -- list style
        x="hello", y="world";  -- record style
        [key]="vvv";  -- general style
}
```

--------------------------------

### Lua Table Initialization Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch04-03.expdesc.md

This Lua code demonstrates a table initialization with local variables as key and value. It serves as an example for explaining the need for temporary storage of expressions in bytecode generation.

```lua
local k = 'kkk'
local v = 'vvv'
local t = { [k] = v }
```

--------------------------------

### Using Standard Input with Lexer

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch03-03.read_input.md

Example of using `std::io::stdin()` as input for the `ParseProto`.

```rust
fn main() {
    let input = std::io::stdin();  // 标准输入
    let proto = parse::ParseProto::load(input);
    vm::ExeState::new().execute(&proto);
}
```

--------------------------------

### Example Lua Addition Code

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch04-03.expdesc.md

A simple Lua code snippet demonstrating variable assignment and addition.

```lua
local r
local a = 1
local b = 2
r = a + b
```

--------------------------------

### Lua Multiple Assignment Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch04-05.table_rw_and_bnf.md

Illustrates a basic multiple assignment in Lua. This is a precursor to more optimized assignment strategies.

```lua
var_list = tmp_vars // assign values uniformly
```

--------------------------------

### Using `BufReader` with File Input

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch03-03.read_input.md

Example of wrapping a `std::fs::File` with `std::io::BufReader` for buffered reading.

```rust
fn main() {
    // 省略参数处理
    let file = File::open(&args[1]).unwrap();

    let input = BufReader::new(file);  // 封装BufReader
    let proto = parse::ParseProto::load(input);
    vm::ExeState::new().execute(&proto);
}
```

--------------------------------

### Lua goto Example with Continue Label

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch06-06.goto.md

Demonstrates the legal use of goto to a 'continue' label that appears after a local variable declaration, illustrating that labels are considered void statements.

```lua
while xx do
     if yy then goto continue end
     local var = 123
     -- some code
     ::continue::
end
```

--------------------------------

### Lua Dynamic Typing Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch01-03.value_and_type.md

Demonstrates how a variable in Lua can be reassigned to a value of a different type.

```lua
local n = 10
n = "hello" -- OK
```

--------------------------------

### Lua Variable Swap Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch04-05.table_rw_and_bnf.md

Demonstrates a common Lua idiom for swapping two variables using assignment. This example highlights the importance of evaluating all expressions on the right-hand side before performing assignments to ensure correctness.

```lua
local a, b = 1, 2
a, b = b, a  -- swap 2 variables !!!
```

--------------------------------

### String Memory Layout Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch03-01.string_type.md

Illustrates the memory distribution of a Rust String, showing metadata on the stack and the string content on the heap. The metadata includes a pointer to the heap buffer, the string's length, and its capacity.

```text
    stack             heap
    +--------+
    | buffer +------->+----------------+ 
    |--------|        |hello, world!   |
    | len=13 |        +----------------+
    |--------|
    | cap=16 |
    +--------+
```

--------------------------------

### Lua Bytecode for Simple Addition

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch05-02.binary_ops.md

Illustrates the bytecode generated for a simple addition expression with two operands. This example shows how bytecodes for operands can be interspersed.

```lua
local a = -g1 + -g2
```

```text
constants: ['g1', 'g2']
byte_codes:
   GetGlobal(0, 0) # parse the first operand
   GetGlobal(1, 1) # parse the second operand
   Neg(2, 0)       # discharge the first operand
   Neg(3, 1)       # discharge the second operand
   Add(0, 2, 3)
```

--------------------------------

### Test Case for Rust Closure Counter

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch09-04.rust_closure.md

Demonstrates the implementation of a counter example using a Rust closure, showing how to create and push a `Value::RustClosure` onto the state stack.

```rust
fn test_new_counter(state: &mut ExeState) -> i32 {
     let mut i = 0_i32;
     let c = move |_: &mut ExeState| {
         i += 1;
         println!("counter: {i}");
         0
     };
     state.push(Value::RustClosure(Rc::new(RefCell::new(Box::new(c)))));
     1
}

```

--------------------------------

### Stack-Based VM Bytecode for Addition

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch04-03.expdesc.md

Example of bytecode for an addition operation in a stack-based VM. Operands are pushed onto the stack, the Add operation is performed, and the result is popped.

```plaintext
Push 1  # 把a加载到栈顶
Push 2  # 把b加载到栈顶
Add     # 把栈顶的2个数弹出并相加，并把结果压到栈顶
Pop 0   # 把栈顶的结果弹出，并赋值给r
```

--------------------------------

### Basic Rust `print` Function Implementation

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch08-04.rust_functions_and_api.md

An example implementation of the `print` function in Rust, which takes an `ExeState` and prints the first argument from the stack.

```rust
fn lib_print(state: &mut ExeState) -> i32 {
     println!("{}", state.stack[state.base + 1]);
     0
}

```

--------------------------------

### Initial Return Bytecode Execution

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-03.results.md

The initial implementation of the Return bytecode execution. It returns the starting position and count of return values from the stack.

```rust
    ByteCode::Return(iret, nret) => {
        return (self.base + iret as usize, nret as usize);
    }

```

--------------------------------

### Lua Function Stack Layout Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch08-02.arguments.md

Visualizes the stack layout during the execution of the 'foo' function, showing the placement of arguments ('a', 'b') and local variables ('x', 'y') relative to the base pointer.

```text
|     |
+-----+
| foo |
+=====+ <---base
|  a  | 0  \
+-----+
      + arguments
|  b  | 1  /
+-----+
|  x  | 2  \
+-----+
      + local variables
|  y  | 3  /
+-----+
|     |
```

--------------------------------

### Lua Function Stack Layout Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-02.arguments.md

Illustrates the stack layout for a Lua function call, showing the placement of parameters and local variables relative to the base pointer.

```lua
local function foo(a, b)
    local x, y = 1, 2
end
```

--------------------------------

### Vec<String> Memory Layout Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch03-01.string_type.md

Depicts the memory layout for a Vec containing String elements. The Vec's metadata is on the stack, while the String metadata and content are on the heap, demonstrating nested heap allocations.

```text
    stack             heap
    +--------+
    | buffer +------->+-------------+-------------+----
    |--------|        | buf|len|cap | buf|len|cap | ...
    | len=2  |        +--+----------+--+----------+----
    |--------|           |             V
    | cap=4  |           V             +----------------+
    +--------+        +--------+       |hello, world!   |
                      |print   |       +----------------+
                      +--------+
```

--------------------------------

### Lua Bytecode Output for Local Variable Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch02-02.local.md

The bytecode generated for the preceding Lua script. This output illustrates the low-level instructions executed by the virtual machine, including loading constants, moving values, accessing globals, and function calls.

```text
[src/parse.rs:71] &constants = [
     hello, local!,
     print,
     I'm local-print!,
]
byte_codes:
   LoadConst(0, 0)
   Move(1, 0)
   GetGlobal(2, 1)
   Move(3, 1)
   Call(2, 1)
   GetGlobal(2, 1)
   GetGlobal(3, 1)
   Call(2, 1)
   GetGlobal(2, 1)
   Move(3, 2)
   LoadConst(4, 2)
   Call(3, 1)
hello, local!
function
I'm local-print!
```

--------------------------------

### Lua script with multiple print statements

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch01-04.lets_do_it.md

An example Lua script demonstrating the support for multiple 'print' statements. This highlights a potential optimization where 'print' appears twice in the constant table.

```lua
print "hello, world!"
print "hello, again..."
```

--------------------------------

### Rust String UTF-8 Handling Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch03-04.unicode_utf8.md

Demonstrates how Rust's String type handles UTF-8 encoding and contrasts it with byte-by-byte interpretation, revealing potential garbled output.

```rust
# fn main() {
    let s = String::from("print 你好");  // Rust的String是UTF-8编码，所以可以模拟Lua源文件
    println!("string: {}", &s);  // 正常输出
    println!("bytes in UTF-8: {:x?}", s.as_bytes());  // 查看UTF-8编码

    print!("Unicode: ");
    for ch in s.chars() {  // 逐个“字符”读取，查看Unicode编码
        print!("{:x} ", ch as u32);
    }
    println!("");

    let mut x = String::new();
    for b in s.as_bytes().iter() {  // 逐个“字节”读取
        x.push(*b as char);  // as char，字节被解释为Unicode，导致乱码
    }
    println!("wrong: {}", x);
# }

```

--------------------------------

### Lua Code Example: Function Equality

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch09-02.escape_and_closure.md

Demonstrates the behavior of function equality in Lua when functions are returned from another function. The result depends on whether Lua reserves a distinct 'LuaFunction' type or treats all functions as closures.

```lua
local function foo()
     return function () print "hello, world!" end
end
local f1 = foo()
local f2 = foo()
print(f1 == f2) -- true or false?
```

--------------------------------

### Lua Example: Local Variable Definition and Usage

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch02-02.local.md

This Lua code snippet demonstrates the definition and usage of local variables, including assigning values from strings, other local variables, and global functions. It also shows redefining a global function locally.

```lua
local a = "hello, local!" -- define a local by string
local b = a -- define a local by another local
print(b) -- print local variable
print(print) -- print global variable
local print = print --define a local by global variable with same name
print "I'm local-print!" -- call local function
```

--------------------------------

### Get Specific Argument from Stack

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch08-04.rust_functions_and_api.md

Retrieves a specific argument from the Lua stack by its index. Supports both positive (1-based from function start) and negative (from stack top) indexing, similar to Lua's API. Panics on invalid or zero index.

```rust
pub fn get<T>(&'a self, i: isize) -> T where T: From<&'a Value> {
     let narg = self. get_top();
     if i > 0 { // positive index, counting from self.base
         let i = i as usize;
         if i > narg {
             panic!("invalid index: {i} {narg}");
         }
         (&self. stack[self. base + i - 1]). into()
     } else if i < 0 { // Negative index, counting from the top of the stack
         let i = -i as usize;
         if i > narg {
             panic!("invalid index: -{i} {narg}");
         }
         (&self.stack[self.stack.len() - i]).into()
     } else {
         panic!("invalid 0 index");
     }
}
```

--------------------------------

### Virtual Machine Initialization

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch01-04.lets_do_it.md

Initializes a new VM instance and pre-populates the global variables table with the 'print' function.

```rust
impl VM {
    pub fn new() -> Self {
        let mut globals = HashMap::new();
        globals.insert("print".to_string(), Value::Function(print_fn));
        Self { stack: Vec::new(), globals }
    }
    // ... other methods ...
}
```

--------------------------------

### Lua Example: Cross-Layer Upvalue Reference

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch09-02.escape_and_closure.md

This Lua example further illustrates upvalue behavior, specifically showing how an inner function can reference a variable from a function two levels up. It requires intermediate upvalue creation.

```lua
local function newCounter()
    local i = 0
    return function ()
        local function increase()
            i = i + 1  -- upvalue of upper-upper local
        end
        increase()
        print(i)  -- upvalue
    end
end

```

--------------------------------

### Stack-based Bytecode for Table Setting

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch04-03.expdesc.md

Illustrates setting a table using a stack-based virtual machine. Key and value are pushed onto the stack before the SetTable operation.

```bytecode
Move 3 0
Move 4 1
SetTable 2 3 4
```

--------------------------------

### Running a Lua script with the Rust interpreter

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch01-04.lets_do_it.md

Demonstrates the execution of a Lua script ('hello.lua') using the Rust interpreter. Shows the generated constant table, bytecode sequence, and the final output.

```bash
$ cargo r -q --test_lua/hello.lua
[src/parse.rs:39] &constants = [
     print,
     hello, world!,
]
[src/parse.rs:40] &byte_codes = [
     GetGlobal(
         0,
         0,
     ),
     LoadConst(
         1,
         1,
     ),
     Call(
         0,
     ),
]
hello world!
```

--------------------------------

### ParseProto Initialization with Parameters

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch08-02.arguments.md

Initializes the ParseProto structure, setting up the FuncProto with variable argument support and parameter count, and initializing the locals field with the parameter list.

```rust
impl<'a, R: Read> ParseProto<'a, R> {
     // Add has_varargs and params two parameters
     fn new(lex: &'a mut Lex<R>, has_varargs: bool, params: Vec<String>) -> Self {
         ParseProto {
             fp: FuncProto {
                 has_varargs: has_varargs, // Whether to support variable parameters
                 nparam: params.len(), // number of parameters
                 constants: Vec::new(),
                 byte_codes: Vec::new(),
             },
             sp: 0,
             locals: params, // Initialize the locals field with the parameter list
             break_blocks: Vec::new(),
             continue_blocks: Vec::new(),
             gotos: Vec::new(),
             labels: Vec::new(),
             lex: lex,
         }
     }
}
```

--------------------------------

### Lua Interpreter Process (Simplified)

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch01-01.principles.md

Shows the streamlined process in the official Lua implementation, directly generating bytecode from syntax analysis for virtual machine execution.

```text
            Lexical Analysis         Syntax Analysis
Character Stream --------> Token Stream --------> Bytecode
                                                     ^
                                                     |
                                                 virtual machine
```

--------------------------------

### Using Standard Input with ParseProto

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch03-03.read_input.md

Demonstrates how to use standard input (`std::io::stdin`) as the source for parsing by leveraging the `Read` trait.

```rust
fn main() {
     let input = std::io::stdin(); // standard input
     let proto = parse::ParseProto::load(input);
     vm::ExeState::new().execute(&proto);
}

```

--------------------------------

### Lua Tail Call Examples

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch08-05.tail_call.md

Illustrates non-tail calls in Lua, where additional operations are performed after the function call.

```lua
function f1(x)
     g(x) -- discard the return value of g(x) before f1() returns
end
function f2(x)
     return g(x) + 1 -- also execute +1
end
function f3(x)
     return x or g(x) -- also limit the return value of g(x) to 1
end
function f4(x)
     return (g(x)) -- also limit the return value of g(x) to 1
end
```

--------------------------------

### ParseProto Constructor with Parameters

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-02.arguments.md

Shows the Rust implementation of the ParseProto constructor, initializing the FuncProto with variable argument status and parameter names, and setting up the local variables list.

```rust
impl<'a, R: Read> ParseProto<'a, R> {
    // 新增has_varargs和params两个参数
    fn new(lex: &'a mut Lex<R>, has_varargs: bool, params: Vec<String>) -> Self {
        ParseProto {
            fp: FuncProto {
                has_varargs: has_varargs,  // 是否支持可变参数
                nparam: params.len(),  // 形参个数
                constants: Vec::new(),
                byte_codes: Vec::new(),
            },
            sp: 0,
            locals: params,  // 用形参列表初始化locals字段
            break_blocks: Vec::new(),
            continue_blocks: Vec::new(),
            gotos: Vec::new(),
            labels: Vec::new(),
            lex: lex,
        }
    }
}
```

--------------------------------

### Lua Example: Conditional Assignment

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch07-02.logical_in_evalue.md

Illustrates a Lua code snippet where a conditional assignment is used, highlighting the potential for optimization.

```lua
local x = t and t.k
```

--------------------------------

### Lua Function with Single Return Value

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-03.results.md

Example of a Lua function returning a single value, which is a local variable already on the stack.

```lua
local function foo() 
    local x, y = 1, 2
    return x
end
```

--------------------------------

### Lua Function with Local Table (Inefficient)

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch04-02.table_constructor.md

Example of a Lua function where a table is constructed on each call, highlighting potential performance issues.

```lua
local function day_of_week(day)
    local days = {
        "Sunday"=0, "Monday"=1, "Tuesday"=2,
        "Wednesday"=3, "Thursday"=4, "Friday"=5,
        "Saturday"=6,
    }
    return days[day]
end
```

--------------------------------

### Generic For Loop Stack Management (Original Plan)

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch09-05.generic_for.md

Illustrates the stack layout for a generic for loop using the original plan, which reserves a separate space for the control variable.

```text
|           |        |           |     |           |
+-----------+        +-----------+     +-----------+
| iter func |entry   | iter func |     | iter func |
+-----------+        +-----------+     +-----------+
| state     |\       | state     |     | state     |
+-----------+ 2args  +-----------+     +-----------+
| ctrl var  |/       | ctrl var  |     | ctrl var  |<--first return value
+-----------+        +-----------+   ->+-----------+
|           |        :           :  /  | name-     | i
                     +-----------+ /   | list      | v
                     | return-   |-    |           |
                     | values    |
                     |           |

```

--------------------------------

### Lua Local Variable Definition and Usage

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch02-02.local.md

Defines a local variable 'a' and prints its value. This is a simplified example of local variable declaration in Lua.

```lua
local a = "hello, local!" -- define new local var 'a'
print(a) -- use 'a'
```

--------------------------------

### Execute 'hello, world!' in Lua

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch01-00.hello_world.md

This is the target Lua code to be interpreted by the minimal Lua interpreter. It demonstrates a basic function call to print a string.

```lua
print "hello, world!"
```

--------------------------------

### Lua Function with Multiple Return Values

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-03.results.md

Example demonstrating a Lua function returning multiple values, including local variables and an expression.

```lua
local function foo() 
    local x, y = 1, 2
    return x, "Yes", g1+g2
end
```

--------------------------------

### Lua Repeat..Until with Local Variable

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch06-04.repeat_continue.md

Example demonstrating the intended use of a local variable defined within the repeat block in the until condition.

```lua
-- 如果请求失败，则一直重试，直到成功为止
repeat
    local ok = request_xxx()
until ok

```

--------------------------------

### Creating a String and a String Slice

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch03-01.string_type.md

Demonstrates the creation of a `String` and a `&str` slice from it. The `&str` is a reference to a portion of the original `String`.

```rust
let s = String::from("hello, world!"); // String
let r = s[7..12]; // &str
```

--------------------------------

### Using String Input with `std::io::Cursor`

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch03-03.read_input.md

Example of using a string literal wrapped in `std::io::Cursor` as input for the `ParseProto`.

```rust
fn main() {
    let input = std::io::Cursor::new("print \"i am from string!\"");  // 字符串+Cursor
    let proto = parse::ParseProto::load(input);
    vm::ExeState::new().execute(&proto);
}
```

--------------------------------

### Main Entry Point for Rust Interpreter

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch01-04.lets_do_it.md

The main function reads a Lua source file as a command-line argument, parses it, and then executes the resulting bytecode using a virtual machine. Error handling is simplified by terminating the program on failure.

```rust
use std::env;
use std::fs::File;

mod lex;
mod parse;
mod vm;

fn main() {
    let filename = env::args().nth(1).unwrap();
    let mut file = File::open(filename).unwrap();

    let proto = parse::load(&mut file);
    let mut vm = vm::new();
    vm.execute(proto);
}
```

--------------------------------

### Rust: Virtual Machine Execution for VarArgs Bytecode

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-02.arguments.md

This Rust code demonstrates the virtual machine's execution logic for the `ByteCode::VarArgs` instruction. It handles different cases based on the `want` parameter, including using all actual varargs, padding with `nil`, or taking a specific number of arguments.

```rust
ByteCode::VarArgs(dst, want) => {
    self.stack.truncate(self.base + dst as usize);

    let len = varargs.len();  // 实际参数个数
    let want = want as usize; // 需要参数个数
    if want == 0 { // 需要实际全部参数，流程不变
        self.stack.extend_from_slice(&varargs);
    } else if want > len {
        // 需要的比实际的多，则用fill_stack()填补nil
        self.stack.extend_from_slice(&varargs);
        self.fill_stack(dst as usize + len, want - len);
    } else {
        // 需要的比实际的一样或更少
        self.stack.extend_from_slice(&varargs[..want]);
    }
}
```

--------------------------------

### Lua Function Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-05.tail_call.md

A simple Lua function `foo` that calls another function `bar` as its last action, demonstrating the definition of a tail call.

```lua
function foo(a, b) 
    return bar(a + b)
end
```

--------------------------------

### Get Argument Count (Top of Stack)

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-04.rust_functions_and_api.md

Provides the number of arguments passed to a Rust function from Lua. This corresponds to the `lua_gettop()` C API function.

```rust
impl<'a> ExeState {
    // 返回栈顶，即参数个数
    pub fn get_top(&self) -> usize {
        self.stack.len() - self.base
    }
}
```

--------------------------------

### Return Bytecode Instructions

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-03.results.md

Introduces Return0 and Return bytecodes for handling function return values. Return0 is used for functions with no return values, while Return handles cases with a specific number of return values, using a special value (0) to indicate a variable number of return values.

```rust
需要解释的是如何用字节码表示“可变数量”。本节中新增2个返回值相关的字节码，`Return0`和`Return`。其中`Return0`用于没有返回值的情况，所以`Return`字节码中关联的返回值个数的参数不会是`0`，那么`0`就可以作为特殊值，用来表示可变数量的返回值。
```

--------------------------------

### C Logical AND Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch07-02.logical_in_evalue.md

Demonstrates the behavior of the logical AND operator (&&) in C, which converts operands to boolean and returns a boolean result (1 for true, 0 for false).

```c
int i=10, j=11;
printf("%d\n", i && j);  // Output: 1
```

--------------------------------

### Access Argument using func_index

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch02-02.local.md

Within a called function, `func_index` is used to access its arguments on the stack. This example shows how the `lib_print` function accesses its argument.

```rust
fn lib_print(state: &mut ExeState) -> i32 {
    println!("{:?}", state.stack[state.func_index + 1]);  // use func_index
    0
}
```

--------------------------------

### Lua `break` Statement Example

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch06-03.while_break.md

Demonstrates nested loops and the behavior of the `break` statement within different block scopes. The `break` exits the nearest enclosing loop.

```lua
while 123 do -- outer loop block, support `break`
     while true do -- middle-level loop block, support `break`
         a = a + 1
         if a < 10 then -- inner block, does not support `break`
             `break` -- `break` out of the `while true do` loop
         end
     end
end
```

--------------------------------

### Optimized Assignment Logic

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch04-05.table_rw_and_bnf.md

Illustrates an optimized approach for assignment statements, distinguishing between single variable assignments (quick path) and multiple variable assignments (evaluate all first).

```pseudocode
if single variable then
     var = exp // direct assignment, quick path
else // multiple variables
     tmp_vars = exp_list // evaluate all to temporary variables first
```

--------------------------------

### Lua Counter Example with Upvalue

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch09-02.escape_and_closure.md

Demonstrates a counter function where an inner function modifies a local variable from the outer scope. This variable 'i' acts as an upvalue for the inner function 'retf'.

```lua
local function newCounter()
     local i = 0
     local function retf()
         i = i + 1 -- upvalue
         print(i)
     end
     retf() -- called inside newCounter()
     return retf -- return retf
end
```

--------------------------------

### Virtual Machine Execution of Jump

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch06-03.while_break.md

Shows how the virtual machine handles the `ByteCode::Jump` instruction, updating the program counter (pc) to facilitate unconditional jumps, including backward jumps.

```rust
         // unconditional jump
         ByteCode::Jump(jmp) => {
             pc = (pc as isize + jmp as isize) as usize;
         }

```

--------------------------------

### Conceptual Syntax Tree for Addition

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch04-03.expdesc.md

Illustrates the abstract syntax tree generated for the addition statement 'a + b' during syntax analysis.

```text
     |
     V
     +
    / \
   a   b
```

--------------------------------

### Lua Relational Operator Examples

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch07-03.relational_in_condition.md

Demonstrates Lua's behavior with relational operators when comparing different types (numeric and string). Numeric and string types are supported for comparison.

```lua
print (123 == 'hello') -- prints false
print (123 > 'hello') -- throw exception
```

--------------------------------

### Stack layout for numerical for loop variables

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch06-05.numerical-for.md

Illustrates the stack positions for the control variable (init/i), and two anonymous placeholder variables used by the numerical for loop.

```text
      |        |
sp    +--------+
      | init/i |  control variable Name
sp+1  +--------+
      | limit  |  anonymous variable ""
sp+2  +--------+
      | step   |  anonymous variable ""
      +--------+
      |        |

```

--------------------------------

### Rust Code for Initializing ExeState with _ENV

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch09-06.environment.md

This Rust code initializes the ExeState, pushing the _ENV table onto the stack as the first parameter, replacing the previous global variable table.

```rust
impl ExeState {
    pub fn new() -> Self {
        // 全局变量表
        let mut env = Table::new(0, 0);
        env.map.insert("print".into(), Value::RustFunction(lib_print));
        env.map.insert("type".into(), Value::RustFunction(lib_type));
        env.map.insert("ipairs".into(), Value::RustFunction(ipairs));
        env.map.insert("new_counter".into(), Value::RustFunction(test_new_counter));

        ExeState {
            // 栈上压入2个值：虚拟的函数入口，和全局变量表 _ENV
            stack: vec![Value::Nil, Value::Table(Rc::new(RefCell::new(env)))],
            base: 1, // for entry function
        }
    }
}
```

--------------------------------

### Lua Bytecode for Local Variable

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch02-02.local.md

The bytecode generated by luac for the Lua local variable example. It shows instructions for loading constants, calling functions, and managing stack slots.

```text
main <local.lua:0,0> (6 instructions at 0x6000006e8080)
0+ params, 3 slots, 1 upvalue, 1 local, 2 constants, 0 functions
	1	[1]	VARARGPREP	0
	2	[1]	LOADK    	0 0	; "hello, world!"
	3	[2]	GETTABUP 	1 0 1	; _ENV "print"
	4	[2]	MOVE     	2 0
	5	[2]	CALL     	1 2 1	; 1 in 0 out
	6	[2]	RETURN   	1 1 1	; 0 out
```

--------------------------------

### Syntax Analysis for 'print' Statement

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/translations/en/ch01-04.lets_do_it.md

Analyzes the 'print "hello, world!"' statement by tokenizing the input and generating corresponding bytecode. It handles Name and String tokens to produce a ParseProto.

```rust
pub fn load(file: &File) -> ParseProto {
    let mut lex = Lexer::new(file.source());
    let mut constants = Vec::new();
    let mut byte_codes = Vec::new();

    let mut token = lex.next();
    while token != Token::Eos {
        match token {
            Token::Name("print") => {
                let name_idx = constants.len();
                constants.push(Value::String(String::from("print")));
                byte_codes.push(ByteCode::GetGlobal(0, name_idx));

                token = lex.next();
                if let Token::LiteralString(s) = token {
                    let str_idx = constants.len();
                    constants.push(Value::String(s));
                    byte_codes.push(ByteCode::LoadConst(1, str_idx));

                    byte_codes.push(ByteCode::Call(0, 1));
                } else {
                    panic!("Expected string literal after print name");
                }
            }
            _ => panic!("Unexpected token: {:?}", token),
        }
        token = lex.next();
    }

    ParseProto { constants, byte_codes }
}

```

--------------------------------

### Basic Rust Print Function Implementation

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-04.rust_functions_and_api.md

An example of a simple Rust function (`lib_print`) that prints the first argument from the Lua stack. It returns 0, indicating no return values.

```rust
fn lib_print(state: &mut ExeState) -> i32 {
    println!("{}", state.stack[state.base + 1]);
    0
}

```

--------------------------------

### Virtual Machine Execution for `SetList` with Variable Arguments

Source: https://github.com/wubingzheng/build-lua-in-rust/blob/main/src/ch08-02.arguments.md

This Rust code snippet shows how the virtual machine handles the `SetList` bytecode when the second parameter `n` is 0, indicating variable arguments. It determines the number of elements to add to the table by taking all values from the current stack position up to the stack top.

```rust
    ByteCode::SetList(table, n) => {
        let ivalue = self.base + table as usize + 1;
        if let Value::Table(table) = self.get_stack(table).clone() {
            let end = if n == 0 { // 0，可变参数，直至栈顶的全部表达式
                self.stack.len()
            } else {
                ivalue + n as usize
            };
            let values = self.stack.drain(ivalue .. end);
            table.borrow_mut().array.extend(values);
        } else {
            panic!("not table");
        }
    }
```
Tokens:
Raw