How rampyaaryans/rampyaaryan works
1. What this repo is
Rampyaaryan is a standalone C99 interpreter/runtime for a Hinglish programming language. The core product is a single native executable that can run .ram scripts or start an interactive REPL.
2. Core runtime boundary
The architecture is centered in src/, which contains the full language engine: main.c for process entry, lexer.c for tokenizing, compiler.c for translating source into bytecode, and vm.c for executing that bytecode.
3. Execution pipeline
Source code flows through a classic compiler-to-VM pipeline: .ram source → lexer → compiler → bytecode chunk → virtual machine. The README’s architecture diagrams and the presence of chunk.*, debug.*, and vm.* confirm this is a bytecode-based interpreter rather than a tree-walking interpreter.
4. Language runtime model
The runtime is split across value.*, object.*, table.*, and chunk.*. That suggests a dynamically typed object model with heap-allocated runtime objects, hash-table-backed data structures, and a bytecode container for compiled functions/scripts. debug.* supports inspection/disassembly of compiled chunks.
5. Memory management
memory.* and the README’s GC description indicate the interpreter manages its own heap with an automatic garbage collector. This is a major architectural boundary: language objects are owned by the VM and reclaimed internally, rather than relying on external runtimes like Python or Node.
6. Native/builtin function layer
native.* is the bridge between the language and host capabilities. The README emphasizes a large built-in library covering strings, math, lists, maps, files, types, date/time, system utilities, and higher-order helpers. Architecturally, these are host-side native functions exposed to bytecode as part of the runtime environment.
7. User-facing language features
The language surface is intentionally local-language oriented: keywords like maano, likho, agar, jab tak, and kaam. The examples and tests show support for variables, control flow, functions, closures, lists, maps, exceptions, classes, enums, file I/O, bitwise ops, and higher-order functions.
8. Validation and behavioral coverage
tests/e2e/ contains end-to-end .ram programs that exercise the language from the outside in. These tests are important because they validate the integrated compiler/VM behavior, not just isolated C modules. The examples/ directory serves as runnable documentation and regression coverage for common language features.
9. Documentation subsystem
docs/ is a full static documentation site, including language spec, tutorial, API reference, examples, and changelog. The HTML/CSS/JS files show that documentation is published as GitHub Pages content and is part of the project’s delivery story, not just an afterthought.
10. Editor and developer tooling
vscode-extension/ packages syntax highlighting, theme files, language configuration, and an extension entrypoint. This is a separate integration layer that improves authoring experience but does not participate in runtime execution.
11. Packaging and distribution
The repo includes multiple installer/distribution channels: homebrew/, scoop/, snap/, winget/, npm/, and platform install scripts under scripts/. Architecturally, this means the same native runtime is packaged for several ecosystems rather than being deployed as a hosted service.
12. Build and CI
Makefile, CMakeLists.txt, and .github/workflows/build.yml define the build/release pipeline. The project is built from source on CI and distributed as platform-specific artifacts, reinforcing that the main deliverable is a compiled binary plus ecosystem packaging.
13. How to draw the diagram
A useful architecture diagram would show: language source and examples/tests on the left, the compiler pipeline and VM in the center, the native function layer and GC beneath, and docs/editor/package distribution as supporting subsystems around the core runtime. The key boundary is between user .ram programs and the self-contained C runtime that parses, compiles, executes, and manages memory internally.
Main entry points: vm.c VM · main.c Entry point · compiler.c Compiler · object.c Objects
Components 18
Core runtime
C99 language engine and execution pipeline.
- Entry point · Process startup, CLI handling, and REPL/script dispatch.
src/main.c - Lexer · Converts source text into tokens for the compiler.
src/lexer.c - Compiler · Translates parsed language constructs into bytecode chunks.
src/compiler.c - Chunk · Stores compiled bytecode and related constants.
src/chunk.c - VM · Executes bytecode and drives language behavior.
src/vm.c - Values · Tagged runtime values used throughout execution.
src/value.c - Objects · Heap-allocated language objects and closures/classes.
src/object.c - Tables · Associative storage for globals, instances, and collections.
src/table.c - Memory · Heap allocation and garbage collection management.
src/memory.c - Builtins · Host-side functions exposed to the language runtime.
src/native.c - Debug · Inspection and disassembly support for bytecode chunks.
src/debug.c
Language content
Runnable programs used to exercise and demonstrate the language.
Docs and delivery
Documentation, editor integration, packaging, and build/release tooling.
- Docs site · Published documentation site for spec, tutorial, API, and changelog.
docs/index.html - VS Code · Syntax highlighting, themes, and language configuration for the editor.
vscode-extension/extension.js - Build CI · Source build and release automation for the native runtime.
.github/workflows/build.yml - CMake · Cross-platform build configuration for compiling the executable.
CMakeLists.txt - Packaging · Installer and package definitions for multiple ecosystems.
homebrew/rampyaaryan.rb
Connections 25
- Entry point → Lexer: loads source · Main entry point feeds source into the lexer.
- Entry point → Compiler: drives compile · Main coordinates compilation of script input.
- Entry point → VM: runs VM · Main hands execution over to the virtual machine.
- Lexer → Compiler: tokens · Lexer output is consumed by the compiler.
- Compiler → Chunk: emits · Compiler produces bytecode chunks.
- VM → Chunk: executes · VM reads bytecode from chunks.
- VM → Values: uses · VM manipulates dynamic runtime values.
- VM → Objects: allocates · VM creates and manages heap objects.
- VM → Tables: stores · VM uses hash tables for globals and runtime structures.
- VM → Memory: gc · VM relies on the internal memory manager and collector.
- VM → Builtins: calls · VM exposes native/builtin functionality to programs.
- Debug → Chunk: inspects · Debug utilities disassemble compiled chunks.
- Values → Objects: wraps · Values reference heap objects when needed.
- Objects → Tables: contains · Objects use tables for fields, methods, and maps.
- Memory → Objects: manages · Allocator and GC manage heap objects.
- Memory → Values: tracks · Memory subsystem participates in value/object lifecycle management.
- E2E tests → VM: validates · Integration tests exercise the full compile-and-run pipeline.
- Examples → VM: demonstrates · Examples are runnable programs for the runtime.
- Docs site → Compiler: documents · Docs explain language semantics and usage.
- Docs site → VM: documents · Docs cover execution model and runtime behavior.
- VS Code → Examples: supports · Editor tooling helps author and run sample language code.
- Build CI → CMake: orchestrates · CI uses the build configuration to compile artifacts.
- CMake → Entry point: builds · Build config compiles the native executable from src/.
- Packaging → Entry point: packages · Packaging definitions distribute the compiled runtime.
- Packaging → Build CI: released by · Distribution artifacts are produced through the build pipeline.