LuaJGG

LuaJGG is a pure Lua interpreter inspired by Luaj, built entirely in Lua. It supports modern Lua 5.3 operators as well as advanced control flow features such as goto and label, providing a flexible and up-to-date environment for executing Lua code.

Overview

LuaJGG compiles Lua source code into bytecode using a robust parser, then executes the bytecode on a custom virtual machine. The project is designed to mirror the functionality of Luaj while incorporating modern Lua features, making it an ideal platform for learning, prototyping, or extending the Lua language.

Key Features

• Robust Parser and Compiler: Converts Lua source code into bytecode with full support for Lua 5.3 syntax, including new arithmetic, bitwise, and logical operators, as well as goto and label statements.
• Custom Virtual Machine (VM): Executes the generated bytecode using a VM that mimics Lua’s own execution model, managing registers, upvalues, and global tables.
• Debug and Type Checking: Offers a debug mode to display detailed opcode execution and incorporates type checking to catch errors early in function calls and operations.
• Modular Design: The project is divided into clear modules (such as parser.lua, vm.lua, opcodes, lex, and code) to simplify maintenance and future extensions.

Project Structure

• vm.lua:
  Contains the virtual machine responsible for executing bytecode. It processes opcodes like OP_MOVE, OP_LOADK, OP_ADD, OP_JMP, OP_CALL, etc., using a program counter (pc) and register-based execution model.

• parser.lua:
  Implements the parser that translates Lua source code into bytecode. This module integrates with other helper modules (like lex for lexical analysis and code for code generation) to handle expressions, table constructors, function definitions, and control flow statements.

• Supporting Modules:
  Other modules such as opcodes.lua, lex.lua, and code.lua provide essential definitions and functionalities that support the parsing and execution processes.

Installation

Requirements

• Lua version 5.3 or later.
• Ensure that all supporting modules (opcodes, lex, code, etc.) are included in the project directory.

Usage

1. Write Lua Code:
   Create your Lua source file using Lua 5.3 syntax, including any of the new operators, goto, and label as needed.

2. Parse and Execute with VM:
   Use the parser to compile your Lua source into bytecode and execute it with the VM:

   local parser = require"parser"
   local f = parser(src)
   print(f:vm())

   Here, src is the Lua source code string that will be parsed and executed.

3. Execute with VM Directly:
   Pass the generated bytecode to the VM to run the program:

   local vm = require "vm"
   vm.run(bytecode, args, upvals, globals, hook)

   You can enable debug mode by setting vm.debug = true to output detailed execution information.

Development Guidelines

• Parser Enhancements:
  If you need to modify or extend the Lua syntax, work with the parser.lua file, which handles expressions, function definitions, control structures, and more.

• Virtual Machine Improvements:
  The core bytecode execution logic resides in vm.lua. You can add new opcodes or optimize existing ones as required.

• Additional Modules:
  Files like opcodes.lua, lex.lua, and code.lua contain definitions and helper functions critical to the overall operation. Modify these with care to maintain compatibility with the rest of the system.

Contribution

Contributions are welcome! If you have suggestions for improvements, encounter bugs, or wish to add new features, please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.