diff --git a/content/docs/components/functions.mdx b/content/docs/components/functions.mdx index 449deeb..0a6e85b 100644 --- a/content/docs/components/functions.mdx +++ b/content/docs/components/functions.mdx @@ -4,7 +4,7 @@ description: Defining execution blocks with C-style ergonomics and Rust-powered icon: SquareFunction --- -Functions are the primary unit of execution in Mist. They prioritize a traditional declaration order, placing the return type before the identifier to ensure signatures remain easy to scan in complex systems. +Functions are the primary unit of execution in Mist. They prioritize a traditional declaration order, placing the return type before the identifier. ## Basic Syntax @@ -28,18 +28,15 @@ Functions are private to their module by default. The `pub` modifier exports the pub i32 get_version() { return 1; } -``` -You can also point to a specific point (super or crate, or a custom path): -```mist -pub(crate) i32 get_version() { - return 1; +pub(crate) i32 internal_use() { + return 0; } ``` ## Mutable Parameters -Parameters follow Rust’s ownership rules but use Mist’s local variable syntax. Use `mut` to allow a function to modify its local binding of a value. +Use `mut` to allow a function to modify its local binding of a value. ```mist void update_score(i32 mut current_score, i32 bonus) { @@ -58,9 +55,23 @@ pub str'a* choose_longer<'a, T: Display>(str'a* s1, str'a* s2, T meta) { } ``` +## Closures + +Closures are anonymous functions that can capture their environment. The return type before the pipe is optional — when omitted, the closure body uses curly braces: + +```mist +var add = |i32 a, i32 b| { a + b }; + +// With explicit return type +Option |var v| { Some(v) } + +// Without return type +var greet = |str* name| { println!("Hello {}", name) }; +``` + ## Attributes & Metadata -Metadata is applied via the `#[attr]` syntax directly above the declaration for compiler hints or testing. +Metadata is applied via the `#[attr]` syntax directly above the declaration. ```mist #[inline] @@ -71,6 +82,7 @@ pub bool is_active(u32 id) { ## Key Characteristics -* **Scannable Signatures:** Placing return types first allows for rapid identification of a function's output. -* **Unified Abstraction:** Lifetimes and type constraints are declared in one location, reducing signature noise. -* **Zero-Cost Mapping:** Every function maps directly to a Rust `fn`, maintaining performance and ecosystem compatibility. \ No newline at end of file +- **Scannable Signatures**: Return types first for rapid identification of a function's output. +- **Unified Abstraction**: Lifetimes and type constraints are declared in one location. +- **Closure Support**: Anonymous functions with optional return type annotations. +- **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 new file mode 100644 index 0000000..0824c95 --- /dev/null +++ b/content/docs/components/modules-imports.mdx @@ -0,0 +1,81 @@ +--- +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, similar to Rust but with a cleaner import syntax. + +## The Module System + +Each `.mist` file in `src/` corresponds to a module. The module tree mirrors the file hierarchy. Directories can be declared as submodules using `mod`. + +### File-Based Modules + +The file `src/main.mist` is the crate root. Other files are discovered through `mod` declarations or by name — no explicit declaration is needed when a file exists at a matching path. + +### Declaring Submodules + +```mist +// src/main.mist +mod network; +mod database; +``` + +## Imports + +Use the `use` keyword with angle brackets to bring items from other modules or external crates into scope. + +```mist +use ; +use ; +use ; +use ; + +// Import specific items +use ; +``` + +### Visibility + +Items can be re-exported with a visibility modifier on the import: + +```mist +pub use ; +``` + +## 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 +├── src/ +│ ├── main.mist +│ ├── lib/ +│ │ ├── parser.mist +│ │ └── helper.rs +│ └── _header.rs +└── .mist/ + └── src/ + ├── main.rs # transpiled output + ├── lib/ + │ ├── parser.rs + │ └── helper.rs + └── _header.rs +``` + +The `.mist/src/` directory contains the transpiled Rust output. `_header.rs` is a special file that provides IDE support for Rust Analyzer. diff --git a/content/docs/components/structs.mdx b/content/docs/components/structs.mdx index 70a8c72..aeb5ff8 100644 --- a/content/docs/components/structs.mdx +++ b/content/docs/components/structs.mdx @@ -57,4 +57,4 @@ pub struct Buffer<'a, T> { - **Type-First Declaration**: Fields use the `type name` order to match function parameters and variable declarations. - **Comma-Separated Members**: Fields are separated by commas, maintaining a clean and consistent delimiter style. - **Rust Compatibility**: Maps 1:1 to Rust structs, ensuring zero-cost abstraction and full ecosystem interoperability. -- **Direct Visibility**: The `pub` keyword replaces `pub` for a more consistent modifier language across the codebase. +- **Direct Visibility**: The `pub` modifier controls access at the struct and field level. diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 184ff38..2f8c31f 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -11,7 +11,7 @@ Mist is currently distributed as a Cargo crate. To get started, you'll need to h Run the following command to install the Mist compiler: ```bash title="Terminal" -cargo install mist-lang@0.0.3-alpha4 +cargo install mist-lang@0.0.5-alpha0 ``` Once the installation finishes, verify it by checking the version: @@ -24,20 +24,19 @@ mist version ## 2. Setting Up Your Project -Mist works alongside Cargo to handle the heavy lifting. Follow these steps to prepare your environment for your first "Hello World" program. - -### Initialize a New Project - -If you haven't already, create a new Cargo project and navigate into the directory: +Mist works alongside Cargo to handle the heavy lifting. Use `init` to scaffold a new project: ```bash title="Terminal" cargo new my-mist-app cd my-mist-app +mist init ``` -### Configure Mist +This creates a `src/main.mist` and wires up the output directory (`.mist/src/`) in your `Cargo.toml`. -Create a `mist.json` file in your root directory. This tells the compiler where to look for your source code and where to place the generated Rust files. +### Manual Setup + +If you prefer to configure things yourself, create a `mist.json` file: ```json title="mist.json" { @@ -46,36 +45,13 @@ Create a `mist.json` file in your root directory. This tells the compiler where } ``` -### Link Cargo to Mist - -Since Mist compiles down to Rust, you need to point Cargo to the generated output. Update your `Cargo.toml` to include the following: - -```toml title="Cargo.toml" -[[bin]] -name = "my-mist-app" -path = "build/main.rs" -``` - -You can also add `/build` to your `.gitignore`. - -> **Pro Tip:** create a `src/_header.rs` file with only main declared, and add this to your `Cargo.toml` (without replacing the current `[[bin]]`): -> ```toml title="Cargo.toml" -> # add this in [package] -> default-run="my-mist-app-header" -> -> # Do not replace the current [[bin]] -> [[bin]] -> name = "my-mist-app-header" -> path = "src/_header.rs" ->``` -> -> And add all of the `mod`(s) from `src/main.rs`, as well as a empty `main` function, this will allow `.rs` files to be used with IDE support. +Source files go in `src/` and the transpiled output goes to `.mist/src/`. Non-Mist files in `src/` (e.g. Rust sidecar files) are copied through as-is. --- ## 3. Your First Program -Now for the fun part! Create a new file at `src/main.mist` and add the following code: +Create a new file at `src/main.mist` and add the following code: ```mist title="src/main.mist" void main() { @@ -85,28 +61,23 @@ void main() { ### Build and Run -To turn your Mist code into an executable, use the `run` command: - ```bash title="Terminal" -mist run +mist run # or the short alias: mist r +mist build # or: mist b +mist check # or: mist c +mist transpile # or: mist t ``` -Or if you only want to transpile to rust (this will not give any semantic errors, only syntax errors). - -```bash title="Terminal" -mist transpile -``` - - --- ## Command Reference -| Command | Description | -| ---------------- | ----------------------------------------------- | -| `mist run` | Runs the project in the current directory | -| `mist build` | builds the project in the current directory | -| `mist transpile` | transpiles the project in the current directory | -| `mist check` | checks the project in the current directory | -| `mist version` | prints the compiler version | -| `mist help` | prints this message | +| Command | Alias | Description | +| -------------------- | ----- | ----------------------------------------------- | +| `mist init` | | Initializes a new Mist project | +| `mist run` | `r` | Runs the project in the current directory | +| `mist build` | `b` | Builds the project in the current directory | +| `mist transpile` | `t` | Transpiles the project in the current directory | +| `mist check` | `c` | Checks the project in the current directory | +| `mist version` | `-v` | Prints the compiler version | +| `mist help` | `-h` | Prints this message | diff --git a/content/docs/limitations.mdx b/content/docs/limitations.mdx index 2ac5442..918e52b 100644 --- a/content/docs/limitations.mdx +++ b/content/docs/limitations.mdx @@ -6,4 +6,6 @@ icon: TriangleAlert Mist is currently in a **Volatile Alpha** stage. Our current priority is exploring **Syntax and Features**. We believe in stabilizing the developer experience and the "feel" of the language before locking in the deep architectural logic of the compiler. +The compiler, transpiler, and CLI are partially bootstrapped — written in Mist itself. This gives us real-world feedback on every language design decision. + You may encounter weird illogical syntax errors, please report them at https://github.com/mist-go/mist/issues with the context. diff --git a/content/docs/logic/control-flow.mdx b/content/docs/logic/control-flow.mdx index 8783892..1bf1e54 100644 --- a/content/docs/logic/control-flow.mdx +++ b/content/docs/logic/control-flow.mdx @@ -4,11 +4,11 @@ description: Directing execution with expression-based logic, pattern matching, icon: Split --- -Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. While many structures can return values, they follow a strict syntax for blocks and statements. +Control flow in Mist provides a bridge between C-style procedural logic and Rust's expression-oriented design. Blocks, if statements, while/for/loop loops, and match expressions all support statement bodies — meaning braces can be omitted for single-statement branches. ## Conditionals -The `if` statement evaluates a boolean expression. It supports multiple `else if` branches and an optional `else` block. +The `if` statement evaluates a boolean expression. Single-statement bodies don't need braces: ```mist if (score > 50) { @@ -18,11 +18,17 @@ if (score > 50) { } else { println!("Fail"); } + +// Single-statement body (no braces needed) +if (is_active) println!("Running"); + +// Expression body (soft return) +var result = if (valid) "ok" else "err"; ``` ## Match -The `match` statement provides exhaustive pattern matching. Currently, every match arm requires a block `{}` following the `=>` operator. +The `match` statement provides exhaustive pattern matching with support for multiple patterns per arm via `|`: ```mist match (task_state) { @@ -43,54 +49,57 @@ match (task_state) { ## Loops -Mist supports both functional iteration and traditional low-level loop control. +### Loop + +An infinite loop construct: + +```mist +loop { + println!("forever"); + if (done) break; +} +``` ### C-Style For Loop -For manual iteration control, Mist supports the standard three-part `for` loop: initialization, condition, and post-iteration statement. - ```mist -for (var mut i = 0; i < 10; i = i + 1;) { +for (var mut i = 0; i < 10; i++;) println!("Index: {}", i); -} ``` ### For-In Loop -The `for-in` loop iterates over collections or iterators using Mist's pattern matching system. - ```mist -for (var item in collection) { +for (var item in collection) process(item); -} -// Destructuring within the loop -for ((i32 x, i32 y) in coordinates) { +for ((i32 x, i32 y) in coordinates) draw_point(x, y); -} + +// Range iteration +for (var i in 0..10) + println!("{}", i); ``` ### While Loop -The `while` loop continues execution as long as the parenthesized expression evaluates to `true`. - ```mist while (active) { wait_for_event(); } + +while (count > 0) process(count--); ``` ## Jump Statements -Execution flow can be interrupted or redirected using standard jump keywords. - - **`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 and proceeds to the next. +- **`continue`**: Skips the remainder of the current loop iteration. ## Key Characteristics -- **Pattern Integration**: Loops and match arms utilize Mist's pattern system, allowing for seamless data destructuring during iteration. -- **Explicit Scoping**: Match items currently require explicit blocks, ensuring clear boundaries for variable shadowing and local logic. -- **Familiar Iteration**: The inclusion of C-style `for` loops provides fine-grained control for performance-critical logic where simple iteration is insufficient. -- **Rust-Native Safety**: Despite the procedural syntax, these structures compile to safe Rust, maintaining exhaustive checking and memory safety. +- **Statement Bodies**: If, while, for, and loop branches can omit braces for single statements or expressions. +- **Soft Returns**: Expression bodies (without `;`) 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. diff --git a/content/docs/logic/expressions.mdx b/content/docs/logic/expressions.mdx index 62ff96a..8a051d8 100644 --- a/content/docs/logic/expressions.mdx +++ b/content/docs/logic/expressions.mdx @@ -4,80 +4,123 @@ description: The building blocks of logic, from literals to complex postfix chai 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 that maps closely to Rust's mental model. +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 that maps closely to Rust's mental model. ## Primary Expressions Primary expressions are the starting point of any logic chain. These include literal values, paths to static members, or grouped expressions in tuples. ```mist -// Literals and paths var x = 42; var y = Math::PI; - -// Tuples var coordinates = (10, 20, 30); - ``` ## Postfix Operations -Postfix expressions allow you to build on a primary value. This includes calling functions, accessing fields, indexing arrays, or initializing structs. +Postfix expressions allow you to build on a primary value with field access, calls, indexing, type casting, error propagation, and mutation operators. ```mist -// Field access and method/function calls var len = list.length(); -// Struct initialization var task = Task { name: "Drafting", priority: 1, }; -// Indexing and Macro calls var first = items[0]; -println!("Value: {}", first); // Macro call via '!' +println!("Value: {}", first); +``` +### Increment & Decrement + +```mist +var 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 +var x = 42; +var y = x as f64; +``` + +### Try Operator + +Propagate errors with the `?` postfix operator: + +```mist +var content = fs::read_to_string(path)?; +``` + +### Range Operators + +```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 +var arr = [1, 2, 3]; +var zeros = [0; 10]; // ten zeroes ``` ## Prefix Operations -Prefixes modify the primary expression that follows them. Mist uses these for logical negation, dereferencing, and creating references. +Prefixes modify the primary expression that follows them. ```mist var mut value = 10; -var ref = &value; // Reference -var mref = &mut value; // Mutable reference -var val = *ref; // Dereference -var is_false = !true; // Logical NOT - +var ref = &value; +var mref = &mut value; +var val = *ref; +var is_false = !true; +var neg = -42; ``` ## Binary Operations -Binary operations are applied as postfixes to an expression, following a `bin_op ~ expr` pattern. This supports all standard arithmetic, comparison, and logical operators. - ```mist var sum = 10 + 20; var is_equal = (x == y); var complex = (a + b) * (c / d); - ``` ## Operator Table -Mist supports the following binary operators for comparisons and arithmetic: - -| Category | Operators | -| -------------- | -------------------------------- | -| **Arithmetic** | `+`, `-`, `*`, `/`, `%` | -| **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=` | -| **Logical** | `&&`, `\|\|` | +| Category | Operators | +| -------------- | ---------------------------------------------------------------- | +| **Arithmetic** | `+`, `-`, `*`, `/`, `%` | +| **Comparison** | `==`, `!=`, `<`, `>`, `<=`, `>=` | +| **Logical** | `&&`, `||` | +| **Bitwise** | `<<`, `>>`, `&`, `\|`, `^` | +| **Range** | `..`, `..=` | +| **Assign** | `=`, `+=`, `-=`, `*=`, `/=`, `%=`, `&=`, `\|=`, `^=`, `<<=`, `>>=` | ## Key Characteristics -- **Predictable Chaining**: The `prefix* ~ primary ~ postfix*` grammar ensures that complex expressions are parsed consistently, whether you are dereferencing a function call or indexing a struct field. -- **Rust-Style References**: While the pointer syntax `type*` is used in declarations, expressions use `&` and `&mut` to create references, maintaining compatibility with Rust's borrow checker. -- **Macro Integration**: Macros are treated as a postfix operation (`!`), allowing them to be called on identifiers just like standard functions. -- **Unified Tuples**: Tuples are primary expressions, allowing them to be passed, returned, or destructured seamlessly within the expression tree. +- **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. diff --git a/content/docs/logic/variables.mdx b/content/docs/logic/variables.mdx index 88bac8d..f444f02 100644 --- a/content/docs/logic/variables.mdx +++ b/content/docs/logic/variables.mdx @@ -11,8 +11,8 @@ In Mist, variables follow the language-wide `type name` convention. For local sc Variables are declared using the `var` keyword for automatic type inference. Like Rust, variables are immutable by default. ```mist -var message = "Hello Mist"; // Inferred as str* -var count = 42; // Inferred as i32 +var message = "Hello Mist"; +var count = 42; ``` ## Mutability @@ -29,28 +29,28 @@ price = 14.99; ## Explicit Typing -While `var` handles inference, you can explicitly define the type before the identifier. This is often used for clarity in complex logic or when the specific numeric width (e.g., `u8` vs `i32`) matters. - ```mist u64 large_id = 1000234; bool is_active = true; ``` -## Pattern Destructuring - -Because variable declarations are patterns, you can destructure tuples or structures directly. This keeps data extraction clean and avoids manual indexing. +## Arrays ```mist -// Destructuring a tuple into local variables -(i32, i32) (x, y) = get_coordinates(); +var list = [1, 2, 3]; // Standard init +var zeros = [0; 10]; // Repeat notation: ten zeroes +``` -// Using 'var' within a pattern for inference +## Pattern Destructuring + +```mist +(i32, i32) (x, y) = get_coordinates(); (String, i32) (name, age) = get_user_info(); ``` ## Constants -Constants are immutable values that are evaluated at compile time. They require an explicit type and follow the `const` keyword. +Constants are immutable values evaluated at compile time with an explicit type. ```mist const i32 MAX_RETRIES = 5; @@ -59,7 +59,7 @@ const str* VERSION = "1.0.4"; ## Key Characteristics -- **Predictable Order**: Whether using `var` or an explicit type, the name of the variable always follows the "source" of its data. -- **Safety First**: Immutability by default prevents accidental state changes, mapping directly to Rust's memory safety model. -- **Zero-Cost Inference**: Type inference is handled entirely at compile time, ensuring there is no runtime performance penalty. -- **Shadowing**: Mist supports variable shadowing, allowing you to reuse variable names within the same scope to transform data without changing mutability. +- **Predictable Order**: Whether using `var` or an explicit type, the name always follows the "source" of its data. +- **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. diff --git a/content/docs/meta.json b/content/docs/meta.json index cce9b65..13a5b01 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -12,10 +12,11 @@ "components/classes", "components/traits", "components/pointers-references", + "components/modules-imports", "---[ArrowDownUp]Logic---", "logic/variables", "logic/control-flow", "logic/expressions" ] -} \ No newline at end of file +} diff --git a/content/docs/philosophy.mdx b/content/docs/philosophy.mdx index a555e5d..d601be1 100644 --- a/content/docs/philosophy.mdx +++ b/content/docs/philosophy.mdx @@ -34,6 +34,10 @@ Mist is not a replacement for Rust; it is a **ergonomic interface** for it. It p --- +## Bootstrapped Development + +Mist is partially bootstrapped — the compiler's CLI, transpiler, and analyzer modules are written in Mist itself. This gives us first-hand experience with the language's ergonomics and drives real-world improvements with every release. + ## Why Mist? Mist is for the developer who needs the rigor of a systems language but wants the comfort of a modern, streamlined environment.