How pulkitjakhmola/compiler-pbl-4devs-6sem works
1. What this repo is
ams-lang is a C++17-based language engine for AutomonScript (.ams). Its architecture is centered on a transpile/build pipeline: source scripts are parsed, converted into an internal representation, then compiled into a runnable executable with runtime support.
2. Main top-level flow
The primary data path is:
.ams source → grammar/parser → AST/builder layer → compiler/generator → executable
The runtime and standard library headers provide the execution services that generated code depends on, especially for I/O and system utilities.
3. Language front end
The grammar/AMS.g4 file is the language specification. This strongly suggests an ANTLR4-based parser front end, with the grammar defining the tokenization and syntax rules for AMS. The custom support header caseCaptilizeInputStream.hpp indicates there is at least one specialized parsing/input adaptation layer.
4. AST and build layer
include/core/builder/AST.hpp and Builder.hpp form the core structural layer between parsing and code generation. This is where parsed language constructs are represented as an AST or similar intermediate model, and where higher-level compilation/build logic likely normalizes source into compiler-friendly structures.
5. Code generation layer
include/core/compiler/Generator.hpp is the output-oriented subsystem. Based on the repository description, this is the component that turns the internal model into “compiled execution” output. In an architecture diagram, this is the boundary where language semantics become deployable artifacts.
6. Runtime subsystem
include/runtime/runtime.hpp is the runtime entry point. This is the execution support layer that generated programs rely on at runtime, separating language implementation concerns from the user’s script logic.
7. Standard library
include/stdlib provides built-in functionality exposed to AMS scripts. The visible modules are:
- stdlib/io/console.hpp for console I/O
- stdlib/utils/system.hpp for system-level utilities
This subsystem is likely consumed by both generated code and runtime services, and it is an important boundary for script capabilities.
8. CLI / driver
src/driver/main.cpp is the command-line entry point for the ams tool. The README describes it as managing the build-and-run lifecycle, so this is the orchestration layer that invokes parsing, compilation, and execution workflows.
9. Packaging and build system
CMakeLists.txt indicates the project is built as a CMake-based C++ project. The install scripts (ams_install_linux.sh, ams_install_windows.ps1, plus dependency scripts) show that setup is automated for both Linux and Windows, so the repo supports cross-platform developer setup and tool installation.
10. Examples and validation
examples/hello_world.ams and examples/basic_operators.ams act as reference inputs for the language pipeline. These examples are useful diagram anchors because they show the expected input to the compiler and the kind of runnable output the engine produces.
11. Documentation and repo structure
docs/PROJECT_STRUCTURE.md and the README provide the main architectural map for contributors. The issue templates and CONTRIBUTING.md are supporting project infrastructure, not part of runtime execution, but they reinforce that this is a toolchain-style repository rather than an application runtime alone.
12. Architectural boundary summary
A clean diagram should separate:
- Language definition: grammar
- Compilation model: AST/builder + generator
- Execution support: runtime + stdlib
- User interface: CLI driver
- Build/distribution: CMake + install scripts
The most important flow is that the CLI coordinates the build, the parser and builder transform source into an internal model, and the generator/runtime combination produces and supports executable AMS programs.
Main entry points: main.cpp ams CLI · CMakeLists.txt CMake build · Generator.hpp Generator · AMS.g4 AMS grammar
Components 18
Language front end
Grammar and parsing support for AMS source files.
- AMS grammar · Defines the AMS language syntax and tokens.
grammar/AMS.g4 - Case stream · Specialized input stream support used during parsing.
include/core/supports/caseCaptilizeInputStream.hpp
Compile pipeline
Internal model and code generation steps.
- AST · Core abstract syntax representation for parsed AMS programs.
include/core/builder/AST.hpp - Builder · Transforms parsed source into the compiler-friendly internal structure.
include/core/builder/Builder.hpp - Generator · Converts the internal model into compiled output.
include/core/compiler/Generator.hpp
Execution support
Runtime services and standard library used by generated programs.
- Runtime · Runtime entry point and execution support for generated programs.
include/runtime/runtime.hpp - Console I/O · Built-in console input and output facilities.
include/stdlib/io/console.hpp - System utils · Built-in system-level helper functions exposed to AMS scripts.
include/stdlib/utils/system.hpp
Tooling
Command-line entry point and repository tooling.
- ams CLI · Command-line entry point that orchestrates build and run workflows.
src/driver/main.cpp - CMake build · Primary build configuration for the C++ project.
CMakeLists.txt - Linux install · Linux setup and installation automation.
ams_install_linux.sh - Windows install · Windows setup and installation automation.
ams_install_windows.ps1 - Deps Linux · Linux dependency installation helper.
install_dependency_linux.sh - Deps Windows · Windows dependency installation helper.
install_dependency.ps1
Project materials
Examples, documentation, and contribution scaffolding.
- Examples · Reference AMS programs used to demonstrate the language pipeline.
examples/hello_world.ams - Operators · Example AMS program covering basic operators.
examples/basic_operators.ams - README · Primary repository overview and usage guide.
README.md - Structure docs · Repository structure and architecture notes.
docs/PROJECT_STRUCTURE.md
Connections 21
- ams CLI → AMS grammar: parses · CLI starts the front-end parsing flow.
- ams CLI → Builder: builds · CLI coordinates compilation of AMS source.
- AMS grammar → Case stream: uses · Grammar parsing is adapted by the custom input stream layer.
- AMS grammar → AST: produces · Parsed language structures are represented in the AST.
- Builder → AST: normalizes · Builder shapes parsed constructs into the internal model.
- Builder → Generator: feeds · Builder passes the prepared model to code generation.
- Generator → Runtime: targets · Generated output is meant to run with runtime support.
- Generator → Console I/O: emits to · Generated programs rely on console facilities for I/O.
- Generator → System utils: uses · Generated programs can call system utilities from the stdlib.
- Runtime → Console I/O: provides · Runtime exposes console services to generated code.
- Runtime → System utils: provides · Runtime exposes system services to generated code.
- Examples → ams CLI: input to · Example scripts are representative inputs to the toolchain.
- Operators → ams CLI: input to · Example scripts are representative inputs to the toolchain.
- README → ams CLI: documents · README explains tool usage and workflow.
- README → Builder: documents · README describes the build pipeline.
- Structure docs → AMS grammar: documents · Structure docs map the language front end.
- CMake build → ams CLI: builds · CMake config compiles the driver and core components.
- Linux install → CMake build: sets up · Installer script prepares the project build environment on Linux.
- Windows install → CMake build: sets up · Installer script prepares the project build environment on Windows.
- Deps Linux → CMake build: supports · Dependency setup script supports Linux builds.
- Deps Windows → CMake build: supports · Dependency setup script supports Windows builds.