|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Build and Development Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +make run # Build and run Ghost REPL |
| 9 | +make build # Build for all platforms (mac/linux/windows) |
| 10 | +make test # Run all tests with colored output |
| 11 | +go test -v ./evaluator/... # Run tests for a specific package |
| 12 | +``` |
| 13 | + |
| 14 | +## Architecture Overview |
| 15 | + |
| 16 | +Ghost is a tree-walking interpreter written in Go. The execution pipeline follows this flow: |
| 17 | + |
| 18 | +**Source Code → Scanner → Parser → AST → Evaluator → Object** |
| 19 | + |
| 20 | +### Core Packages |
| 21 | + |
| 22 | +- **scanner/** - Lexical analysis. Transforms source into tokens. Keywords defined in `scanner/scanner.go:21-48`. |
| 23 | +- **token/** - Token type definitions and the Token struct containing lexeme, literal, position info. |
| 24 | +- **parser/** - Recursive descent parser using Pratt parsing. Each AST node type has its own parsing function (e.g., `parser/function.go`, `parser/if.go`). |
| 25 | +- **ast/** - Abstract syntax tree node definitions. Base interfaces in `ast/ast.go`: `Node`, `StatementNode`, `ExpressionNode`. |
| 26 | +- **evaluator/** - Tree-walking evaluation. Main entry point is `Evaluate()` in `evaluator/evaluator.go:15`. Each AST node type has a corresponding `evaluate*` function. |
| 27 | +- **object/** - Runtime value types (Number, String, Boolean, List, Map, Function, Class, etc.). The `Object` interface (`object/object.go:15-19`) requires `Type()`, `String()`, and `Method()`. |
| 28 | +- **ghost/** - Main Ghost struct that orchestrates the pipeline (`ghost/ghost.go`). Entry point for embedding Ghost in Go applications. |
| 29 | + |
| 30 | +### Key Design Patterns |
| 31 | + |
| 32 | +- **Scope**: Wraps Environment and tracks `Self` for method calls (`object/scope.go`). |
| 33 | +- **Environment**: Variable storage with parent chain for lexical scoping (`object/environment.go`). |
| 34 | +- **Library system**: Native functions and modules registered via `library.RegisterFunction()` and `library.RegisterModule()`. Built-in modules in `library/modules/`. |
| 35 | + |
| 36 | +### Object Method System |
| 37 | + |
| 38 | +All object types implement the `Method(method string, args []Object) (Object, bool)` interface. Methods are defined directly on object types (e.g., string methods in `object/string.go`). |
| 39 | + |
| 40 | +## Language Features |
| 41 | + |
| 42 | +Ghost supports: classes with inheritance (`extends`), traits (`trait`/`use`), first-class functions, closures, lists, maps, for/for-in/while loops, switch statements, imports, and compound operators (`+=`, `++`, etc.). |
| 43 | + |
| 44 | +## Version |
| 45 | + |
| 46 | +Update `version/version.go` when releasing. GoReleaser handles binary distribution. |
0 commit comments