How syuilo/aiscript works
Project Type and Purpose
• This project is a lightweight scripting language implemented in JavaScript. It provides both a parser and an interpreter to execute scripts written in a JavaScript-like syntax, along with an optional playground (built with Vue and Vite) for live experimentation.
• The README emphasizes that AiScript supports critical language features (arrays, objects, functions, etc.), secure sandbox execution, and an easy integration process with host applications.
Analyzing the File Structure
• The top-level directories include key components such as:
• src: Contains the core implementation of the language.
• src/interpreter: Implements the runtime/interpreter, handling control flow, variable scopes, standard library, and execution logic.
• src/parser: Contains the parser, including scanner, token streams, syntaxes, plugins (such as validator plugins for jumping statements, keywords, and type checks), and visitor patterns.
• playground: Provides a web-based interactive UI built with Vue and configured via Vite, intended to allow online testing and demonstration of AiScript.
• test: Houses various test files to validate both the parser and interpreter functionalities.
• docs, translations, and unreleased: These directories provide documentation, localized resources, and notes about upcoming changes.
• Various configuration files (.eslintrc, tsconfig.json, GitHub workflows, etc.) are present to support coding standards, CI/CD pipelines, and project metadata.
• The file organization suggests a clear separation between the core language engine (parser and interpreter) and its demonstration/utilization (playground), along with supporting infrastructure (tests, docs, etc.).
Key Components
a. Core Language Engine:
• Parser Component:
• Scanner: Located in src/parser/scanner.ts.
• Token Streams: Implemented in src/parser/streams (char-stream.ts, token-stream.ts).
• Syntax Analysis: Found in src/parser/syntaxes (common, expressions, statements, etc.) and the visitor implementation (visit.ts).
• Plugins: Custom validations (plugins directory, e.g., validate-jump-statements.ts, validate-keyword.ts, validate-type.ts) which extend or ensure correct AST structure.
• Utility Functions: Helpers like src/parser/utils.ts and the token definitions in src/parser/token.ts.
• Interpreter Component:
• Core Control & Execution: Implemented in src/interpreter/control.ts.
• Standard Library: In src/interpreter/lib (e.g., std.ts).
• Runtime Environment: Includes scope management (scope.ts), variable handling (variable.ts), reference and value management, and error handling.
• Additional Interpreter Utilities: In files like primitive-props.ts, reference.ts, and src/interpreter/util.ts.
• Entry Point: The main script (src/index.ts or src/node.ts) acts as the bridge between parsing source scripts and handing them over to the runtime.
b. Playground (Frontend UI):
• A separate interactive layer found in the playground/ directory.
• Built using Vue (components like App.vue, Settings.vue) and configured with Vite (vite.config.js).
• Provides end users with a visual and interactive environment to write and test AiScript code.
c. Supporting Infrastructure:
• Test Suite: The test directory outlines unit tests for individual language aspects such as literals, types, jump statements, and interpreter behaviors.
• Documentation & Translations: Separate directories that provide user and developer documentation.
• Build and Deployment Scripts: Located in scripts/ (e.g., start.mjs, parse.mjs, check-release.mjs) to automate tasks related to building, releasing, and maintaining the project.
• CI/CD Workflows: GitHub workflows ensure that tests, linting, publishing, and deployment automation are maintained.
Relationships and Data Flow
1. Source Code Input → Parser (Scanner → Token Streams → Syntax Analysis with Plugin Validations) → Abstract Syntax Tree (AST).
2. AST → Interpreter (using control flow, scope management, and standard library) → Executed Output in the secure sandbox environment.
3. The playground component interacts with the core engine by sending script input to this processing pipeline and receiving execution results to display.
4. Test and documentation pipelines are peripheral but connect to both the core engine and playground for validating and documenting behavior.
Architectural Patterns and Design Principles
• Modular Design: Separate directories for parser and interpreter indicate separation of concerns.
• Plugin Architecture: Custom validations and extendable processing in the parser facilitate specialization and future extensibility.
• Secure Sandbox Execution: Emphasized in the README, showing attention to runtime security.
Elements
• Clearly labeled components: Parser, Interpreter, Playground UI, Testing Suite, Documentation/CI Infrastructure.
• Process flow from source to scanning → tokenization → syntax analysis → AST → interpreter execution.
• Communication between playground and core engine.
• Feedback loops (such as tests feeding back into development).
• Core components (e.g., use rectangles for parser/interpreter modules).
• Annotations indicating key technologies (JavaScript, Vue, Vite, Node.js) and design patterns (plugin system, modular design, sandboxing).