How sohammalakar/fun-assembly works
Project Type & Purpose
• This project is an interpreter for a custom, token-based procedural programming language called “Fun Assembly.” Its purpose is to read and execute programs written in its simple assembly-like syntax. The language supports a variety of operations (arithmetic, string manipulation, file I/O, control flow with jumps, module system, and functions) using a modular design.
• The README emphasizes that it is written in C++ and uses a hash table for symbol storage. In addition, there are sample programs (with .fasml extension) that demonstrate language features. This clearly marks the project as an interpreter with built-in tooling (e.g., syntax highlighter extension for VS Code).
File Structure
• Top-level files such as main.cpp, Makefile, install.bat, and README.md indicate the core engine is in C++ and the build/deployment is scripted.
• The resources folder contains images (like the logo and code theme previews) used for branding and IDE integration.
• The samples directory holds numerous .fasml files showcasing language features (e.g., loops via jumps, function calls, module system, file I/O, arithmetic expressions). These act both as tests and documentation.
• The presence of test.sh and configuration files (e.g., .gitattributes, LICENSE) reflects good project organization and release management.
Main Components of the System (to be included
a. Interpreter Core:
• Main Execution Engine: Entry point is main.cpp which initializes and runs the interpreter.
• Tokenizer/Lexer: Parses the input .fasml files into tokens (based on spaces and keywords).
• Parser/Interpreter: Processes tokens, handles control structures (labels, jumps) and interprets language syntax based on the simplified rules.
• Expression Evaluator: Specifically handles arithmetic and logical expressions (e.g., EXPR keyword).
• Variable/Symbol Table Manager: Uses a hash table to store variables, arrays, and their dynamic (effectively global) context.
b. Module & Function Handling:
• Module Loader: Manages the built-in module system where individual .fasml files can be loaded and executed.
• Function Manager: Handles user-defined functions (via labels and FCALL/FRET) within a single file.
c. Input/Output Handlers:
• File I/O Subsystem: Implements operations like FREAD, FWRITE, and FDEL for file manipulation.
• Terminal I/O Management: Supports reading command line arguments as well as interactive inputs (SCN and SCNL).
d. Extension and Integration Layers:
• Command Line Interface (CLI): Facilitates program execution with arguments (fasml <filename> [args]).
• IDE Integration: Although part of the broader ecosystem, the provided syntax highlighter resources indicate an extension layer, for example with Visual Studio Code.
Relationships & Interactions
• The CLI sends a .fasml file as input to the interpreter core.
• The interpreter core (main.cpp) first tokenizes the code, then uses the parser to build/extract control flow elements (labels, jumps, function definitions).
• The Expression Evaluator processes arithmetic and logical operations.
• All components consult the Variable/Symbol Table Manager to read/write variables during execution.
• On encountering module or function calls, the corresponding Module Loader or Function Manager is invoked, and control is transferred accordingly.
• I/O Handlers process file reading/writing operations and interact with the system’s file system, while CLI arguments are mapped into internal variables ($ARGC, $0, $1, etc.).
Architectural Patterns & Technologies
• The design follows a procedural programming paradigm with a modular plugin-like system (for modules and functions).
• The interpreter’s processing stages resemble a traditional compiler/interpreter architecture – tokenize, parse, then execute.
• Usage of a hash table for variable management is an essential detail that should be highlighted.
• C++ as the implementation language, and mention build tools (Makefile) and platform-specific install scripts (install.bat).