@graffiticode/basis 1.6.1 → 1.6.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +55 -0
- package/package.json +1 -1
- package/spec/package.json +6 -0
- package/spec/spec.html +291 -155
- package/spec/spec.md +164 -11
- package/src/compiler.js +40 -3
- package/src/lexicon.js +44 -35
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
- `npm test` - Run Jest test suite
|
|
8
|
+
- `npm run build-spec` - Generate HTML spec from spec/spec.md
|
|
9
|
+
- `npm run watch-spec` - Watch spec.md and rebuild on changes
|
|
10
|
+
|
|
11
|
+
## Architecture
|
|
12
|
+
|
|
13
|
+
This is the **basis library for Graffiticode languages** - a compiler framework for building domain-specific languages.
|
|
14
|
+
|
|
15
|
+
### Compilation Pipeline (3-Stage Visitor Pattern)
|
|
16
|
+
|
|
17
|
+
All stages are in `src/compiler.js`:
|
|
18
|
+
|
|
19
|
+
1. **Checker** (lines 91-516): Validates AST nodes, collects errors
|
|
20
|
+
2. **Transformer** (lines 557-1391): Evaluates the program, manages environments/scope
|
|
21
|
+
3. **Renderer** (lines 1393-1403): Formats output (minimal pass-through)
|
|
22
|
+
4. **Compiler** (lines 1405-1450): Orchestrates Checker → Transformer → Renderer
|
|
23
|
+
|
|
24
|
+
### Key Files
|
|
25
|
+
|
|
26
|
+
- `src/compiler.js` - Core compiler with Visitor base class and all stages
|
|
27
|
+
- `src/lexicon.js` - Builtin function definitions (28 functions with types/descriptions)
|
|
28
|
+
- `src/share.js` - Shared utilities, error codes, assertion helpers
|
|
29
|
+
- `index.js` - Exports: Checker, Transformer, Renderer, Compiler, lexicon
|
|
30
|
+
- `spec/spec.md` - Language specification (source of truth for syntax/semantics)
|
|
31
|
+
|
|
32
|
+
### Implementation Details
|
|
33
|
+
|
|
34
|
+
- **AST representation**: Node pool as array of `{tag, elts}` objects with numeric IDs
|
|
35
|
+
- **Async traversal**: Uses `setTimeout(0)` to prevent stack overflow during deep recursion
|
|
36
|
+
- **Arithmetic**: Uses Decimal.js for precise numeric operations
|
|
37
|
+
- **Scope**: Stack-based environment management (`enterEnv`, `exitEnv`, `findWord`, `addWord`)
|
|
38
|
+
|
|
39
|
+
## Language Features
|
|
40
|
+
|
|
41
|
+
Graffiticode is a functional language with:
|
|
42
|
+
- Prefix notation for function application (`add 1 2`). Functions have fixed arity, so applications can be parsed unambiguously without grouping syntax (e.g., `add 1 mul 2 3` parses as `add(1, mul(2, 3))`)
|
|
43
|
+
- First-class lambdas (`<x: add x 1>`)
|
|
44
|
+
- Pattern matching (`case x of ... end`)
|
|
45
|
+
- Records and lists as first-class data
|
|
46
|
+
- Let bindings (`let name = value..`)
|
|
47
|
+
- Programs terminated with `..`
|
|
48
|
+
|
|
49
|
+
## Spec Synchronization
|
|
50
|
+
|
|
51
|
+
The language spec (`spec/spec.md`) should stay synchronized with `src/lexicon.js`. When adding/modifying builtin functions:
|
|
52
|
+
1. Update the function in `src/compiler.js` (Transformer handlers)
|
|
53
|
+
2. Add/update entry in `src/lexicon.js` with type signature and description
|
|
54
|
+
3. Document in `spec/spec.md` Built-in Functions table and detailed section
|
|
55
|
+
4. Run `npm run build-spec` to regenerate spec/spec.html
|
package/package.json
CHANGED