From 6cda69044a616196aeb1e4fdd1701f38dfe1191a Mon Sep 17 00:00:00 2001 From: Klesti Selimaj Date: Fri, 3 Jul 2026 10:14:43 +0200 Subject: [PATCH] Single file doc --- content/docs/components/classes.mdx | 135 -- content/docs/components/enums.mdx | 87 -- content/docs/components/functions.mdx | 102 -- content/docs/components/modules-imports.mdx | 85 -- .../docs/components/pointers-references.mdx | 67 - content/docs/components/structs.mdx | 84 -- content/docs/components/traits.mdx | 70 - content/docs/logic/control-flow.mdx | 115 -- content/docs/logic/expressions.mdx | 142 --- content/docs/logic/variables.mdx | 77 -- content/docs/meta.json | 16 +- docs.md | 1131 +++++++++++++++++ 12 files changed, 1132 insertions(+), 979 deletions(-) delete mode 100644 content/docs/components/classes.mdx delete mode 100644 content/docs/components/enums.mdx delete mode 100644 content/docs/components/functions.mdx delete mode 100644 content/docs/components/modules-imports.mdx delete mode 100644 content/docs/components/pointers-references.mdx delete mode 100644 content/docs/components/structs.mdx delete mode 100644 content/docs/components/traits.mdx delete mode 100644 content/docs/logic/control-flow.mdx delete mode 100644 content/docs/logic/expressions.mdx delete mode 100644 content/docs/logic/variables.mdx create mode 100644 docs.md diff --git a/content/docs/components/classes.mdx b/content/docs/components/classes.mdx deleted file mode 100644 index 90a3a84..0000000 --- a/content/docs/components/classes.mdx +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: Classes -description: Unified data and behavior with Java-style organization and Rust-powered execution. -icon: Shapes ---- - -Classes in Mist bridge the gap between Java's organizational structure and Rust's performance. They group fields, constructors, and methods within a single cohesive block, using C-style method signatures with `&self` for the instance parameter. - -## Basic Syntax - -A class groups fields and methods together. Fields use semicolons and the `Type name` convention. Methods use C-style syntax with `&self` as the first parameter for shared access. - -```mist -pub class Logger { - String prefix; - - pub void info(&self, message str&) { - self.log(LogLevel::Info, message); - } - - void log(&self, LogLevel level, message str&) { - println!("{level} {} {}", self.prefix, message); - } -} -``` - -## The Constructor - -Mist uses the explicit `constructor` keyword for initialization: - -```mist -pub constructor() { - self.prefix = "default".to_string(); -} -``` - -Constructors can take parameters: - -```mist -pub constructor(String prefix) { - self.prefix = prefix; -} -``` - -## Instance Methods & `&self` - -Methods use `&self` (shared reference) or `&mut self` (mutable reference) as the first parameter. - -```mist -pub void warning(&self, message str&) { - self.log(LogLevel::Warning, message); -} - -pub void reset(&mut self) { - self.prefix = String::new(); -} -``` - -## Inheritance - -Classes support single inheritance with the `:` syntax. Use `super = Super::new()` in the constructor to call the parent constructor. Override methods by placing `override(Parent)` after the parameter list. - -```mist -pub class Animal { - pub String name; - - constructor() { - self.name = "Rex".to_string(); - } - - pub String speak(&self) { - "Unknown".to_string() - } -} - -pub class Dog : Animal { - constructor() { - super = Super::new(); - } - - pub String speak(&self) override(Animal) { - "Woof!".to_string() - } -} -``` - -## Trait Implementations - -Traits can be implemented directly inside a class body: - -```mist -pub class Dog : Animal { - constructor() { - self.name = name; - } - - pub String speak(&self) override(Animal) { - "Woof!".to_string() - } - - impl std::fmt::Display { - Result<(), std::fmt::Error> fmt(&self, std::fmt::Formatter<'_> mut& f) { - write!(f, "🐾 {}", self.name) - } - } -} -``` - -## Generics - -Classes support generic type parameters: - -```mist -pub class Container { - T value; - - constructor(T val) { - self.value = val; - } - - pub &T get(&self) { - &self.value - } -} -``` - -## Key Characteristics - -- **Unified Scope**: Data and behavior live in one class block. -- **C-Style Methods**: Return type before name β€” no `fn` keyword. -- **`&self` Parameter**: The self reference is explicit and uses `&` syntax. -- **Inheritance**: Single inheritance with `override(Parent)` for polymorphic dispatch. -- **Encapsulation**: Visibility modifiers (`pub`) control API exposure. -- **Inline Impl**: Traits can be implemented directly within the class body. -- **Zero-Cost Classes**: Under the hood, Mist desugars these into idiomatic Rust structs and implementation blocks. diff --git a/content/docs/components/enums.mdx b/content/docs/components/enums.mdx deleted file mode 100644 index cd26c50..0000000 --- a/content/docs/components/enums.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Enums -description: Defining algebraic data types with Mist's type-first convention. -icon: Layers ---- - -Enums in Mist serve as powerful algebraic data types (ADTs), maintaining the exact behavior and safety of Rust enums while using parentheses for tuple variants and `Type name` for struct-like fields. - -## Basic Syntax - -An enum can contain unit variants, tuple variants (with types in parentheses), or struct-like variants. - -```mist -pub enum TaskState { - Pending, - InProgress, - Completed, - Failed { - String reason, - i32 code, - }, -} -``` - -## Variant Types - -Mist supports all standard variant shapes: - -```mist -enum OptionInt { - None, // Unit - Some(i32), // Tuple (parentheses) -} - -enum Shape { - Circle { i32 radius }, // Struct-like - Rect { i32 w, i32 h }, -} -``` - -### Instantiation & Matching - -Tuple variants are created and matched with parentheses: - -```mist -let x = OptionInt::Some(42); - -match x { - OptionInt::None => { println!("none"); } - OptionInt::Some(v) => { println!("{}", v); } -} -``` - -Struct variants use brace notation: - -```mist -let c = Shape::Circle { - radius: 5, -}; - -match c { - Shape::Circle { radius } => { println!("{}", radius); } - Shape::Rect { .. } => { /* ignore */ } -} -``` - -## Generics - -Enums declare generics and lifetimes in angle brackets after the name. - -```mist -pub enum Validation<'a, T> { - Valid(T), - Invalid { - &'a str message, - u32 error_id, - }, -} -``` - -## Key Characteristics - -- **Consistent Declaration**: Struct-like variants use `Type name` order, consistent with Mist structs. -- **Parentheses Tuples**: Tuple variants use `()` syntax, consistent with Rust. -- **Rust-Native ADTs**: Enums compile directly to Rust enums, allowing exhaustive pattern matching and zero-cost abstraction. -- **Shared Visibility**: The `pub` modifier at the enum level exports all variants. -- **Comma-Separated Members**: Fields within struct-like variants are separated by commas. diff --git a/content/docs/components/functions.mdx b/content/docs/components/functions.mdx deleted file mode 100644 index ab90cec..0000000 --- a/content/docs/components/functions.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Functions -description: Defining execution blocks with C-style ergonomics and Rust-powered safety. -icon: SquareFunction ---- - -Functions are the primary unit of execution in Mist, using C-style syntax with the return type before the name. The last expression in a block is implicitly returned. - -## Basic Syntax - -Functions place the return type before the name, followed by parameters in parentheses. - -```mist -void greet() { - println!("Hello!"); -} - -i32 add(i32 a, i32 b) { - a + b -} -``` - -## Visibility & Modules - -Functions use `pub` for public visibility. Files declare a module with `pub module name;`. - -```mist -pub module utils; - -pub i32 get_version() { - 1 -} - -pub void process() { - // ... -} -``` - -## Mutable Parameters - -Use `mut` after the type to allow reassignment within the function body. - -```mist -void update_score(i32 mut current_score, i32 bonus) { - current_score = current_score + bonus; -} -``` - -## Methods & `&self` - -Methods take `&self` (immutable) or `&mut self` (mutable) as the first parameter. - -```mist -struct Counter { - i32 value, -} - -impl Counter { - pub i32 get(&self) { - self.value - } - - pub void increment(&mut self) { - self.value += 1; - } -} -``` - -## Closures - -Closures are anonymous functions defined with arrow syntax: - -```mist -let add = (a, b) => a + b; -add(2, 3); - -// With a block body -let greet = (name str&) => { - println!("Hello {}", name); -}; -``` - -## Attributes & Metadata - -Metadata is applied via the `#[attr]` syntax directly above the declaration. - -```mist -#[inline] -pub i32 clamp(i32 value, i32 min, i32 max) { - if value < min { min } - else if value > max { max } - else { value } -} -``` - -## Key Characteristics - -- **C-Style Syntax**: Return type before name β€” no `fn` keyword. -- **Implicit Returns**: The final expression in a block is automatically returned. -- **`&self` / `&mut self`**: Explicit self parameter in method definitions. -- **Closure Support**: Arrow syntax `(params) => expr` for anonymous functions. -- **Zero-Cost Mapping**: Every function maps directly to a Rust `fn`. diff --git a/content/docs/components/modules-imports.mdx b/content/docs/components/modules-imports.mdx deleted file mode 100644 index 488538a..0000000 --- a/content/docs/components/modules-imports.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Modules & Imports -description: Organizing code across files with module declarations and path-based imports. -icon: FolderTree ---- - -Mist organizes code through a file-system based module system with explicit path imports. - -## Module Declarations - -Each `.mist` file declares itself as a module with `pub module name;` at the top. A `package.mist` file acts like `mod.rs` β€” it is the entry point for its directory. - -```mist -// src/utils/helper.mist -pub module helper; - -pub void greet() { - println!("Hello!"); -} -``` - -```mist -// src/utils/package.mist -pub module utils; -// This module exports submodules and items -``` - -## Imports - -Use the `use` keyword with a path to bring items from other modules or external crates into scope. - -```mist -use std::fs; -use std::process; -use std::path::Path; -use std::collections::HashMap; - -// Import specific items -use my_module::Helper; -``` - -### Visibility - -Items can be re-exported with a visibility modifier on the import: - -```mist -pub use internal::format; -``` - -## Sidefiles - -Any non-`.mist` file in `src/` (e.g., `.rs`, `.toml`, data files) is treated as a **sidefile** β€” it is copied directly into the output directory `.mist/src/` during transpilation. This allows you to keep Rust helper files or configuration alongside your Mist source. - -```text -src/ -β”œβ”€β”€ main.mist -β”œβ”€β”€ helper.rs # copied to .mist/src/helper.rs -└── config/ - └── data.json # copied to .mist/src/config/data.json -``` - -## Project Structure - -A typical Mist project looks like this: - -``` -my-project/ -β”œβ”€β”€ Cargo.toml -β”œβ”€β”€ Mist.toml -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ main.mist -β”‚ β”œβ”€β”€ my_api/ -β”‚ β”‚ β”œβ”€β”€ package.mist -β”‚ β”‚ β”œβ”€β”€ methods.mist -β”‚ β”‚ └── utils.mist -└── .mist/ - └── src/ - β”œβ”€β”€ main.rs - └── my_api/ - β”œβ”€β”€ mod.rs - β”œβ”€β”€ methods.rs - └── utils.rs -``` - -The `.mist/src/` directory contains the transpiled Rust output. diff --git a/content/docs/components/pointers-references.mdx b/content/docs/components/pointers-references.mdx deleted file mode 100644 index 31a264a..0000000 --- a/content/docs/components/pointers-references.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Pointers & References -description: Explicit memory access with postfix reference syntax and Rust-native safety. -icon: MousePointer2 ---- - -Mist uses a postfix `&` syntax for reference types. While familiar from C++, these references adhere strictly to Rust's ownership and borrowing rules. - -## Basic Syntax - -Reference types are written with `&` after the type. Use `mut&` for mutable references. The `&` and `&mut` operators create references from values. - -```mist -i32 x = 42; -i32& r = &x; - -let mut y = 42; -i32 mut& r = &mut y; -*r = 100; -``` - -In function parameters: - -```mist -void increment(i32 mut& value, i32& limit) { - if *value < *limit { - *value = *value + 1; - } -} -``` - -## Lifetimes - -Lifetimes are placed before the type in the `&` suffix: - -```mist -pub struct Inspector<'a> { - &'a str target, - &'a mut u32 counter, -} -``` - -## In Classes - -Methods use `&self` for immutable access and `&mut self` for mutable access: - -```mist -pub class Logger { - String prefix; - - pub void info(&self, message str&) { - println!("{}", message); - } - - pub void reset(&mut self) { - self.prefix = String::new(); - } -} -``` - -## Key Characteristics - -- **Postfix Reference Syntax**: `T&` for shared references, `T mut&` for mutable references. -- **Explicit Intent**: The `mut&` syntax clearly distinguishes read-only from writable references. -- **Visual Consistency**: Lifetimes (`'a`) are placed before the type in `&'a T`. -- **Safety Guaranteed**: The Mist compiler enforces Rust's borrow checker. -- **Zero Overhead**: Mist references compile to identical machine code as Rust references. diff --git a/content/docs/components/structs.mdx b/content/docs/components/structs.mdx deleted file mode 100644 index 8bb1901..0000000 --- a/content/docs/components/structs.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Structs -description: Data modeling with Mist's type-first field convention. -icon: Form ---- - -Structs in Mist follow the same structural logic as Rust, with fields using the language-wide `Type name` convention and comma-separated grouping. - -## Basic Syntax - -A struct is defined by its name followed by a block of fields. Each field places the type before the identifier. - -```mist -pub struct Task { - pub String name, - pub TaskState state, - pub i32 executions, -} -``` - -## Visibility - -Use the `pub` modifier to make the struct or its individual fields accessible from other modules. - -```mist -pub struct NetworkNode { - pub u32 id, - str& address, -} -``` - -## Instantiation - -Structs are instantiated using standard brace syntax. - -```mist -let task = Task { - name: "Initialize".to_string(), - state: TaskState::Pending, - executions: 0, -}; -``` - -## Mutation - -Use `let mut` to allow field reassignment. - -```mist -let mut p = Point { - x: 1, - y: 2, -}; -p.x = 100; -``` - -## Destructuring - -Struct patterns use `let` with the struct name and field bindings: - -```mist -let p = Point { - x: 3, - y: 4, -}; -let Point { x, y } = p; -``` - -## Generics - -Generics and lifetimes are declared in angle brackets after the struct name. - -```mist -pub struct Buffer<'a, T> { - &'a T data, - usize len, -} -``` - -## Key Characteristics - -- **Type-First Declaration**: Fields use `Type name` order, consistent with function parameters and variable declarations. -- **Comma-Separated Members**: Fields are separated by commas, maintaining a clean delimiter style. -- **Rust Compatibility**: Maps 1:1 to Rust structs, ensuring zero-cost abstraction and full ecosystem interoperability. -- **Direct Visibility**: The `pub` modifier controls access at the struct and field level. diff --git a/content/docs/components/traits.mdx b/content/docs/components/traits.mdx deleted file mode 100644 index 5fe5af3..0000000 --- a/content/docs/components/traits.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Traits -description: Defining shared behavior and contracts with Mist's signature ergonomics. -icon: Sparkles ---- - -Traits in Mist define a set of methods that a type must implement, facilitating polymorphism and shared behavior. Method signatures use C-style syntax with `&self` for the instance parameter. - -## Defining a Trait - -A trait lists method signatures using return-type-first syntax, with `&self` as the instance parameter. - -```mist -pub trait Drawable { - void draw(&self); - str& metadata(&self); -} -``` - -## Implementing a Trait - -Use `impl Trait for Type` to provide implementations: - -```mist -impl Drawable for Task { - void draw(&self) { - println!("Drawing task: {}", self.name); - } - - str& metadata(&self) { - self.name - } -} -``` - -## Default Implementations - -Traits can provide default behavior for methods that implementing types may override: - -```mist -pub trait Identifiable { - u32 get_id(&self); - - bool is_valid(&self) { - self.get_id() > 0 - } -} -``` - -## Super-traits - -A trait can require another trait using the colon `:` syntax: - -```mist -pub trait Speak { - String speak(&self); -} - -pub trait Greet : Speak { - String greet(&self); -} -``` - -## Key Characteristics - -- **C-Style Signatures**: Return type before name β€” no `fn` keyword. -- **Explicit Context**: Methods use `&self` as the first parameter, mapping directly to Rust's reference rules. -- **Default Methods**: Traits can provide default implementations. -- **Super-traits**: Colon syntax for expressing trait requirements. -- **Static Dispatch**: By default, Mist traits leverage Rust's zero-cost generics and monomorphization. diff --git a/content/docs/logic/control-flow.mdx b/content/docs/logic/control-flow.mdx deleted file mode 100644 index 9ea8f48..0000000 --- a/content/docs/logic/control-flow.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Control Flow -description: Directing execution with expression-based logic, pattern matching, and traditional loop structures. -icon: Split ---- - -Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. Conditions do not require parentheses, and blocks support expression bodies. - -## Conditionals - -The `if` statement evaluates a boolean expression without parentheses: - -```mist -if score > 50 { - println!("Pass"); -} else if score == 50 { - println!("Borderline"); -} else { - println!("Fail"); -} - -// Expression body (implicit return) -let result = if valid { "ok" } else { "err" }; -``` - -## Match - -The `match` statement provides exhaustive pattern matching with support for multiple patterns per arm via `|`: - -```mist -match task_state { - TaskState::Pending => { println!("Queued"); } - TaskState::Failed { reason, code } => { - println!("Error {}: {}", code, reason); - } - TaskState::NotResponding | TaskState::Progress => { - draw_loading(); - } - _ => { println!("Other state"); } -} -``` - -Patterns support destructuring, or-patterns, and wildcards: - -```mist -let x = 2; -let result; - -match x { - 1 => { result = 10; } - 2 => result = 20, - 3 => { result = 30; } - _ => panic!(); -} -``` - -## Loops - -### Loop - -An infinite loop construct: - -```mist -loop { - println!("forever"); - if done { break; } -} -``` - -### For-In Loop - -For loops iterate over an expression using `for pattern in expr` syntax: - -```mist -for i in 0 .. 4 { - sum += i; -} - -// With pattern destructuring -for (k, _) in pairs { - keys += k; -} - -// With range variable -let r = 0 .. 5; -for i in r { - count++; -} -``` - -### While Loop - -```mist -while count < 5 { - count++; -} - -while active { - wait_for_event(); -} -``` - -## Jump Statements - -- **`return`**: Exits the current function, optionally passing back a value. -- **`break`**: Terminates the innermost looping construct. -- **`continue`**: Skips the remainder of the current loop iteration. - -## Key Characteristics - -- **No Parentheses**: Conditions in `if`, `while`, and `match` do not require parentheses. -- **Implicit Returns**: Expression bodies implicitly return their value. -- **Pattern Integration**: Loops and match arms utilize Mist's pattern system for data destructuring. -- **Multiple Patterns**: Match arms support `|` for matching multiple patterns. -- **Expression `if`**: `if/else` blocks can be used as expressions. diff --git a/content/docs/logic/expressions.mdx b/content/docs/logic/expressions.mdx deleted file mode 100644 index 5dd9e1e..0000000 --- a/content/docs/logic/expressions.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Expressions -description: The building blocks of logic, from literals to complex postfix chains. -icon: Binary ---- - -Expressions in Mist are the fundamental units that evaluate to a value. The syntax follows a clean **prefix -> primary -> postfix** chain, providing a predictable structure. - -## Primary Expressions - -Primary expressions are the starting point of any logic chain. These include literal values, paths to members, tuples, arrays, and basic statements. - -```mist -let x = 42; -let pi = Math::PI; -let coordinates = (10, 20, 30); -``` - -## Postfix Operations - -Postfix expressions allow you to build on a primary value with field access, calls, indexing, type casting, error propagation, and mutation operators. - -```mist -let len = list.length(); -s.len(); -s.to_uppercase(); - -let task = Task { - name: "Drafting", - priority: 1, -}; - -let first = items[0]; -println!("Value: {}", first); -``` - -### Increment & Decrement - -```mist -let mut i = 0; -i++; -i--; -``` - -### Compound Assignments - -```mist -i += 10; -i -= 5; -i *= 2; -i /= 3; -value &= mask; -flags |= 0x01; -``` - -### Type Casting - -Use `as` to convert between compatible types: - -```mist -let x = 42; -let y = x as f64; -``` - -### Try Operator - -Propagate errors with the `?` postfix operator: - -```mist -let content = fs::read_to_string(path)?; -``` - -### Range Operators - -Ranges use spaced `..` syntax: - -```mist -0 .. 10 // exclusive range (0 to 9) -0 ..= 10 // inclusive range (0 to 10) -``` - -### Arrays - -Arrays are initialized with brackets, with an optional repeat notation: - -```mist -let arr = [1, 2, 3]; -let zeros = [0; 10]; // ten zeroes -``` - -## Prefix Operations - -Prefixes modify the primary expression that follows them β€” dereference, reference, negation, and logical not. - -```mist -let mut value = 10; - -let ref = &value; -let mref = &mut value; -let val = *ref; -let is_false = !true; -let neg = -42; -``` - -## Binary Operations - -```mist -let sum = 10 + 20; -let is_equal = (x == y); -let complex = (a + b) * (c / d); -``` - -## Closures - -Closures use arrow syntax with optional type annotations: - -```mist -let add = (a, b) => a + b; -let greet = (name str&) => { - println!("Hello {}", name); -}; -``` - -## Operator Table - -| Category | Operators | -| -------------- | ---------------------------------------------------------------- | -| **Arithmetic** | `+`, `-`, `*`, `/`, `%` | -| **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=` | -| **Logical** | `&&`, `||` | -| **Bitwise** | `<<`, `>>`, `&`, `\|`, `^` | -| **Range** | `..`, `..=` | -| **Assign** | `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=` | - -## Key Characteristics - -- **Predictable Chaining**: The `prefix* ~ primary ~ postfix*` grammar ensures complex expressions are parsed consistently. -- **Rust-Style References**: Expressions use `&` and `&mut` to create references, maintaining borrow checker compatibility. -- **Macro Integration**: Macros use `!` as a postfix operation. -- **Type Casting**: `as Type` provides explicit type conversion at the expression level. -- **Error Propagation**: The `?` operator enables early returns for `Result`/`Option` types. -- **Arrow Closures**: `(params) => expr` for concise anonymous functions. diff --git a/content/docs/logic/variables.mdx b/content/docs/logic/variables.mdx deleted file mode 100644 index a0b333d..0000000 --- a/content/docs/logic/variables.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: Variables -description: Local state management with type inference and explicit mutability. -icon: Variable ---- - -Variables in Mist support two declaration styles: inferred typing with `let` and explicit type annotation. Like Rust, variables are immutable by default. - -## Basic Declaration - -Use `let` for automatic type inference: - -```mist -let x = 42; -let greeting = "Hello Mist"; -let s = "hello, world!"; -``` - -## Explicit Typing - -Type annotations are placed before the name: - -```mist -i32 x = 42; -bool is_active = true; -str& name = "mist"; -f64 pi = 3.14; -``` - -## Mutability - -To allow a variable to be reassigned, use `let mut`: - -```mist -let mut score = 0; -score = 100; -``` - -Or with explicit typing: - -```mist -i32 mut counter = 0; -counter = 10; -``` - -## Strings - -String references use `str&` for a natural left-to-right read: - -```mist -str& name = "mist"; -str& greeting = "Hello"; -``` - -## Arrays - -```mist -let list = [1, 2, 3]; // Standard init -let zeros = [0; 10]; // Repeat notation: ten zeroes -``` - -## Pattern Destructuring - -Tuples are destructured using parentheses: - -```mist -let (a, b) = (10, "hello"); -let (a, (b, c)) = (1, (2, 3)); -``` - -## Key Characteristics - -- **Dual Declaration Styles**: `let` for inference, `Type name` for explicit typing. -- **Safety First**: Immutability by default prevents accidental state changes. -- **Zero-Cost Inference**: Type inference is handled entirely at compile time. -- **Shadowing**: Mist supports variable shadowing within the same scope. -- **`str&` Notation**: String references use postfix `&` for clear left-to-right reading. diff --git a/content/docs/meta.json b/content/docs/meta.json index 13a5b01..7be92bd 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -3,20 +3,6 @@ "---[Rocket]Introduction---", "index", "philosophy", - "limitations", - - "---[Box]Components---", - "components/functions", - "components/structs", - "components/enums", - "components/classes", - "components/traits", - "components/pointers-references", - "components/modules-imports", - - "---[ArrowDownUp]Logic---", - "logic/variables", - "logic/control-flow", - "logic/expressions" + "limitations" ] } diff --git a/docs.md b/docs.md new file mode 100644 index 0000000..3cabe0e --- /dev/null +++ b/docs.md @@ -0,0 +1,1131 @@ +# Mist Language Documentation + +## Introduction + +Mist is a pragmatic systems programming language that compiles directly to Rust. It provides C/C++-style syntax with zero-cost abstractions, full interoperability with the Rust ecosystem, and additional language features like classes with inheritance. + +The compiler is written in Rust and Mist itself, and is organized into four main crates: + +- **mist-parser** β€” Parses Mist source code into an AST using pest +- **mist-codegen** β€” Generates Rust code from the Mist AST +- **mist-analyzer** β€” Language server built on top of rust-analyzer +- **mist-api** β€” Mist crate that orchestrates transpilation and building + +--- + +## Installation + +```bash +cargo install mist-lang +``` + +This installs the `mist` CLI binary and the `mist-analyzer` LSP binary. + +--- + +## Project Structure + +A Mist project requires the following structure: + +``` +my-project/ +β”œβ”€β”€ Mist.toml # Project configuration +β”œβ”€β”€ Cargo.toml # Standard Rust Cargo.toml (managed by mist) +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ main.mist # Entry point (or lib.mist for libraries) +β”‚ └── ... # Other .mist source files +└── .mist/ + └── src/ # Generated Rust output (do not edit) +``` + +### Mist.toml + +```toml +package = "main.mist" # Entry point file (relative to src/) +packages = ["utils"] # Subdirectories to treat as sub-modules +include = ["crates/*"] # Additional Mist crates to transpile +``` + +The `packages` field lists subdirectories under `src/` that should be treated as child modules. Each such directory should contain a `package.mist` file acting as the module root. + +The `include` field supports glob patterns for including external Mist crates. A trailing `*` treats all immediate subdirectories that contain a `Mist.toml` as independent crates. + +--- + +## CLI Commands + +| Command | Short | Description | +|------------------|-------|---------------------------------| +| `mist run` | `r` | Run the project | +| `mist build` | `b` | Build the project | +| `mist check` | `c` | Check without building | +| `mist test` | | Run tests | +| `mist publish` | | Publish the project | +| `mist bench` | | Benchmark the project | +| `mist doc` | | Build documentation | +| `mist fix` | | Auto-fix warnings | +| `mist clippy` | | Lint the project | +| `mist clean` | | Clean build artifacts | +| `mist transpile` | `t` | Transpile Mist to Rust only | +| `mist init` | | Init a project in current dir | +| `mist new` | | Create a new project | +| `mist version` | `-v` | Print compiler version | +| `mist help` | `-h` | Print usage information | + +All Cargo subcommands delegate to `cargo` with Mist error remapping. + +--- + +## Language Syntax + +### Comments + +```mist +// Line comments only +``` + +### Literals + +```mist +42 // Integer +3.14 // Float +true // Boolean +false // Boolean +"hello" // String +(1, true, "x") // Tuple +``` + +### Identifiers & Keywords + +Keywords are reserved and cannot be used as identifiers: + +`if`, `else`, `fn`, `for`, `while`, `match`, `return`, `break`, `continue`, `struct`, `enum`, `class`, `trait`, `impl`, `use`, `pub`, `mut`, `let`, `true`, `false`, `dyn`, `loop`, `unsafe`, `override`, `const`, `type` + +Identifiers follow the pattern `[a-zA-Z_][a-zA-Z0-9_]*`. + +--- + +### Variables + +```mist +let x = 42; // Type-inferred immutable +let mut y = 10; // Mutable variable +i32 z = 100; // Explicit type annotation +str& s = "hello"; // Typed string reference +bool b = true; // Typed boolean +f64 f = 3.14; // Typed float +let (a, b) = (1, "two"); // Destructuring +let (x, (y, z)) = (1, (2, 3)); // Nested destructuring +``` + +Variable declarations follow either of two forms: + +```mist +let [= ]; + [= ]; +``` + +--- + +### Functions + +```mist +// Return type is `void` (unit) +void greet(str& name) +{ + println!("Hello, {name}"); +} + +// With return type +i32 add(i32 a, i32 b) +{ + return a + b; +} + +// Expression body (last expression is the return value) +i32 square(i32 x) +{ + x * x +} + +// Public function +pub i32 multiply(i32 a, i32 b) +{ + a * b +} + +// Generic function +T identity(T value) +{ + value +} + +// Unsafe function +unsafe i32 dangerous() +{ + 42 +} +``` + +Function syntax: `[pub] [void | ] []() [override] { }` + +Functions use **Allman brace style** (opening brace on the next line). + +### Self Parameter + +Methods can take `self`, `&self`, `&mut self`, or `self` with lifetimes: + +```mist +pub void set_value(&mut self, i32 v) +{ + self.value = v; +} +``` + +--- + +### Control Flow + +#### If/Else + +```mist +if condition { + // body +} else if other_condition { + // body +} else { + // body +} +``` + +Conditions must be parenthesized: `if (expr) { }` or `if expr_no_struct { }` (struct literals require parentheses). + +Used as an expression: + +```mist +let x = if true { 1 } else { 2 }; +``` + +#### While + +```mist +while condition { + // body +} +``` + +#### For + +```mist +for pattern in iterator { + // body +} + +for i in 0 .. 10 { + // body +} +``` + +#### C-Style For + +```mist +for (let mut i = 0; i < 10; i++) { + // body +} +``` + +#### Loop + +```mist +loop { + // infinite loop +} +``` + +#### Match + +```mist +match value { + pattern1 => expr, + pattern2 => { + // block body + } + pattern3 | pattern4 => expr, +} +``` + +#### Break/Continue + +```mist +break; +continue; +``` + +#### Return + +```mist +return; +return value; +``` + +--- + +### Types + +#### Type System + +```mist +i32 // Path type +str& // Reference type +&mut i32 // Mutable reference +&'a i32 // Reference with lifetime +*const i32 // Const pointer +*mut i32 // Mutable pointer +(i32, bool) // Tuple type +fn(i32) -> bool // Function pointer type +Fn(i32) -> bool // Closure trait (Fn) +FnMut(i32) -> bool // Closure trait (FnMut) +FnOnce(i32) -> bool // Closure trait (FnOnce) +dyn Trait // Trait object +void // Unit type (maps to Rust's ()) +'i32 // Type ascription not to be confused with lifetime +``` + +Type expressions can be composed: + +```mist +type_expr = { (void | path_type | tuple_type | dyn_type) ~ (unsafe_ref_type | ref_type | fn_type)* } +``` + +This means types are written left-to-right naturally: + +```mist +i32& // &i32 +i32&mut // &mut i32 +i32&'a // &'a i32 +i32 fn() -> bool // fn(i32) -> bool +``` + +#### Type Aliases + +```mist +type MyInt = i32; + +type Result = std::result::Result; +``` + +#### Const and Static + +```mist +const MAX: i32 = 100; +static NAME: str& = "hello"; +``` + +--- + +### Structs + +```mist +pub struct Point { + i32 x, + i32 y, +} + +pub struct Generic { + T value, +} +``` + +Fields can be public or private: + +```mist +struct User { + pub str& name, + i32 age, // private +} +``` + +--- + +### Enums + +```mist +pub enum Option { + Some(T), + None, +} + +pub enum Message { + Quit, + Move(i32, i32), + Write { str& content, i32 length }, +} +``` + +Enum variants can be: +- **Named** β€” `Variant` +- **Tuple** β€” `Variant(T1, T2)` +- **Struct** β€” `Variant { T1 field1, T2 field2 }` + +--- + +### Traits + +```mist +pub trait Drawable { + void draw(&self); +} + +pub trait Comparable : Eq { + i32 cmp(&self, T other); +} +``` + +Trait requirements are specified after `:`: + +```mist +trait MyTrait : SuperTrait + OtherTrait { + void required_method(&self); + void another(&self); +} +``` + +--- + +### Impl Blocks + +```mist +impl MyType { + void method(&self) { } +} + +impl Trait for MyType { + void method(&self) { } +} + +impl GenericTrait for MyType { + void method(&self, T value) { } +} +``` + +--- + +### Classes + +Mist introduces `class` as syntactic sugar for a Rust struct with a virtual method table (vtable). + +```mist +pub class Animal { + str& name, + + pub constructor(str& name) + { + self.name = name; + } + + pub void speak(&self) + { + println!("..."); + } +} +``` + +Class fields can have default initializers: + +```mist +class Player { + i32 health = 100, + str& name, +} +``` + +#### Inheritance + +```mist +class Dog : Animal { + pub constructor(str& name) + { + super(name); + } + + override void speak(&self) + { + println!("Woof!"); + } +} +``` + +The `override` keyword supports explicit base class targeting: + +```mist +override(Animal) void speak(&self) +{ + println!("Woof!"); +} +``` + +#### Under the Hood + +A class `Dog : Animal` generates: + +1. A Rust struct with a `_super: Animal` field (or `_vptr: &'static [*const c_void]` for root classes) +2. A vtable constant with function pointers for each public method +3. An `impl` block with `Deref` and `DerefMut` +4. Method trampolines (`__m_`) that are dispatched through the vtable +5. A `new()` constructor that initializes via `MaybeUninit` and calls the user's `constructor(&mut self)` + +The vtable is unified: parent entries are copied, overridden entries replace parent slots, and new methods are appended. + +--- + +### Generics + +```mist +// Generic function +T id(T x) +{ + x +} + +// Generic struct +struct Pair { + A first, + B second, +} + +// Generic enum +enum Result { + Ok(T), + Err(E), +} + +// Generic with trait bounds +T max(T a, T b) +{ + if a > b { a } else { b } +} + +// Lifetime generics +void process<'a>(&'a str& data) +{ + // ... +} +``` + +Generic syntax uses `<` `>` delimiters. Lifetimes are prefixed with `'`. + +--- + +### Visibility + +```mist +// Private (default) +void internal() { } + +// Public +pub void external() { } + +// Public to specific path +pub(crate) void crate_only() { } +pub(super) void parent_only() { } +pub(in my::module) void module_only() { } +``` + +--- + +### Modules + +```mist +// Declare a submodule +pub module foo; + +// Import +use std::collections::HashMap; + +// Re-exporting import +pub use my_module::MyType; +``` + +#### Module Resolution + +Mist maps the module tree to Rust's module system: + +| Mist Path | Rust Output | +|------------------------------|------------------------------| +| `src/main.mist` | `.mist/src/main.rs` | +| `src/utils/package.mist` | `.mist/src/utils/mod.rs` | +| `src/foo.mist` | `.mist/src/foo.rs` | +| `src/utils/helper.mist` | `.mist/src/utils/helper.rs` | + +A `package.mist` file acts as a directory's module root, analogous to `mod.rs`. + +--- + +### Attributes + +Inner attributes apply to the containing module: + +```mist +#![allow(unused_variables)] +``` + +Outer attributes apply to the next item: + +```mist +#[derive(Debug, Clone)] +struct Point { + i32 x, + i32 y, +} + +#[test] +void my_test() +{ + assert_eq!(1, 1); +} +``` + +Attribute syntax: +- `#[path]` +- `#[path = literal]` +- `#[path(item1, item2, ...)]` + +--- + +### Patterns + +```mist +// Literal patterns +match x { + 1 => "one", + 2 => "two", + _ => "other", +} + +// Tuple patterns +let (a, b) = (1, 2); + +// Struct patterns +match value { + Point { x, y } => x + y, + Point { x: 0, y } => y, + _ => 0, +} + +// Named tuple patterns (newtype) +let MyType(value) = my_var; + +// Wildcard / etc +let _ = get_side_effect(); +match x { + 1 => ..., + .. => ..., // rest / etc +} + +// Mutable binding in pattern +let mut x = 42; +match ref_to_option { + Some(mut value) => value += 1, + None => {}, +} +``` + +--- + +### Operators + +#### Binary Operators + +| Operator | Description | +|----------|----------------------| +| `+` | Addition | +| `-` | Subtraction | +| `*` | Multiplication | +| `/` | Division | +| `%` | Modulus | +| `==` | Equality | +| `!=` | Inequality | +| `<` | Less than | +| `>` | Greater than | +| `<=` | Less or equal | +| `>=` | Greater or equal | +| `&&` | Logical AND | +| `\|\|` | Logical OR | +| `&` | Bitwise AND | +| `\|` | Bitwise OR | +| `^` | Bitwise XOR | +| `<<` | Left shift | +| `>>` | Right shift | +| `=` | Assignment | +| `+=` | Add assign | +| `-=` | Subtract assign | +| `*=` | Multiply assign | +| `/=` | Divide assign | +| `%=` | Modulus assign | +| `&=` | Bitwise AND assign | +| `\|=` | Bitwise OR assign | +| `^=` | Bitwise XOR assign | +| `<<=` | Left shift assign | +| `>>=` | Right shift assign | +| `..` | Range (exclusive) | +| `..=` | Range (inclusive) | +| `->` | Pointer write | + +#### Prefix Operators + +| Operator | Description | +|----------|-------------------| +| `*` | Dereference | +| `&` | Reference | +| `&mut` | Mutable reference | +| `!` | Logical NOT | +| `-` | Numeric negation | + +#### Postfix Operators + +| Operator | Description | +|------------|----------------------| +| `.field` | Field access | +| `.0` | Tuple field access | +| `()` | Function call | +| `[]` | Index | +| `{ f: v }` | Struct literal | +| `as Type` | Type cast | +| `?` | Try (error prop) | +| `++` | Increment | +| `--` | Decrement | +| `!()` | Macro call (paren) | +| `![]` | Macro call (bracket) | +| `!{}` | Macro call (brace) | + +--- + +### Macros + +Mist reuses Rust's macro system directly: + +```mist +println!("hello"); +assert_eq!(a, b); +vec![1, 2, 3]; +``` + +Macro calls use `!` followed by parentheses, brackets, or braces. + +--- + +### Closures + +```mist +let add = (a, b) => a + b; +let result = add(2, 3); // 5 + +let square = f64 x => x * x; +``` + +Closures can have explicit return types: + +```mist +let transform = i32 x => { + x * 2 +}; +``` + +--- + +### Attributes + +Mist supports Rust-style attributes at module and item level: + +```mist +#![crate_type = "lib"] + +#[derive(Clone)] +#[repr(C)] +pub struct External { } +``` + +--- + +## Compiler Architecture + +### Pipeline Overview + +The Mist compiler operates in distinct phases: + +``` +Source (.mist) + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Lexer β”‚ (pest PEG grammar) +β”‚ & Parser β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ AST + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Semantics β”‚ (field init checking) +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Codegen β”‚ (AST β†’ Rust source) +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ .rs + .map.json + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ cargo β”‚ (Rust compilation) +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + Binary / Library +``` + +### 1. Parsing (`mist-parser`) + +The parser is built with [pest](https://pest.rs), a PEG parser generator. Grammar rules are defined in `grammar.pest` (693 rules). + +**Key files**: +- `grammar.pest` β€” PEG grammar defining the entire language syntax +- `src/parser/common/` β€” Parse rule β†’ AST conversions for expressions, statements, types, declarations +- `src/parser/items/` β€” Parse rule β†’ AST conversions for top-level items (structs, enums, classes, functions, traits, impls, attributes) +- `src/ast/` β€” AST node types (expr.rs, statement.rs, top_level.rs) +- `src/semantics.rs` β€” Semantic checks (e.g., ensuring all class fields are initialized in constructors) +- `src/error.rs` β€” Error types (PreAst parsing errors, Ast generation errors) +- `src/rev_mapper.rs` β€” Position mapping between Mist and Rust source + +**Parsing entry points**: + +```rust +// Parse a complete program +pub fn parse<'a>(source: &'a str) -> Result> + +// Parse only the module declaration +pub fn parse_module<'a>(source: &'a str) -> Result, ParseError<'a>> +``` + +#### Grammar Structure + +The grammar follows a layered approach: + +1. **Lexical rules** (silent) β€” `WHITESPACE`, `COMMENT`, `identifier`, `integer`, `float`, `string_lit` +2. **Primary expressions** β€” literals, paths, tuples, arrays, closures, control flow +3. **Term** β€” prefix operators + primary + postfix operators +4. **Expression** β€” terms joined by binary operators (via Pratt parser) +5. **Statements** β€” variable declarations, control flow (`if`, `while`, `for`, `match`, `loop`), blocks +6. **Top-level items** β€” functions, structs, enums, classes, traits, impls, type aliases, imports, module declarations, constants + +#### AST Structure + +The AST preserves source positions via `Spanned`: + +```rust +pub struct Spanned { + pub line: usize, + pub column: usize, + pub item: T, +} +``` + +Top-level items are wrapped as: + +```rust +pub struct TopLevel(pub Spanned, pub Vec); +``` + +Expressions use a fix-point representation for prefix/postfix operators: + +```rust +Expression::Fix { + initial: Box, + prefixes: Vec, + postfixes: Vec, +} +``` + +Binary expressions use Pratt parsing for correct precedence: + +```rust +Expression::Binary { + lhs: Box, + op: String, + rhs: Box, +} +``` + +All operators are left-associative with a single precedence level. + +### 2. Semantic Analysis (`mist-parser`) + +The semantic checker (`semantics.rs`) performs class field initialization analysis. When a class has a constructor, it verifies that every declared field is mutated (directly or indirectly via method calls) within the constructor body. + +**Key check**: `check_class_semantics()` β€” Collects all field names, then walks the constructor body tracking which identifiers are assigned. If any field is uninitialized, an error is reported. + +The mutability analysis (`GetMutability` trait) works by: +1. Collecting all identifiers that get `&mut` references +2. Tracking `self.field = value` patterns +3. Following method calls that might initialize fields +4. Ensuring all branches initialize the same fields (intersection semantics) + +### 3. Code Generation (`mist-codegen`) + +The code generator converts the Mist AST into Rust source code. It does not generate an intermediate representation β€” it produces Rust source text directly. + +**Key files**: +- `src/lib.rs` β€” `RustCodegen` struct with output buffer, indentation tracking, `Mapping` for position translation +- `src/top_level.rs` β€” Generates Rust for top-level items (structs, enums, traits, functions, impls, imports, type aliases, const/static) +- `src/statement.rs` β€” Generates Rust for statements and blocks +- `src/expr.rs` β€” Generates Rust for expressions (literals, paths, binary ops, closures, arrays, prefix/postfix) +- `src/class_decl.rs` β€” Class-specific code generation (struct + vtable + impl blocks + Deref) + +#### Codegen Design + +The `RustCodegen` maintains: +- A string `output` buffer +- An `indent` level (4 spaces per level) +- A `Mapping` that records `(RustMap, MistMap)` pairs for source position remapping +- A current `position` tracker (`RustMap(line, column)`) + +Generation follows the `GenRust` trait: + +```rust +pub trait GenRust { + fn gen_rust(&self, ctx: &mut Context, cg: &mut RustCodegen); +} +``` + +And `GetRust` for simple string-returning types: + +```rust +pub trait GetRust { + fn get_rust(&self) -> String; +} +``` + +The `Context` carries optional expression path information for class `super` / `Super` resolution. + +#### Class Codegen (detailed) + +Classes are the most complex codegen path. `ClassProcessedData` analyzes a class declaration and then emits: + +1. **Struct declaration** β€” `struct ClassName { pub _super: Parent, pub field1: T1, ... }` (or `_vptr` for root classes) + +2. **Vtable constants** β€” Index constants `__FN_METHOD` and a `__V_TABLE` static array of function pointers. For inherited classes, parent vtable entries are copied and overridden entries replaced. + +3. **Constructor** β€” `pub fn new(...) -> Self` that: + - Creates an uninitialized instance via `MaybeUninit::zeroed().assume_init()` + - Sets the vtable pointer + - Writes field defaults + - Calls `self.constructor(...)` + - Returns `this` + +4. **Method trampolines** β€” Public methods with `self` get wrapper functions `__m_method` that are stored in the vtable, plus virtual dispatch methods that look up the function pointer at runtime. + +5. **Override support** β€” Methods marked `override` are validated at compile time by generating test code that dereferences `&Self` to `&Target`, confirming the Deref chain works. + +6. **Deref impls** β€” `impl Deref for Child` and `DerefMut` for inherited classes. + +7. **Impl declarations** β€” Inner `impl` blocks are rewritten to use the self type. + +#### Mapping System + +The `rev_mapper` module provides bidirectional position mapping: + +```rust +pub struct Mapping { + pub mist_path: PathBuf, + pub map: HashSet<(RustMap, MistMap)>, +} +``` + +- `RustMap(usize, usize)` β€” line/column in generated Rust +- `MistMap(usize, usize)` β€” line/column in original Mist + +The mapping is populated during codegen via `GenSpanTranslation`: + +```rust +impl GenSpanTranslation for Spanned { + fn gen_span(&self, cg: &mut RustCodegen) { + cg.mapping.map.insert((cg.position, MistMap(self.line, self.column))); + } +} +``` + +This allows the builder to remap Rust compiler errors back to the original Mist source positions. + +### 4. Builder & Error Remapping (`mist-api`) + +The builder module (`builder.mist` in the `mist_api` crate) wraps `cargo` to: + +1. Spawn `cargo` with `--message-format=json` +2. Parse JSON compiler messages +3. For each diagnostic span, look up the corresponding `.map.json` file +4. Remap Rust line/column to Mist line/column using the mapping +5. Display errors/warnings with Mist source locations and context lines + +```rust +pub fn build(args: Vec, root: PathBuf) -> bool { + // Spawn cargo with JSON output + // Parse CompilerMessage for each span + // Look up rev_mapper::Mapping from .map.json + // Remap to Mist positions + // Print diagnostics +} +``` + +### 5. Transpilation Pipeline + +The transpiler (`transpiler.mist` in `mist_api`) orchestrates the full pipeline: + +1. Read `Mist.toml` configuration +2. Build a `Module` tree from the filesystem (discovering `package.mist` files) +3. For each module: + a. Parse Mist source + b. Run semantic checks + c. Generate Rust code and position mapping + d. Write `.rs` file and `.map.json` file +4. Recursively transpile included crates + +The `Module` struct represents the file-to-module mapping: + +```rust +pub class Module { + pub String name; + pub PathBuf path; + pub Vec children; + + pub constructor(PathBuf mist_path, MistConfig& config) { ... } + pub bool is_package(&self) { ... } + pub PathBuf output_dir(&self, PathBuf& parent_dir) { ... } + pub PathBuf output_path(&self, PathBuf& parent_dir, ...) { ... } +} +``` + +#### Transpilation Mapping Rules + +| Mist Source | Rust Output | +|-----------------|--------------------------------| +| `src/main.mist` | `.mist/src/main.rs` | +| `src/foo.mist` | `.mist/src/foo.rs` | +| `src/bar/package.mist` | `.mist/src/bar/mod.rs` | +| `src/bar/baz.mist` | `.mist/src/bar/baz.rs` | + +A `package.mist` file: +- Generates `mod.rs` in the output directory +- Contains `pub mod ;` declarations for its children +- Its own items are prepended to the output + +### 6. Caching + +The transpiler implements basic caching via file modification times: + +```rust +fn is_source_newer(source: &Path, output: &Path) -> io::Result { + if !output.exists() { return Ok(true); } + let source_time = fs::metadata(source)?.modified()?; + let output_time = fs::metadata(output)?.modified()?; + Ok(source_time > output_time) +} +``` + +If a source file has not changed since the last transpilation, the `.rs` file is not regenerated. + +--- + +## LSP Support (`mist-analyzer`) + +The Mist Language Server Protocol implementation runs a headless `rust-analyzer` instance and bridges Mist editor requests to Rust positions. + +### Architecture + +``` +Editor (LSP client) + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ mist-analyzer β”‚ +β”‚ (Rust + Mist) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ β–² + β”‚ JSON-RPC β”‚ + β–Ό β”‚ +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ rust-analyzer β”‚ +β”‚ (headless child) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Flow + +1. Editor sends Mist file edits to `mist-analyzer` via LSP +2. `mist-analyzer` transpiles Mist to Rust +3. The transpiled Rust is forwarded to the headless `rust-analyzer` process +4. For goto-definition, hover, and completion, a unique marker token is injected at the cursor position +5. The transpiled output with the marker is sent to `rust-analyzer` +6. The marker position is located in the response +7. Results are mapped back to Mist positions using the `rev_mapper` + +### Key Features + +- **Full document sync** β€” Open, change, save, close +- **Go to definition** β€” Maps through transpiled Rust positions +- **Completions** β€” Supports trigger characters `:`, `.`, `'`, `(` +- **Hover** β€” Type information and docs +- **Diagnostics** β€” Real-time errors from transpilation failures and Rust compilation +- **Formatting** β€” Document formatting support (currently passthrough) +- **Auto-import** β€” Automatically inserts `pub module ;` when new `.mist` files are created +- **File watching** β€” Monitors `**/*.mist` for new files + +### Diagnostic Remapping + +When a transpilation error occurs in the `mist-analyzer`: + +1. Parse errors are converted to `Diagnostic` with Mist source positions +2. Semantic errors (uninitialized class fields) use the stored line/column +3. Rust compiler errors are remapped via the `Mapping` system back to Mist positions + +--- + +## Semantic Checks + +### Field Initialization + +The primary semantic check ensures all class fields are initialized in the constructor: + +```mist +class Player { + i32 health, + str& name, + + pub constructor(str& name) + { + self.name = name; + // Error: field 'health' is uninitialized + } +} +``` + +The analysis tracks: +- Direct field assignment: `self.field = value` +- `&mut self.field` patterns +- Method calls that might initialize fields (transitively) +- All conditional branches must initialize the same fields +- `super` assignments count for `_super` field initialization + +--- + +## Position Mapping + +Mist maintains a bidirectional mapping between Mist source positions and Rust output positions. This is essential for: + +1. **Error remapping** β€” Rust compiler errors point to the correct Mist source location +2. **LSP features** β€” Go-to-definition, hover, and completion work from Mist source + +The mapping is stored as `HashSet<(RustMap, MistMap)>` pairs and serialized to `.map.json` files alongside the transpiled `.rs` output. + +### Mapping Lifecycle + +1. **Codegen** β€” Each `Spanned` AST node records its Mist position and the current Rust position in the codegen output buffer +2. **Persistence** β€” The mapping is written to `.map.json` +3. **Build-time remapping** β€” The builder reads `.map.json` to remap `cargo` diagnostics back to Mist positions +4. **LSP remapping** β€” Both Mistβ†’Rust and Rustβ†’Mist direction queries are supported via `find()` and `find_by_mist()`