Galfus Script

A small, efficient, highly modular interpreted scripting language built around typed source code, an in-memory module image, and a deterministic VM runtime.

Galfus Script is a programming language validating a compact, modular, VM-first scripting model. The compiler pipeline and VM interpreter are fully implemented and verified.

---

Table of Contents

• Status
• Core Features
• Memory Philosophy
• Repository Layout
• Virtual Standard Library
• Running and Testing Locally
• Design Goals
• Name Inspiration
• License

---

Status

The entire core execution pipeline is complete. You can parse, typecheck, compile, and run Galfus Script projects using the local VM runner.

.gfs Source Files (Workspace)
  └── Lexer & AST Parser
        └── Resolver (Scope & Name Resolution)
              └── Type Checker & Semantic Analyzer
                    └── Ownership Check
                          └── MIR Lowering (Structured IR)
                                └── Bytecode Emitter
                                       └── Galfus Module Image (in-memory)
                                                   └── VM Interpreter Execution

---

Core Features

Galfus Script implements a robust set of modern language features:

• Type Safety: Fully typed syntax with static type inference, validation of assignments, function calls, member accesses, and expression statements.
• Encapsulated Builtins: Strictly prevents user projects from referencing or declaring __builtin_* compiler intrinsics directly. These are visible only inside compiler-trusted builtin scopes.
• Structs: Rich struct declarations supporting inline initialization, member field access, and typed layouts.
• Dynamic Array Spreads: Array literal spread operators ([...arr1, ...arr2]) computed dynamically at runtime using custom Len and CopyArray VM instructions.
• Control Flow: Conditionals (if/else), loop jumps, and comparison operators.
• Workspace Linking: Cross-module resolution supporting local file imports, named imports, and exported declarations across multiple files.
• Deterministic Memory: Implementation of the custom anchor/edge ownership graph model.

---

Memory Philosophy

Galfus Script does not rely on a traditional global garbage collector or manual raw memory management. Instead, it utilizes an ownership model built on:

• Anchors: Roots that preserve value lifetime.
• Edges: Hard references connecting reachable values.
• Weak Observers: Non-owning references that are safely invalidated when the target value is released.

Values live as long as they are reachable from anchors through edges. When anchors or edges are removed, the affected graph fragments are released deterministically and cycle-safely at runtime.

---

Repository Layout

Galfus Script is structured as a cargo workspace containing the following crates:

galfus-script/
  ├── crates/
  │    ├── galfus-core/       # Shared IDs, diagnostics, spans, and primitive metadata
  │    ├── galfus-frontend/   # Lexer, parser, resolver, checker, and semantic validation
  │    ├── galfus-ir/         # MIR representation and VM lowering code
  │    ├── galfus-image/      # Bytecode format, validation, and in-memory module image layouts
  │    ├── galfus-runtime/    # Concurrency runtime, threads, loader, and registry
  │    ├── galfus-vm/         # Virtual Machine interpreter and ownership graph engine
  │    ├── galfus-jit/        # Just-in-Time compilation engine skeleton
  │    ├── galfus-target/     # Low-level target capabilities provider interface
  │    ├── galfus-builtins/   # Standard library builtins and rich_builtins files
  │    ├── galfus-runner/     # Workspace compilation pipeline and linker
  │    └── galfus-cli/        # CLI interface (Command Line Interface)
  └── examples/
       └── project/           # Sample workspace project with local main.gfs and config

---

Virtual Standard Library

A minimal virtual standard library is available to user scripts, including:

std/io

Offers basic console input/output interface:

• fn print(text: [u8]): null: Output a slice of u8 characters directly to the standard output.

---

Running and Testing Locally

1. Requirements

Ensure you have the latest Rust toolchain installed:

rustup update

2. Building the Project

Compile the workspace and CLI runner:

cargo build

3. Running the Example Project

Execute the sample workspace containing structures, array spreads, and control flow:

cargo run -- run examples/project

Expected output:

Hello Galfus!
Idade maior que 20
Program exited successfully with value: Null

4. Code & Semantic Auditing

Check the syntax and type checks of a single file:

cargo run -- check examples/project/src/main.gfs

Validate type-safety and semantics across the entire workspace directory:

cargo run -- check-workspace examples/project

5. Inspecting AST and Symbol Graph

Visualize AST nodes, scopes, references, and symbol tables:

cargo run -- graph examples/project/src/main.gfs

6. Executing Tests & Quality Checks

Run all unit and integration tests across the workspace:

cargo test --workspace

Ensure clippy checks and formattings are strictly clean:

cargo clippy --workspace --all-targets
cargo fmt --check

---

Design Goals

Galfus Script is designed from the ground up to be:

• VM-First: Bytecode and interpreter structures dictate the design, making the VM highly portable.
• Host-Friendly: Designed to easily embed in larger native applications (like game engines or databases).
• Deterministic: Standardized memory behavior, integer arithmetic, and strict execution paths.
• Explicit: Avoids magic conventions; imports, exports, and structures must be declared explicitly.

---

Name Inspiration

The name Galfus comes from Galafus, a figure from Pernambuco folklore associated with will-o'-the-wisp phenomena. The wandering flame represents a runtime that is:

• Small & Portable
• Present where needed
• Lightweight by default
• Able to float across hosts and environments

---

License

MIT