{"id":22386776,"url":"https://github.com/programmerstevie/haskell-assembly-interpreter","last_synced_at":"2025-07-08T17:34:49.186Z","repository":{"id":266516018,"uuid":"867354797","full_name":"programmerstevie/haskell-assembly-interpreter","owner":"programmerstevie","description":"An Assembly Language Parser and Evaluator written in Haskell using Parsec. Parses and executes assembly-like code, simulating a CPU with registers, flags, stack, and control flow instructions.","archived":false,"fork":false,"pushed_at":"2024-10-04T05:23:36.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-02T03:46:05.580Z","etag":null,"topics":["assembly-language","control-flow","cpu-simulation","evaluator","flags","gpl3","haskell","interpreter","open-source","parsec","parser","registers","software-development","stack"],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/programmerstevie.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE","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-03T22:50:30.000Z","updated_at":"2024-10-04T05:23:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"16a46b61-834c-4bce-b0e6-cc5cab50b41f","html_url":"https://github.com/programmerstevie/haskell-assembly-interpreter","commit_stats":null,"previous_names":["programmerstevie/haskell-assembly-interpreter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/programmerstevie/haskell-assembly-interpreter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/programmerstevie%2Fhaskell-assembly-interpreter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/programmerstevie%2Fhaskell-assembly-interpreter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/programmerstevie%2Fhaskell-assembly-interpreter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/programmerstevie%2Fhaskell-assembly-interpreter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/programmerstevie","download_url":"https://codeload.github.com/programmerstevie/haskell-assembly-interpreter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/programmerstevie%2Fhaskell-assembly-interpreter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264314893,"owners_count":23589669,"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":["assembly-language","control-flow","cpu-simulation","evaluator","flags","gpl3","haskell","interpreter","open-source","parsec","parser","registers","software-development","stack"],"created_at":"2024-12-05T02:06:29.719Z","updated_at":"2025-07-08T17:34:49.180Z","avatar_url":"https://github.com/programmerstevie.png","language":"Haskell","readme":"# Assembly Language Interpreter in Haskell\n\nThis repository contains a Haskell implementation of a parser and evaluator for an assembly-like language using the [Parsec](https://hackage.haskell.org/package/parsec) library. The project includes the following modules:\n\n- **`Grammar`**: Defines the data structures used in the abstract syntax tree (AST) and CPU state.\n- **`Lexer`**: Provides lexical analysis functions and basic parsing utilities.\n- **`Parser`**: Parses assembly source code and converts it into an AST.\n- **`Evaluator`**: Executes the parsed instructions by simulating a CPU state.\n- **`Interface`**: Offers convenient functions to run programs and interact with the evaluator.\n- **`Main`**: A sample program demonstrating how to use the modules to parse and execute assembly code.\n\n## Features\n\n- **Instruction Parsing and Execution**: Supports a comprehensive set of assembly instructions, including arithmetic, bitwise, shift, control flow, and stack operations.\n- **Label Handling**: Parses and executes label declarations and references for jump and call instructions.\n- **Argument Parsing and Evaluation**: Handles registers, values, and special arguments, including support for negative numbers and two's complement.\n- **Message Handling**: Parses and displays messages from the `msg` instruction, supporting string literals and arguments.\n- **CPU Simulation**: Simulates a CPU with registers, flags, stack, and program counter.\n- **Flag Management**: Accurately updates CPU flags (Zero Flag, Sign Flag, Overflow Flag, etc.) based on operation results.\n- **Error Handling**: Provides meaningful error messages for invalid instructions or labels.\n- **Program Interface**: Offers functions to run programs from strings or files.\n- **Lexical Analysis**: Uses a custom lexer to tokenize the assembly source code, handling comments, identifiers, reserved words, literals, and symbols.\n- **Sample Execution**: Includes a `Main` module that serves as an example of how to use the parser and evaluator.\n\n## Modules Overview\n\n### Grammar Module\n\nDefines the data structures used throughout the parser and evaluator, including:\n\n- **Registers and Values**: Types for registers (`Reg`), unsigned values (`Val`), and signed values (`SVal`).\n- **Labels**: For control flow instructions.\n- **Messages**: Structure for the `msg` instruction.\n- **Arguments**: Instruction arguments, either registers or values.\n- **Program Lines**: Lines in the program—instructions, labels, or empty lines.\n- **Instructions**: All supported instructions and their arguments.\n\n### Lexer Module\n\nProvides lexical analysis functions and basic parsing utilities. Handles:\n\n- **Comments**: Lines starting with `;`.\n- **Identifiers**: Register names, labels, variable names.\n- **Reserved Words**: Instruction mnemonics.\n- **Literals**: Numeric literals (integers, naturals, octal, hexadecimal) and string literals.\n- **Symbols and Operators**: Commas, colons, and other punctuation.\n\n### Parser Module\n\nReads assembly source code and constructs an AST representing the program structure.\n\n#### Supported Instructions\n\n- **Arithmetic Operations**: `inc`, `dec`, `add`, `sub`, `mul`, `div`\n- **Bitwise Operations**: `xor`, `and`, `or`, `not`, `neg`\n- **Shift Operations**: `shr`, `shl`, `rol`, `ror`\n- **Control Flow**: `jmp`, `je`, `jne`, `jg`, `jl`, `jge`, `jle`, `jz`, `jo`, `jc`, `jp`, `js`, `jnz`, `jno`, `jnc`, `jnp`, `jns`, `call`, `ret`\n- **Stack Operations**: `push`, `pop`, `pushf`, `popf`\n- **Miscellaneous**: `mov`, `cmp`, `msg`, `end`\n\n### Evaluator Module\n\nSimulates a CPU to execute the parsed assembly instructions.\n\n#### CPU State Components\n\n- **Registers**: Hash map with register names as keys.\n- **Stack**: For `push` and `pop` operations.\n- **Call Stack**: Manages return addresses for `call` and `ret`.\n- **Flags**: CPU flags like Zero Flag (ZF), Sign Flag (SF), Overflow Flag (OF).\n- **Program Counter**: Tracks the current instruction line.\n- **Output**: Collects messages from `msg` instructions.\n- **Program**: The parsed program to execute.\n- **Termination Status**: Indicates if the program has terminated.\n\n### Interface Module\n\nProvides functions to run assembly programs and interact with the evaluator.\n\n#### Key Functions\n\n- **Running Programs from Strings**:\n  - `runStr :: String -\u003e CPUState`: Parses and runs a program from a string.\n  - `runStrIO :: String -\u003e IO ()`: Parses and runs a program from a string, printing outputs.\n- **Running Programs from Files**:\n  - `runFile :: String -\u003e IO CPUState`: Parses and runs a program from a file.\n  - `runFileIO :: String -\u003e IO ()`: Parses and runs a program from a file, printing outputs.\n- **CPU State Monad**:\n  - `type CPU a = State CPUState a`: State monad for manipulating the CPU state during execution.\n\n### Main Module\n\nAn example program (`Main.hs`) demonstrating how to use the modules to parse and execute assembly code.\n\n#### Example Code\n\n```haskell\nmodule Main where\n\nimport System.IO\nimport qualified Interface as I\n\nmain :: IO ()\nmain = do\n  putStrLn \"What file would you like to read from?\"\n  filename \u003c- getLine\n  contents \u003c- readFile filename\n  I.runStrIO contents\n```\n\n#### Explanation\n\n- **Purpose**: Provides a simple command-line interface to run assembly programs.\n- **Functionality**:\n  - Prompts the user for a filename.\n  - Reads the content of the specified file.\n  - Uses `runStrIO` from the `Interface` module to parse and execute the program, printing any output messages.\n\n## Usage\n\n### Parsing and Executing an Assembly Code String\n\n```haskell\nimport Interface (runStrIO)\n\nmain :: IO ()\nmain = do\n  let code = \"mov ax, 5\\nmsg 'ax is ', ax\\nend\"\n  runStrIO code\n```\n\n### Parsing and Executing an Assembly Code File\n\n```haskell\nimport Interface (runFileIO)\n\nmain :: IO ()\nmain = do\n  runFileIO \"example.asm\"\n```\n\n### Using the Main Program\n\nCompile and run the `Main.hs` file:\n\n```bash\nghc Main.hs -o assembler\n./assembler\n```\n\nWhen prompted, enter the path to your assembly code file (e.g., `example.asm`).\n\n## Example Assembly Program\n\nGiven an assembly file `example.asm`:\n\n```\nstart:\n  mov ax, 10\n  dec ax\n  cmp ax, 0\n  jne start\nend:\n  msg 'Final value of ax: ', ax\n  end\n```\n\nRunning this program using the `Main` module or `runFileIO` function will execute the loop until `ax` reaches `0` and then display the final value.\n\n## Dependencies\n\n- **GHC (The Glasgow Haskell Compiler)**: Available via the [Haskell Platform](https://www.haskell.org/platform/).\n- **Parsec Library**: For constructing parser combinators.\n- **Data Structures**:\n  - `Data.Vector`: For program lines.\n  - `Data.Sequence`: For output messages.\n  - `Data.HashMap.Strict`: For registers and CPU state.\n- **Custom Modules**:\n  - `Grammar`: AST and CPU state definitions.\n  - `Lexer`: Lexical analysis and parsing utilities.\n  - `Parser`: Code parsing into an AST.\n  - `Evaluator`: Instruction execution.\n  - `Interface`: User-friendly program functions.\n\n## Building and Running\n\n1. **Clone the Repository**:\n\n   ```bash\n   git clone https://github.com/yourusername/assembly-parser-evaluator.git\n   cd assembly-parser-evaluator\n   ```\n\n2. **Install Dependencies**:\n\n   Use Stack to install Haskell dependencies.\n\n3. **Compile the Program**:\n\n   Using Stack:\n\n   ```bash\n   stack build\n   ```\n\n4. **Run the Program**:\n\n   ```bash\n   stack exec assembler\n   ```\n\n   When prompted, enter the filename of your assembly code (e.g., `example.asm`).\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request to discuss improvements, bug fixes, or new features.\n\n## License\n\nThis project is licensed under the GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.\n\n\n## Contact\n\nFor questions or suggestions, feel free to reach out via [email](mailto:programmerstevie@gmail.com).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrammerstevie%2Fhaskell-assembly-interpreter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogrammerstevie%2Fhaskell-assembly-interpreter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrammerstevie%2Fhaskell-assembly-interpreter/lists"}