Skip to content

CLAUDE.md

Latest commit

 

History

History
136 lines (94 loc) · 5.45 KB

CLAUDE.md

File metadata and controls

136 lines (94 loc) · 5.45 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Online AlpLogo is a browser-based educational programming environment for teaching turtle graphics programming. It features a custom Logo-like language interpreter with multi-language support (English, Azerbaijani, and Russian) and provides a complete IDE with code editor, canvas visualization, and debugging tools.

Technology Stack

  • Framework: Vue 3 with Composition API and <script setup> syntax
  • Language: TypeScript with strict mode enabled
  • Build Tool: Vite 7.x
  • State Management: Pinia 3.x
  • Code Editor: CodeMirror 6 (via vue-codemirror6)
  • Styling: Scoped CSS in Single File Components

Common Commands

# Start development server (runs on port 3000)
npm run dev

# Type-check and build for production
npm run build

# Preview production build
npm run preview

# Run parser tests
npm test

Architecture Overview

Language Processing Pipeline

The AlpLogo language is processed through a traditional interpreter architecture:

  1. Lexer (src/core/parser/Lexer.ts): Tokenizes source code
  2. Parser (src/core/parser/Parser.ts): Recursive descent parser generating an AST
  3. Interpreter (src/core/interpreter/Interpreter.ts): Executes AST nodes with turtle graphics output

Key files:

  • Token definitions and multi-language mappings: src/core/parser/tokens.ts
  • AST node types: src/core/ast/types.ts
  • Built-in command implementations: src/core/interpreter/builtins.ts

Multi-Language Support

The language supports three locales with keyword/command mappings:

  • English: forward, repeat, if, variable, etc.
  • Azerbaijani: ileri, tekrar, eger, deyisen, etc.
  • Russian: вперед, повтори, если, переменная, etc.

All commands normalize to English internally via COMMAND_MAP and KEYWORD_MAP in src/core/parser/tokens.ts.

State Management (Pinia Stores)

Store File Purpose
Editor Store src/stores/editor.ts Code content, errors, line tracking
Turtle Store src/stores/turtle.ts Canvas state, draw commands, turtle position
Execution Store src/stores/execution.ts Execution mode, pause/resume, step debugging
Modal Store src/stores/modal.ts Modal visibility management

Execution Modes

The interpreter supports three execution modes controlled via src/stores/execution.ts:

  • Immediate: Fast execution without delays
  • Animated: Step-by-step visualization with configurable speed (1-100)
  • Step: Debug mode - pauses after each statement, waits for user step

Rendering Architecture

Turtle graphics use a hybrid approach in src/components/canvas/TurtleCanvas.vue:

  • Canvas API: High-performance rendering of lines, text, and dots
  • SVG Overlay: Turtle sprite with rotation and visibility states

Key Directories

src/
├── components/        # Vue SFCs (organized by feature)
│   ├── editor/       # CodeEditor, EditorToolbar, ErrorDisplay
│   ├── canvas/       # TurtleCanvas
│   ├── ui/           # AppHeader, Sidebar, SplitPane, StatusBar
│   └── modals/       # ModalContainer, HelpModal, ExamplesModal, LanguageReferenceModal
├── core/             # Interpreter & Parser
│   ├── ast/          # AST type definitions
│   ├── parser/       # Lexer, Parser, tokens, Parser.test.ts
│   └── interpreter/  # Interpreter, builtins, Environment
├── stores/           # Pinia stores (editor, turtle, execution, modal)
└── languages/        # Syntax highlighters (CodeMirror 6, Monaco legacy)

Language Support Files

File Purpose
src/languages/alplogo.ts Monaco Editor language definition (legacy)
src/languages/alplogo-codemirror.ts CodeMirror 6 syntax highlighter - Active syntax highlighting for multi-language commands

Entry Points

Purpose File Path
HTML Entry index.html
App Bootstrap src/main.ts
Root Component src/App.vue
CodeMirror Language src/languages/alplogo-codemirror.ts

Testing

The project includes a custom test runner for parser validation:

  • Test File: src/core/parser/Parser.test.ts
  • Test Runner: tsx (TypeScript execute)
  • Coverage: Tests for all three languages (EN, AZ, RU), control flow keywords, system values, nested structures, comparison operators, and subroutine syntax

Run tests with npm test.

Important Patterns

  1. Store-to-Store Communication: Components often use multiple stores (e.g., EditorToolbar uses editor, turtle, and execution stores)

  2. Interpreter Callbacks: The Interpreter class uses callback options for UI updates (onDrawCommand, onTurtleUpdate, onLineChange)

  3. Error Handling: Parse and interpreter errors include line/column information for editor highlighting

  4. Multi-language AST: The parser normalizes all commands to English internally while preserving original command names for error messages

  5. CodeMirror Integration: The editor uses CodeMirror 6 with a custom StreamLanguage definition in src/languages/alplogo-codemirror.ts for syntax highlighting across all three supported languages

  6. Custom Test Runner: Parser tests use a lightweight custom test framework (not Jest/Vitest) executed via tsx for fast TypeScript testing without bundling