{"id":25031736,"url":"https://github.com/avidrucker/lccjs","last_synced_at":"2025-04-30T20:00:19.481Z","repository":{"id":275824798,"uuid":"879083942","full_name":"avidrucker/lccjs","owner":"avidrucker","description":"implementation of LCC in JavaScript for educational purposes","archived":false,"fork":false,"pushed_at":"2025-03-01T16:21:49.000Z","size":955,"stargazers_count":0,"open_issues_count":8,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-30T19:32:57.827Z","etag":null,"topics":["assembler","disassembler","interpreter","linker"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avidrucker.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-26T23:31:36.000Z","updated_at":"2025-02-15T18:17:24.000Z","dependencies_parsed_at":null,"dependency_job_id":"e86af3e3-66b3-466d-b02c-cb0fa0419397","html_url":"https://github.com/avidrucker/lccjs","commit_stats":null,"previous_names":["avidrucker/lccjs"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avidrucker%2Flccjs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avidrucker%2Flccjs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avidrucker%2Flccjs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avidrucker%2Flccjs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avidrucker","download_url":"https://codeload.github.com/avidrucker/lccjs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251774817,"owners_count":21641729,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembler","disassembler","interpreter","linker"],"created_at":"2025-02-05T22:44:20.134Z","updated_at":"2025-04-30T20:00:19.446Z","avatar_url":"https://github.com/avidrucker.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **LCC.js \u0026 LCC+js - An Educational Assembler and Interpreter**\n\n## **Overview**\n\n**LCC.js** is a JavaScript-based assembler and interpreter for a simple 16-bit virtual machine architecture. Inspired by educational projects like the Low-Cost Computer (LCC), it provides a platform for learning assembly language programming and understanding how high-level code translates to machine operations.\n\nBuilding on LCC.js, **LCC+js** introduces an extended assembly instruction set and real-time execution features for more interactive, game-oriented applications. This extension adds new instructions (e.g., for non-blocking input, screen manipulation, and timed delays) and separate `.ap` / `.ep` file formats, making it possible to write assembly-based terminal games or simulations.\n\n## **Table of Contents**\n\n1. [Features](#features)  \n2. [Getting Started](#getting-started)  \n   - [Prerequisites](#prerequisites)  \n   - [Installation](#installation)  \n3. [Usage](#usage)  \n   - [Assembling and Running Code with lcc.js](#assembling-and-running-code-with-lccjs)  \n   - [Using assembler.js and interpreter.js Separately](#using-assemblerjs-and-interpreterjs-separately)  \n   - [LCC+js Assembly and Execution](#lccjs-assembly-and-execution)  \n4. [Understanding the Components](#understanding-the-components)  \n   - [lcc.js](#lccjs)  \n   - [assembler.js](#assemblerjs)  \n   - [interpreter.js](#interpreterjs)  \n   - [linker.js](#linkerjs)  \n   - [assemblerplus.js \u0026 interpreterplus.js (LCC+js)](#assemblerplusjs--interpreterplusjs-lccjs)  \n   - [disassembler.js \u0026 linkerStepsPrinter.js](#disassemblerjs--linkerstepsprinterjs)  \n   - [Directory Structure](#directory-structure)  \n5. [Testing](#testing)  \n6. [Architecture Details](#architecture-details)  \n   - [Registers and Memory](#registers-and-memory)  \n   - [Instruction Set (LCC.js \u0026 LCC+js)](#instruction-set-lccjs--lccjs)  \n7. [Contributing](#contributing)  \n   - [Areas for Improvement](#areas-for-improvement)  \n   - [How to Contribute](#how-to-contribute)  \n8. [License](#license)  \n9. [Contact](#contact)  \n\n---\n\n## **Features**\n\n- **Educational Focus**: Ideal for learning the basics of assembly language and virtual machine architectures.  \n- **Cross-Platform**: Runs anywhere Node.js is available.  \n- **Modular Design**: Separate components for assembling, linking, interpreting, plus extended “plus” modules for advanced use.  \n- **Real-Time Extensions (LCC+js)**: Non-blocking input, screen clearing, timed delays, and other game-oriented features.  \n- **Extensible**: Straightforward to add new instructions or behaviors.\n\n---\n\n## **Getting Started**\n\n### **Prerequisites**\n\n- **Node.js**: Download and install from [nodejs.org](https://nodejs.org/).\n\n### **Installation**\n\nClone the repository:\n\n```bash\ngit clone git@github.com:avidrucker/lccjs.git\ncd lccjs\n```  \n\nSetup aliases on UNIX systems:  \n\n```bash\nchmod u+x alias.sh  \n./alias.sh  \nsource ~/.bashrc\n```\n\n---\n\n## **Usage**\n\n### **Assembling and Running Code with lcc.js**\n\nFor a standard `.a` assembly file:\n\n```bash\nnode ./src/core/lcc.js path/to/yourfile.a\n```\n\n- **lcc.js** automatically detects file type, assembles the source, and interprets the resulting `.e` executable.\n\n### **Using assembler.js and interpreter.js Separately**\n\n- **Assemble** a `.a` file:\n\n  ```bash\n  node ./src/core/assembler.js path/to/yourfile.a\n  ```\n\n  This generates a `.e` or `.o` file (depending on directives) in the same folder.\n\n- **Interpret** the produced executable:\n\n  ```bash\n  node ./src/core/interpreter.js path/to/yourfile.e\n  ```\n\n### **LCC+js Assembly and Execution**\n\nFor **LCC+js** features (non-blocking input, screen manipulation, real-time instructions, etc.):\n\n1. **AssemblerPlus** processes `.ap` files, generating `.ep` executables:\n   ```bash\n   node ./src/plus/assemblerplus.js path/to/yourfile.ap\n   ```\n2. **InterpreterPlus** runs the resulting `.ep`:\n   ```bash\n   node ./src/plus/interpreterplus.js path/to/yourfile.ep\n   ```\n3. **LccPlus** (combined) for one-step assembly and execution:\n   ```bash\n   node ./src/plus/lccplus.js path/to/yourfile.ap\n   ```\n\nThese tools introduce extended instructions like `clear`, `sleep`, `nbain`, and more. See [Instruction Set (LCC.js \u0026 LCC+js)](#instruction-set-lccjs--lccjs) for details.\n\n---\n\n## **Understanding the Components**\n\n### **lcc.js**\n- **Purpose**: A high-level command-line tool that orchestrates assembly, linking, and execution.  \n- **Functionality**: \n  - Automatically detects file types (`.a` or `.o`, etc.).  \n  - Assembles `.a` files, interprets `.e` files.  \n  - Provides a simple CLI for a one-step workflow.\n\n### **assembler.js**\n- **Purpose**: Translates `.a` assembly code into machine code (.e or .o).  \n- **Key Features**:\n  - **Two-Pass Assembly**: Builds symbol table (pass 1) and generates code (pass 2).  \n  - **Symbol Table and Directives**: Handles labels, `.start`, `.globl`, `.word`, etc.  \n  - **Error Reporting**: Provides errors and warnings if assembly issues occur.\n\n### **interpreter.js**\n- **Purpose**: Executes `.e` machine code on a simulated 16-bit virtual machine.  \n- **Key Features**:\n  - **Registers \u0026 Memory**: Manages an 8-register set and 65,536 words of memory.  \n  - **Instruction Decoding**: Implements the standard LCC.js instruction set (arithmetic, logic, control flow, I/O via TRAP).  \n  - **Execution Cap**: Defaults to 500,000 instructions to prevent infinite loops.\n\n### **linker.js**\n- **Purpose**: Combines multiple object files (`.o`) into a single executable (`.e`).  \n- **Key Features**:\n  - **Symbol Resolution**: Merges global and external symbols.  \n  - **Adjusts Addresses**: Ensures references and offsets are correct in the final combined output.\n\n### **assemblerplus.js \u0026 interpreterplus.js (LCC+js)**\n- **Purpose**: Extend LCC.js for real-time, interactive applications (games, demos).  \n- **New Instructions**:\n  - `clear`, `sleep`, `nbain`, `cursor`, `srand`, `rand`, `millis`, `resetc`, etc.  \n  - Allows partial screen clearing, non-blocking input, timed delays, etc.\n- **File Extensions**:\n  - `.ap` → **AssemblerPlus** → `.ep`  \n  - `.ep` → **InterpreterPlus** → runs advanced instructions in real time.\n- **Non-Blocking Execution**: The interpreter uses an event loop for continuous stepping and immediate keystroke handling.\n\n### **disassembler.js \u0026 linkerStepsPrinter.js (Extra)**\n- **`disassembler.js`**: Takes an `.e` file and disassembles machine code back to a textual instruction representation—useful for debugging.  \n- **`linkerStepsPrinter.js`**: Outputs the step-by-step linking process to help visualize how symbols and references are resolved.\n\n### **Directory Structure**\n\n- **`core/`**: Contains primary modules for LCC.js (assembler.js, interpreter.js, etc.).  \n- **`utils/`**: Utility scripts for generating listings/statistics, name handling, and other shared functionality.  \n- **`plus/`**: Modules for **LCC+js** (assemblerplus.js, interpreterplus.js, lccplus.js) adding extended features.  \n- **`test/`**: Houses all test files—both integration tests and end-to-end (e2e).  \n- **`extra/`**: Holds additional tools like `disassembler.js` and `linkerStepsPrinter.js`.\n\n---\n\n## **Testing**\n\nExtensive end-to-end (e2e) and integration tests have been implemented for **assembler.js**, **linker.js**, **interpreter.js**, and **lcc.js**—covering a wide range of functionality. Further edge cases can always be added to improve coverage.\n\nRun all tests:\n\n```bash\nnpm test\n```\n\n\u003e Note: If you encounter issues with `jest` not being found, you may need to install it globally: `npm install -g jest`.\n\nRun a specific test file:\n\n```bash\nnpx jest test/integration/assembler.integration.test.js\n```\n\nWhile there are still opportunities for additional test cases (especially unit tests), the current suite provides strong coverage across the main features.\n\n---\n\n## **Architecture Details**\n\n### **Registers and Memory**\n- **Registers**: 8 (r0–r7), with special roles for `sp` (r6), `fp` (r5), and `lr` (r7).  \n- **Memory**: 65,536 words (16-bit each).\n\n### **Instruction Set (LCC.js \u0026 LCC+js)**\n\n**LCC.js** includes:\n- **Arithmetic**: `ADD`, `SUB`, `MUL`, `DIV`, `REM`  \n- **Logical**: `AND`, `OR`, `XOR`, `NOT`  \n- **Data Movement**: `MOV`, `LD`, `ST`, `LEA`, `LDR`, `STR`, `PUSH`, `POP`  \n- **Control Flow**: `BR` (`brz`, `brn`, etc.), `JMP`, `JSR`, `RET`, `BL`, `BLR`  \n- **I/O (TRAP)**: `AOUT`, `DOUT`, `HOUT`, `SOUT`, `AIN`, `DIN`, `HIN`, `SIN`, etc.\n\n**LCC+js** introduces **extended instructions** (via **assemblerplus.js** \u0026 **interpreterplus.js**):\n- **Non-Blocking Input**: `nbain`  \n- **Screen Clearing**: `clear`, partial reset with `resetc`  \n- **Timed Delay**: `sleep`  \n- **Cursor Control**: `cursor` (hide/show)  \n- **Randomness**: `srand`, `rand` (seed-based random generation)  \n- **Milliseconds**: `millis` (retrieve current time mod 1000)\n\n---\n\n## **Contributing**\n\n### **Areas for Improvement**\n\n1. **Debugging Tools**: Symbolic debugger or additional introspection features.  \n2. **More LCC+js Demos**: Additional example programs showing real-time features.  \n3. **Edge-Case Test Coverage**: Adding more specialized test scenarios to further solidify reliability.  \n4. **Performance Optimization**: Improving execution speed and memory usage.  \n5. **Documentation**: Continually refining and expanding docs.\n\n### **How to Contribute**\n\n1. **Fork** the repository.  \n2. **Create a branch** for your feature or fix.  \n3. **Submit a Pull Request** with a clear explanation of changes.\n\n---\n\n## **License**\n\nThis project is open-source under the [MIT License](LICENSE).\n\n---\n\n## **Contact**\n\nFor questions or feedback, please open an issue or submit a pull request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favidrucker%2Flccjs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favidrucker%2Flccjs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favidrucker%2Flccjs/lists"}