# guyang17/hanling architecture

> Architecture diagram of the GitHub repository guyang17/hanling, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guyang17/hanling
- Repository: https://github.com/guyang17/hanling

## Overview

Hanling is a teaching-oriented, dynamically typed language implemented as a Go tree-walking interpreter. Users run a script, evaluate source text, or execute a file’s built-in tests through the CLI; the runtime tokenizes, parses, and interprets source, with built-ins providing language operations and I/O. The README also highlights lists, maps, error handling, and test/assert support. The sampled sources show the main execution path and CLI test dispatch; other built-in details are represented at subsystem level.

Main entry points: [`pkg/hanling/main.go`](https://github.com/guyang17/hanling/blob/main/pkg/hanling/main.go) (Source runner), [`main.go`](https://github.com/guyang17/hanling/blob/main/main.go) (CLI commands), [`pkg/hanling/builtins.go`](https://github.com/guyang17/hanling/blob/main/pkg/hanling/builtins.go) (Console and files), [`pkg/hanling/interpreter.go`](https://github.com/guyang17/hanling/blob/main/pkg/hanling/interpreter.go) (Interpreter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["CLI commands<br/>[main.go]"]
  node_source_api["Source runner<br/>[main.go]"]
  node_file_api["File runner<br/>[main.go]"]
end

subgraph group_language["Language runtime"]
  node_lexer["Lexer<br/>[lexer.go]"]
  node_parser["Parser and AST<br/>[parser.go]"]
  node_interpreter["Interpreter<br/>[interpreter.go]"]
end

subgraph group_capabilities["Runtime capabilities"]
  node_builtins["Built-in functions<br/>[builtins.go]"]
  node_test_runner["Test runner<br/>[interpreter.go]"]
  node_runtime_io["Console and files<br/>[builtins.go]"]
end

node_user(("User"))
node_filesystem[("Host filesystem")]
node_console(("Console input/output"))

node_user -->|"invokes"| node_cli
node_cli -->|"runs files"| node_file_api
node_cli -->|"evaluates source"| node_source_api
node_cli -->|"runs tests"| node_test_runner
node_file_api -->|"passes source"| node_source_api
node_source_api -->|"tokenizes source"| node_lexer
node_source_api -->|"parses tokens"| node_parser
node_source_api -->|"executes program"| node_interpreter
node_interpreter -->|"registers functions"| node_builtins
node_test_runner -->|"evaluates tests"| node_interpreter
node_builtins -->|"provides I/O"| node_runtime_io
node_runtime_io -->|"reads and writes"| node_filesystem
node_runtime_io -->|"reads and prints"| node_console

click node_cli "https://github.com/guyang17/hanling/blob/main/main.go"
click node_source_api "https://github.com/guyang17/hanling/blob/main/pkg/hanling/main.go"
click node_file_api "https://github.com/guyang17/hanling/blob/main/pkg/hanling/main.go"
click node_lexer "https://github.com/guyang17/hanling/blob/main/pkg/hanling/lexer.go"
click node_parser "https://github.com/guyang17/hanling/blob/main/pkg/hanling/parser.go"
click node_interpreter "https://github.com/guyang17/hanling/blob/main/pkg/hanling/interpreter.go"
click node_builtins "https://github.com/guyang17/hanling/blob/main/pkg/hanling/builtins.go"
click node_test_runner "https://github.com/guyang17/hanling/blob/main/pkg/hanling/interpreter.go"
click node_runtime_io "https://github.com/guyang17/hanling/blob/main/pkg/hanling/builtins.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_source_api,node_file_api,node_user toneBlue
class node_lexer,node_parser,node_interpreter,node_filesystem toneAmber
class node_builtins,node_test_runner,node_runtime_io toneMint
class node_console toneIndigo
```

## Components

### User entry points

- [CLI commands](https://github.com/guyang17/hanling/blob/main/main.go): `main.go`
- [Source runner](https://github.com/guyang17/hanling/blob/main/pkg/hanling/main.go): `pkg/hanling/main.go`
- [File runner](https://github.com/guyang17/hanling/blob/main/pkg/hanling/main.go): `pkg/hanling/main.go`

### Language runtime

- [Lexer](https://github.com/guyang17/hanling/blob/main/pkg/hanling/lexer.go): `pkg/hanling/lexer.go`
- [Parser and AST](https://github.com/guyang17/hanling/blob/main/pkg/hanling/parser.go): `pkg/hanling/parser.go`
- [Interpreter](https://github.com/guyang17/hanling/blob/main/pkg/hanling/interpreter.go): `pkg/hanling/interpreter.go`

### Runtime capabilities

- [Built-in functions](https://github.com/guyang17/hanling/blob/main/pkg/hanling/builtins.go): `pkg/hanling/builtins.go`
- [Test runner](https://github.com/guyang17/hanling/blob/main/pkg/hanling/interpreter.go): `pkg/hanling/interpreter.go`
- [Console and files](https://github.com/guyang17/hanling/blob/main/pkg/hanling/builtins.go): `pkg/hanling/builtins.go`

### Other components

- **User**
- **Host filesystem**
- **Console input/output**

## Connections

- User → CLI commands: invokes (evidence: `main.go`)
- CLI commands → File runner: runs files (evidence: `main.go`)
- CLI commands → Source runner: evaluates source (evidence: `main.go`)
- CLI commands → Test runner: runs tests (evidence: `main.go`)
- File runner → Source runner: passes source (evidence: `pkg/hanling/main.go`)
- Source runner → Lexer: tokenizes source (evidence: `pkg/hanling/main.go`)
- Source runner → Parser and AST: parses tokens (evidence: `pkg/hanling/main.go`)
- Source runner → Interpreter: executes program (evidence: `pkg/hanling/main.go`)
- Interpreter → Built-in functions: registers functions (evidence: `pkg/hanling/interpreter.go`)
- Test runner → Interpreter: evaluates tests (evidence: `pkg/hanling/interpreter.go`)
- Built-in functions → Console and files: provides I/O (evidence: `pkg/hanling/builtins.go`)
- Console and files → Host filesystem: reads and writes (evidence: `pkg/hanling/builtins.go`)
- Console and files → Console input/output: reads and prints (evidence: `pkg/hanling/builtins.go`)
