How joseoliv/cyan works
Main Components
• Lexer – Located in the “lexer” directory. This module is responsible for analyzing the source code and converting it into tokens. Classes like Lexer.java and various Symbol* classes illustrate different token types.
• Parser/AST – Found in the “ast” directory. This section includes ASTNode, various expressions, statements, declarations, and the visitor interface (ASTVisitor.java). This is where the raw tokens are structured into an Abstract Syntax Tree.
• Semantic Analysis & Metaobject Processing – The “meta” directory contains a vast array of metaobject interfaces and classes (e.g., CyanMetaobject, CompilerMacro_parsing, and various “IAction…”, “ICheck…” interfaces). These components likely handle semantic checks, annotations processing, and transformation of the AST.
• Error Handling – The “error” directory houses classes such as CompileErrorException and ProjectError. This module centralizes error detection and reporting across compiler stages.
• Runtime Support – The “cyanruntime” directory provides runtime components (e.g., CyanRuntime and related dynamic type information classes) used during code execution or intermediate representation handling.
• Compiler Driver / Control Flow – The “saci” directory appears to host the entry point and control classes (e.g., Compiler.java, CompilerManager.java) that orchestrate the overall compilation process.
• Ancillary Modules – Other directories such as “refactoring” and “chooseFile” provide additional functionalities (like actions for code modifications or file selection utilities) but serve secondary roles compared to the core compiler pipeline.
Relationships and Interactions
• Data Flow: The source code is first passed to the Lexer, which outputs token streams. These tokens are then processed by the Parser to generate the AST.
• AST to Semantic Analysis: The AST is traversed (using visitor patterns) and handed off to the metaobject framework for semantic analysis and meta-transformation. The meta directory components often work closely with the AST and error modules.
• Error Propagation: Any errors encountered during lexing, parsing, or semantic analysis are managed by the error handling subsystem.
• Runtime and Code Generation: Post semantic analysis, the compiler uses runtime support (cyanruntime) and possibly the “saci” control modules to generate output or perform further compilation steps.
• Utilities & Ancillary Services: Modules like “refactoring” and “chooseFile” interact with the core components to support development and testing.
Architectural Patterns & Design Principles
• Visitor Pattern – Evident in the AST (with ASTVisitor) to traverse and process different node types.
• Modular Design – Clear separation between lexing, parsing, semantic analysis, error handling, and runtime execution.
• Interface-driven Development – Notice the abundance of interfaces (in meta and elsewhere) that allow for flexible implementations and future extensibility.
• Separation of Concerns – Different directories represent isolated concerns: tokenizing, AST generation, semantic analysis, etc.
Technologies, Frameworks, and Libraries
• Java is the implementation language, evident from the .java files.
• Compiler Patterns – Use of metaobject protocols and polymorphic AST visitors are key patterns within the project’s design.
• The “saci” layer orchestrates the stages, likely integrating the various components defined in other directories.