# shidoengie/shlang-rust architecture

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

- Interactive diagram: https://gitdiagram.com/shidoengie/shlang-rust
- Repository: https://github.com/shidoengie/shlang-rust

## Overview

Shlang is a toy programming language with a Rust implementation. Its user-facing purpose is to run programs written in the language; the README shows a `main` function and points users to the command-line options and examples. The main runtime stages are source lexing, parsing into syntax nodes, and interpretation with scopes, values, and built-ins. The README also documents filesystem, math, and command capabilities through its examples and built-in registrations. Several internal calls are supported by the source index, but the CLI-to-runtime wiring is not shown in the sampled evidence.

Main entry points: [`src/backend/interpreter.rs`](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/interpreter.rs) (Interpreter), [`src/backend/defaults/mod.rs`](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/mod.rs) (Default environment), [`src/backend/defaults/functions/mod.rs`](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/mod.rs) (Built-in functions), [`src/backend/defaults/natives/mod.rs`](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/mod.rs) (Native methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Language frontend"]
  node_lexer["Lexer<br/>[lexer.rs]"]
  node_tokens["Tokens<br/>[tokens.rs]"]
  node_parser["Parser<br/>[parser.rs]"]
  node_ast["Syntax nodes<br/>[nodes.rs]"]
end

subgraph group_runtime["Interpreter runtime"]
  node_interpreter["Interpreter<br/>[interpreter.rs]"]
  node_scope["Scopes<br/>[scope.rs]"]
  node_values["Values and heap<br/>[values.rs]"]
end

subgraph group_builtins["Built-in capabilities"]
  node_defaults["Default environment<br/>[mod.rs]"]
  node_functions["Built-in functions<br/>[mod.rs]"]
  node_misc["General functions<br/>[misc.rs]"]
  node_repr["Representation<br/>[repr.rs]"]
  node_filesys["Filesystem functions<br/>[filesys.rs]"]
  node_math["Math functions<br/>[math.rs]"]
  node_natives["Native methods<br/>[mod.rs]"]
  node_cmd["Command execution<br/>[cmd.rs]"]
  node_hashmap["Hash maps<br/>[hashmap.rs]"]
  node_lists["Lists<br/>[lists.rs]"]
  node_strings["Strings<br/>[strings.rs]"]
end

subgraph group_support["Runtime support"]
  node_errors["Language errors<br/>[lang_errors.rs]"]
  node_spans["Source spans<br/>[spans.rs]"]
  node_charvec["Character storage<br/>[charvec.rs]"]
end

node_author(("Program author"))
node_source["Shlang program"]

node_author -->|"writes"| node_source
node_source -.->|"lexes source"| node_lexer
node_lexer -->|"produces tokens"| node_tokens
node_lexer -->|"uses characters"| node_charvec
node_lexer -->|"marks locations"| node_spans
node_parser -->|"consumes tokens"| node_lexer
node_parser -->|"checks token kinds"| node_tokens
node_parser -->|"builds nodes"| node_ast
node_parser -->|"reports parse errors"| node_errors
node_interpreter -->|"evaluates nodes"| node_ast
node_interpreter -->|"reads bindings"| node_scope
node_interpreter -->|"evaluates values"| node_values
node_interpreter -->|"loads defaults"| node_defaults
node_interpreter -->|"returns runtime errors"| node_errors
node_defaults -->|"creates bindings"| node_scope
node_defaults -->|"registers built-ins"| node_values
node_defaults -->|"includes functions"| node_functions
node_defaults -->|"includes natives"| node_natives
node_functions -->|"registers functions"| node_misc
node_functions -->|"registers representation"| node_repr
node_functions -->|"registers filesystem"| node_filesys
node_functions -->|"registers math"| node_math
node_natives -->|"registers commands"| node_cmd
node_natives -->|"registers maps"| node_hashmap
node_natives -->|"registers lists"| node_lists
node_natives -->|"registers strings"| node_strings

click node_lexer "https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/lexer.rs"
click node_tokens "https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/tokens.rs"
click node_parser "https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/parser.rs"
click node_ast "https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/nodes.rs"
click node_interpreter "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/interpreter.rs"
click node_scope "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/scope.rs"
click node_values "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/values.rs"
click node_defaults "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/mod.rs"
click node_functions "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/mod.rs"
click node_misc "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/misc.rs"
click node_repr "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/repr.rs"
click node_filesys "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/filesys.rs"
click node_math "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/math.rs"
click node_natives "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/mod.rs"
click node_cmd "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/cmd.rs"
click node_hashmap "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/hashmap.rs"
click node_lists "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/lists.rs"
click node_strings "https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/strings.rs"
click node_errors "https://github.com/shidoengie/shlang-rust/blob/main/src/lang_errors.rs"
click node_spans "https://github.com/shidoengie/shlang-rust/blob/main/src/spans.rs"
click node_charvec "https://github.com/shidoengie/shlang-rust/blob/main/src/charvec.rs"

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_lexer,node_tokens,node_parser,node_ast toneBlue
class node_interpreter,node_scope,node_values toneAmber
class node_defaults,node_functions,node_misc,node_repr,node_filesys,node_math,node_natives,node_cmd,node_hashmap,node_lists,node_strings toneMint
class node_errors,node_spans,node_charvec toneRose
class node_author,node_source toneIndigo
```

## Components

### Language frontend

- [Lexer](https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/lexer.rs): `src/frontend/lexer.rs`
- [Tokens](https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/tokens.rs): `src/frontend/tokens.rs`
- [Parser](https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/parser.rs): `src/frontend/parser.rs`
- [Syntax nodes](https://github.com/shidoengie/shlang-rust/blob/main/src/frontend/nodes.rs): `src/frontend/nodes.rs`

### Interpreter runtime

- [Interpreter](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/interpreter.rs): `src/backend/interpreter.rs`
- [Scopes](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/scope.rs): `src/backend/scope.rs`
- [Values and heap](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/values.rs): `src/backend/values.rs`

### Built-in capabilities

- [Default environment](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/mod.rs): `src/backend/defaults/mod.rs`
- [Built-in functions](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/mod.rs): `src/backend/defaults/functions/mod.rs`
- [General functions](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/misc.rs): `src/backend/defaults/functions/misc.rs`
- [Representation](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/repr.rs): `src/backend/defaults/functions/repr.rs`
- [Filesystem functions](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/filesys.rs): `src/backend/defaults/functions/filesys.rs`
- [Math functions](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/functions/math.rs): `src/backend/defaults/functions/math.rs`
- [Native methods](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/mod.rs): `src/backend/defaults/natives/mod.rs`
- [Command execution](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/cmd.rs): `src/backend/defaults/natives/cmd.rs`
- [Hash maps](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/hashmap.rs): `src/backend/defaults/natives/hashmap.rs`
- [Lists](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/lists.rs): `src/backend/defaults/natives/lists.rs`
- [Strings](https://github.com/shidoengie/shlang-rust/blob/main/src/backend/defaults/natives/strings.rs): `src/backend/defaults/natives/strings.rs`

### Runtime support

- [Language errors](https://github.com/shidoengie/shlang-rust/blob/main/src/lang_errors.rs): `src/lang_errors.rs`
- [Source spans](https://github.com/shidoengie/shlang-rust/blob/main/src/spans.rs): `src/spans.rs`
- [Character storage](https://github.com/shidoengie/shlang-rust/blob/main/src/charvec.rs): `src/charvec.rs`

### Other components

- **Program author**
- **Shlang program**

## Connections

- Program author → Shlang program: writes (evidence: `README.md`)
- Shlang program → Lexer: lexes source
- Lexer → Tokens: produces tokens (evidence: `src/frontend/lexer.rs`)
- Lexer → Character storage: uses characters (evidence: `src/frontend/lexer.rs`)
- Lexer → Source spans: marks locations (evidence: `src/frontend/lexer.rs`)
- Parser → Lexer: consumes tokens (evidence: `src/frontend/parser.rs`)
- Parser → Tokens: checks token kinds (evidence: `src/frontend/parser.rs`)
- Parser → Syntax nodes: builds nodes (evidence: `src/frontend/parser.rs`)
- Parser → Language errors: reports parse errors (evidence: `src/frontend/parser.rs`)
- Interpreter → Syntax nodes: evaluates nodes (evidence: `src/backend/interpreter.rs`)
- Interpreter → Scopes: reads bindings (evidence: `src/backend/interpreter.rs`)
- Interpreter → Values and heap: evaluates values (evidence: `src/backend/interpreter.rs`)
- Interpreter → Default environment: loads defaults (evidence: `src/backend/interpreter.rs`)
- Interpreter → Language errors: returns runtime errors (evidence: `src/backend/interpreter.rs`)
- Default environment → Scopes: creates bindings (evidence: `src/backend/defaults/mod.rs`)
- Default environment → Values and heap: registers built-ins (evidence: `src/backend/defaults/mod.rs`)
- Default environment → Built-in functions: includes functions (evidence: `src/backend/defaults/mod.rs`)
- Default environment → Native methods: includes natives (evidence: `src/backend/defaults/mod.rs`)
- Built-in functions → General functions: registers functions (evidence: `src/backend/defaults/functions/mod.rs`)
- Built-in functions → Representation: registers representation (evidence: `src/backend/defaults/functions/mod.rs`)
- Built-in functions → Filesystem functions: registers filesystem (evidence: `src/backend/defaults/functions/mod.rs`)
- Built-in functions → Math functions: registers math (evidence: `src/backend/defaults/functions/mod.rs`)
- Native methods → Command execution: registers commands (evidence: `src/backend/defaults/natives/mod.rs`)
- Native methods → Hash maps: registers maps (evidence: `src/backend/defaults/natives/mod.rs`)
- Native methods → Lists: registers lists (evidence: `src/backend/defaults/natives/mod.rs`)
- Native methods → Strings: registers strings (evidence: `src/backend/defaults/natives/mod.rs`)