Single file doc

2026-07-03 10:14:43 +02:00
parent 4c83f46326
commit 6cda69044a
12 changed files with 1132 additions and 979 deletions
@@ -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> {
    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.
@@ -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.
@@ -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`.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -3,20 +3,6 @@
        "---[Rocket]Introduction---",
        "index",
        "philosophy",
-        "limitations",
+        "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"
    ]
 }