Merge pull request #3 from mist-go/complete-documentation
Complete documentation
This commit is contained in:
+16
@@ -0,0 +1,16 @@
|
||||
# Stage 1: Build the application
|
||||
FROM node:20-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm install
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
# Stage 2: Serve the static files with Nginx
|
||||
FROM nginx:alpine
|
||||
# Copy the build files from the builder stage to the Nginx web directory
|
||||
COPY --from=builder /app/dist /usr/share/nginx/html
|
||||
# Expose port 80 where the Nginx server runs
|
||||
EXPOSE 80
|
||||
# Command to start Nginx server
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
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 allow you to define data fields, constructors, instance methods, and trait implementations within a single, cohesive block.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
A class groups fields and methods together. Fields follow the `type name` convention, and methods define their logic directly within the class body.
|
||||
|
||||
```cpp
|
||||
public class Logger {
|
||||
String prefix;
|
||||
|
||||
public void info(self*, str* message) {
|
||||
self.log(LogLevel::Info, message);
|
||||
}
|
||||
|
||||
void log(self*, LogLevel level, str* message) {
|
||||
println!("{level} {} {}", self.prefix, message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## The Constructor
|
||||
|
||||
Unlike languages that use the class name for initialization, Mist uses the explicit `constructor` keyword. This makes the entry point of the class unmistakable.
|
||||
|
||||
```cpp
|
||||
public constructor(str* prefix) {
|
||||
self.prefix = prefix.to_string();
|
||||
}
|
||||
```
|
||||
|
||||
## Instance Methods & `self`
|
||||
|
||||
Mist maintains Rust's explicit context handling. Any method that needs to access or modify class data must include `self*` (or `self mut*` for mutations) as its first parameter.
|
||||
|
||||
```cpp
|
||||
public void warning(self*, str* message) {
|
||||
self.log(LogLevel::Warning, message);
|
||||
}
|
||||
```
|
||||
|
||||
## Trait Implementations
|
||||
|
||||
One of Mist's most powerful features is the ability to nest trait implementations directly within the class block. This keeps the logic for how a type behaves (e.g., how it is displayed) physically coupled with the type definition.
|
||||
|
||||
```cpp
|
||||
impl fmt::Display {
|
||||
std::fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
|
||||
return write!(f, "logger ({})", self.prefix);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **Unified Scope**: Data, behavior, and trait logic live in one place, eliminating the friction of jumping between `struct` and `impl` blocks.
|
||||
- **Explicit Context**: The use of `self*` ensures that the relationship between a method and its instance is always transparent.
|
||||
- **Encapsulation**: Visibility modifiers (`public`) allow you to expose a clean API while keeping internal helper methods and state private to the class.
|
||||
- **Zero-Cost Classes**: Under the hood, Mist desugars these into idiomatic Rust structs and implementation blocks, ensuring no runtime overhead compared to raw Rust.
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
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 applying the language-wide `type name` convention for variants that contain data.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
An enum can contain unit variants, tuple variants, or struct-like variants. Following Mist's core philosophy, struct-like variants place the type before the identifier.
|
||||
|
||||
```rust
|
||||
public enum TaskState {
|
||||
Pending,
|
||||
InProgress,
|
||||
Completed,
|
||||
// Struct-like variant using 'type name'
|
||||
Failed {
|
||||
String reason,
|
||||
i32 code,
|
||||
},
|
||||
}
|
||||
```
|
||||
## Variant Types
|
||||
|
||||
Mist supports all standard variant shapes, ensuring a 1:1 mapping to the underlying Rust execution model.
|
||||
|
||||
```rust
|
||||
enum Message {
|
||||
Quit, // Unit
|
||||
Move(i32, i32), // Tuple
|
||||
Write(String), // Tuple
|
||||
ChangeColor { // Struct-like
|
||||
u8 r, u8 g, u8 b,
|
||||
},
|
||||
}
|
||||
```
|
||||
## Generics & Lifetimes
|
||||
|
||||
Just like structs and functions, enums declare generics and lifetimes in a unified block. This is particularly useful for defining custom Result or Option types that handle references.
|
||||
|
||||
```rust
|
||||
public enum Validation<'a, T> {
|
||||
Valid(T),
|
||||
Invalid {
|
||||
str'a* message,
|
||||
u32 error_id,
|
||||
},
|
||||
}
|
||||
```
|
||||
## Key Characteristics
|
||||
|
||||
- **Consistent Member Declaration**: Struct-like variants maintain the `type name` order, ensuring that data modeling feels identical whether you are defining a top-level `struct` or an `enum` variant.
|
||||
- **Rust-Native ADTs**: Enums compile directly to Rust enums, allowing for exhaustive pattern matching and zero-cost abstraction.
|
||||
- **Shared Visibility**: The `public` modifier at the enum level exports all variants for use in other modules, matching Rust's visibility rules for enums.
|
||||
- **Comma-Separated Members**: Fields within struct-like variants are separated by commas, mirroring the syntax used in standard Mist structs.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
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. They prioritize a traditional declaration order, placing the return type before the identifier to ensure signatures remain easy to scan in complex systems.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
A standard function requires a return type, a name, and a body. Use the `void` keyword for functions that do not return a value.
|
||||
|
||||
```cpp
|
||||
i32 add(i32 a, i32 b) {
|
||||
return a + b;
|
||||
}
|
||||
|
||||
void log_status(str* message) {
|
||||
println!("{}", message);
|
||||
}
|
||||
```
|
||||
|
||||
## Visibility & Exports
|
||||
|
||||
Functions are private to their module by default. The `public` modifier exports the function for cross-module access.
|
||||
|
||||
```cpp
|
||||
public i32 get_version() {
|
||||
return 1;
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```cpp
|
||||
void update_score(i32 mut current_score, i32 bonus) {
|
||||
current_score = current_score + bonus;
|
||||
}
|
||||
```
|
||||
|
||||
## Generics & Lifetimes
|
||||
|
||||
Mist integrates type abstraction and memory management into a single generic block. Lifetimes and type parameters share the `< >` bracket following the identifier.
|
||||
|
||||
```rust
|
||||
public str'a* choose_longer<'a, T: Display>(str'a* s1, str'a* s2, T meta) {
|
||||
println!("Metadata: {}", meta);
|
||||
return if (s1.len() > s2.len()) { s1 } else { s2 };
|
||||
}
|
||||
```
|
||||
|
||||
## Attributes & Metadata
|
||||
|
||||
Metadata is applied via the `#[attr]` syntax directly above the declaration for compiler hints or testing.
|
||||
|
||||
```cpp
|
||||
#[inline]
|
||||
public bool is_active(u32 id) {
|
||||
return id > 0;
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: Pointers & References
|
||||
description: Explicit memory access with C-style ergonomics and Rust-native safety.
|
||||
icon: MousePointer2
|
||||
---
|
||||
|
||||
Mist simplifies Rust’s reference system by using a pointer-style syntax. While the symbols look like C-style pointers, they adhere strictly to Rust’s ownership and borrowing rules.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
References are defined by placing a `*` after the type. By default, pointers are immutable (shared). To allow modification of the underlying data, use the `mut*` modifier.
|
||||
|
||||
```cpp
|
||||
void increment(i32 mut* value, i32* limit) {
|
||||
if (value < limit) {
|
||||
value = value + 1;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Lifetimes
|
||||
|
||||
Lifetimes are attached directly to the type before the pointer symbol. This maintains a clean visual flow where the "type-contract" (identity, duration, and mutability) is read from left to right.
|
||||
|
||||
```cpp
|
||||
public struct Inspector<'a> {
|
||||
public str'a* target,
|
||||
public u32'a mut* counter,
|
||||
}
|
||||
```
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **Explicit Intent:** The `mut*` syntax clearly distinguishes between a reference that can read and one that can write, mapping 1:1 to Rust's `&` and `&mut`.
|
||||
- **Visual Consistency:** Lifetimes (`'a`) and mutability modifiers are integrated into the type declaration, keeping function signatures and struct fields compact.
|
||||
- **Safety Guaranteed:** Despite the "pointer" appearance, the Mist compiler enforces Rust’s borrow checker. You cannot have multiple `mut*` references to the same data, and references cannot outlive their owners.
|
||||
- **Zero Overhead:** Mist pointers are "thin" or "fat" exactly like Rust references; they carry no extra runtime metadata and compile to identical machine code.
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Structs
|
||||
description: Data modeling using Mist's type-first convention.
|
||||
icon: Form
|
||||
---
|
||||
|
||||
Structs in Mist follow the same structural logic as Rust, but apply the language-wide `type name` declaration style and allow for comma-separated field grouping.
|
||||
|
||||
## Basic Syntax
|
||||
|
||||
A struct is defined by its name followed by a block of fields. Each field follows the Mist convention of placing the type before the identifier, separated by commas.
|
||||
|
||||
```rust
|
||||
public struct Task {
|
||||
public String name,
|
||||
public TaskState state,
|
||||
public i32 executions,
|
||||
}
|
||||
```
|
||||
|
||||
## Visibility
|
||||
|
||||
Use the `public` modifier to make the struct or its individual fields accessible from other modules.
|
||||
|
||||
```cpp
|
||||
public struct NetworkNode {
|
||||
public u32 id,
|
||||
str* address,
|
||||
}
|
||||
```
|
||||
|
||||
## Instantiation
|
||||
|
||||
Structs are instantiated using the standard brace syntax.
|
||||
|
||||
```cpp
|
||||
var task = Task {
|
||||
name: "Initialize".to_string(),
|
||||
state: TaskState::Pending,
|
||||
executions: 0,
|
||||
};
|
||||
```
|
||||
|
||||
## Generics & Lifetimes
|
||||
|
||||
Generics and lifetimes are declared in angle brackets after the struct name. Lifetimes are associated with the reference/pointer type within the field declarations.
|
||||
|
||||
```cpp
|
||||
public struct Buffer<'a, T> {
|
||||
public T'a* data,
|
||||
public usize len,
|
||||
}
|
||||
```
|
||||
|
||||
## Key Characteristics
|
||||
|
||||
- **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 `public` keyword replaces `pub` for a more consistent modifier language across the codebase.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
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. While they mirror the logic of Rust traits, they utilize Mist’s **type-first** declaration style for method signatures.
|
||||
|
||||
## Defining a Trait
|
||||
|
||||
A trait definition lists method signatures that implementing types must satisfy. Like functions, these signatures place the return type before the method name.
|
||||
|
||||
```rust
|
||||
public trait Drawable {
|
||||
void draw(self*);
|
||||
str* metadata(self*);
|
||||
}
|
||||
```
|
||||
## Implementing a Trait
|
||||
|
||||
To implement a trait for a specific type, use the `impl` keyword followed by the trait name and the target type. This block must contain all required methods defined in the trait.
|
||||
|
||||
```rust
|
||||
impl Drawable for Task {
|
||||
void draw(self*) {
|
||||
println!("Drawing task: {}", self.name);
|
||||
}
|
||||
|
||||
str* metadata(self*) {
|
||||
return self.name;
|
||||
}
|
||||
}
|
||||
```
|
||||
## Default Implementations
|
||||
|
||||
Traits can provide default behavior for methods. Types implementing the trait can choose to override these defaults or use the provided implementation.
|
||||
|
||||
```rust
|
||||
public trait Identifiable {
|
||||
u32 get_id(self*);
|
||||
|
||||
bool is_valid(self*) {
|
||||
return self.get_id() > 0;
|
||||
}
|
||||
}
|
||||
```
|
||||
## Super-traits
|
||||
|
||||
Traits can build upon other traits. If a trait requires another trait to be implemented first, use the colon `:` syntax.
|
||||
|
||||
```rust
|
||||
public trait Animated : Drawable {
|
||||
void animate(self*, f32 delta_time);
|
||||
}
|
||||
```
|
||||
## Key Characteristics
|
||||
|
||||
- **Consistent Signatures**: Method signatures within traits follow the language-wide `return_type name(params)` convention.
|
||||
- **Explicit Context**: Methods use `self*` or `self mut*` as the first parameter to define how the instance is accessed, mapping directly to Rust's reference rules.
|
||||
- **Static Dispatch**: By default, Mist traits leverage Rust's zero-cost generics and monomorphization, ensuring high performance.
|
||||
- **Predictable Contracts**: Traits act as strict blueprints; the Mist compiler ensures every implementation perfectly matches the interface before generating the corresponding Rust code.
|
||||
@@ -1,66 +0,0 @@
|
||||
---
|
||||
title: Get Started
|
||||
description: This guide will help you install the Mist CLI, understand its basic commands, and compile your first program.
|
||||
icon: Rocket
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
Mist is distributed through Cargo.
|
||||
|
||||
Install the Mist compiler using:
|
||||
|
||||
```bash title="Terminal"
|
||||
cargo install [email protected]
|
||||
```
|
||||
|
||||
Verify using
|
||||
|
||||
```bash title="Terminal"
|
||||
mist version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```bash title="Compiles the project in the current directory"
|
||||
mist build
|
||||
```
|
||||
|
||||
```bash title="Prints the compiler version"
|
||||
mist version
|
||||
```
|
||||
|
||||
```bash title="Shows the help message and available commands"
|
||||
mist help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hello World
|
||||
|
||||
On your existing cargo project project (`cargo init` or `cargo new <name>`).
|
||||
|
||||
```json title="mist.json"
|
||||
{
|
||||
"src": "src",
|
||||
"output": "build"
|
||||
}
|
||||
```
|
||||
|
||||
```toml title="Cargo.toml"
|
||||
[[bin]]
|
||||
name = "main"
|
||||
path = "build/main.rs"
|
||||
```
|
||||
|
||||
```bash title=".gitignore"
|
||||
/build
|
||||
```
|
||||
|
||||
```cpp title="src/main.mist"
|
||||
void main() {
|
||||
println!("Hello World!");
|
||||
}
|
||||
```
|
||||
+77
-21
@@ -1,41 +1,97 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: What Mist is and the thinking behind it.
|
||||
icon: Brain
|
||||
title: Get Started
|
||||
description: This guide will walk you through installing the Mist CLI, setting up your development environment, and compiling your very first program.
|
||||
icon: Rocket
|
||||
---
|
||||
|
||||
Mist is a systems programming language that compiles directly into Rust.
|
||||
## 1. Installation
|
||||
|
||||
It exists to make Rust-based development feel more direct and less mentally heavy, while preserving Rust’s performance model and ecosystem.
|
||||
Mist is currently distributed as a Cargo crate. To get started, you'll need to have the Rust toolchain installed.
|
||||
|
||||
Mist does not replace Rust. It is another way of writing Rust-compatible systems code with a more ergonomic surface layer.
|
||||
Run the following command to install the Mist compiler:
|
||||
|
||||
```bash title="Terminal"
|
||||
cargo install [email protected]
|
||||
```
|
||||
|
||||
Once the installation finishes, verify it by checking the version:
|
||||
|
||||
```bash title="Terminal"
|
||||
mist version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Philosophy
|
||||
## 2. Setting Up Your Project
|
||||
|
||||
Mist is built around making systems programming feel calm, predictable, and easy to reason about.
|
||||
Mist works alongside Cargo to handle the heavy lifting. Follow these steps to prepare your environment for your first "Hello World" program.
|
||||
|
||||
When working close to the system, developers constantly manage performance, correctness, and structure at the same time. As projects grow, this can create mental friction — not because the system is unclear, but because expressing it can feel heavy.
|
||||
### Initialize a New Project
|
||||
|
||||
Mist focuses on reducing that friction in how code is written and read, so attention stays on the problem being solved rather than the mechanics of expression.
|
||||
If you haven't already, create a new Cargo project and navigate into the directory:
|
||||
|
||||
The language is shaped around clarity and flow: code should feel direct to write, and easy to understand when revisited.
|
||||
```bash title="Terminal"
|
||||
cargo new my-mist-app
|
||||
cd my-mist-app
|
||||
```
|
||||
|
||||
### Configure Mist
|
||||
|
||||
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.
|
||||
|
||||
```json title="mist.json"
|
||||
{
|
||||
"src": "src",
|
||||
"output": "build"
|
||||
}
|
||||
```
|
||||
|
||||
### 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 = "main"
|
||||
path = "build/main.rs"
|
||||
```
|
||||
|
||||
> **Pro Tip:** You’ll probably want to add `/build` to your `.gitignore` file to keep your repository clean!
|
||||
|
||||
---
|
||||
|
||||
## What Mist Is
|
||||
## 3. Your First Program
|
||||
|
||||
Mist is a Rust-compatible systems language with a compiled-to-Rust design.
|
||||
Now for the fun part! Create a new file at `src/main.mist` and add the following code:
|
||||
|
||||
This means:
|
||||
```cpp title="src/main.mist"
|
||||
void main() {
|
||||
println!("Hello World!");
|
||||
}
|
||||
```
|
||||
|
||||
- It integrates directly with the Rust ecosystem
|
||||
- It compiles into idiomatic Rust code
|
||||
- It preserves Rust’s performance characteristics
|
||||
- It has no runtime or garbage collector
|
||||
- It is designed to stay predictable and close to the metal
|
||||
### Build and Run
|
||||
|
||||
Mist provides a more ergonomic way of authoring systems code while remaining fully grounded in Rust’s type system and execution model.
|
||||
To turn your Mist code into an executable, use the `build` command:
|
||||
|
||||
It is especially designed for readability and structure in larger codebases, where Rust’s guarantees remain important but expression overhead becomes noticeable.
|
||||
```bash title="Terminal"
|
||||
mist build
|
||||
```
|
||||
|
||||
Once the build is successful, you can run your program using standard Cargo commands:
|
||||
|
||||
```bash title="Terminal"
|
||||
cargo run
|
||||
```
|
||||
|
||||
> **Pro Tip:** If you encounter any rust errors, head to the build directory and analyze the output, if you see anything unusual in the output, report the issue at https://github.com/mist-go/mist
|
||||
|
||||
---
|
||||
|
||||
## Command Reference
|
||||
|
||||
| Command | Description |
|
||||
| -------------- | ---------------------------------------------------------------- |
|
||||
| `mist build` | Compiles your `.mist` files into Rust code in the output folder. |
|
||||
| `mist version` | Displays the current version of the Mist compiler. |
|
||||
| `mist help` | Stuck? Use this to see all available commands and options. |
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
title: Status & Limitations
|
||||
description: Understanding the Alpha state of Mist and our technical roadmap.
|
||||
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 "Syntax-First" Philosophy
|
||||
|
||||
Mist is currently in a phase of rapid iteration. We are intentionally keeping the **Semantics** flexible while we finalize the **Syntax**.
|
||||
|
||||
* **The Goal:** Finalize a robust, ergonomic feature set first.
|
||||
|
||||
|
||||
* **The Reasoning:** Implementing complex semantic analysis while features are still being added is inefficient. By stabilizing the syntax first, we ensure that adding full semantic depth becomes a cohesive, "single-step" process later in development.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Current Technical Trade-offs
|
||||
|
||||
To allow for this rapid syntax exploration, the compiler currently uses a "Shim" model for certain complex Rust operations.
|
||||
|
||||
### 1. The Construction Model
|
||||
|
||||
To support Mist's unified **Class and Constructor** model, the compiler uses an experimental memory initialization pattern.
|
||||
|
||||
* **Mechanism:** The compiler generates a "shell" using `MaybeUninit`, allowing `self` to be used inside the constructor logic.
|
||||
|
||||
|
||||
* **Limitation:** Because full **Definite Assignment Analysis** (semantics) is not yet implemented, the compiler does not verify that every field is assigned. It currently relies on zeroing out memory as a placeholder.
|
||||
|
||||
|
||||
* **Future Fix:** Once the syntax is frozen, we will implement the semantic checks required to generate standard, safe Rust struct literals.
|
||||
|
||||
|
||||
|
||||
### 2. Inheritance
|
||||
|
||||
Inheritance is a major planned feature but is currently **not implemented**.
|
||||
|
||||
* **Status:** The syntax for inheritance is being designed, but it will not be functional until the semantic analyzer is built to handle v-tables and memory layouts in the emitted Rust code.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Feature Volatility
|
||||
|
||||
Be aware that because we are focusing on syntax, keywords and structures may change between minor versions. Currently:
|
||||
|
||||
* **Access Modifiers:** `public` and private defaults are being tested for various contexts (classes vs. structs, or `public(crate)`).
|
||||
|
||||
|
||||
* **Pointers vs. References:** The `*` syntax for references (e.g., `self mut*`) is the current standard but is subject to refinement based on ecosystem feedback.
|
||||
|
||||
|
||||
* **Trait Implementations:** The "In-Class" `impl` block is a core feature we are prioritizing for ergonomics.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
> **Alpha Warning:** Mist is currently a playground for defining a better way to write systems code. Expect breaking changes as we finalize the surface layer of the language.
|
||||
>
|
||||
>
|
||||
@@ -0,0 +1,93 @@
|
||||
---
|
||||
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. While many structures can return values, they follow a strict syntax for blocks and statements.
|
||||
|
||||
## Conditionals
|
||||
|
||||
The `if` statement evaluates a boolean expression. It supports multiple `else if` branches and an optional `else` block.
|
||||
|
||||
```cpp
|
||||
if (score > 50) {
|
||||
println!("Pass");
|
||||
} else if (score == 50) {
|
||||
println!("Borderline");
|
||||
} else {
|
||||
println!("Fail");
|
||||
}
|
||||
```
|
||||
|
||||
## Match
|
||||
|
||||
The `match` statement provides exhaustive pattern matching. Currently, every match arm requires a block `{}` following the `=>` operator.
|
||||
|
||||
```cpp
|
||||
match (task_state) {
|
||||
TaskState::Pending => {
|
||||
println!("Queued");
|
||||
}
|
||||
TaskState::Failed { reason, code } => {
|
||||
println!("Error {}: {}", code, reason);
|
||||
}
|
||||
_ => {
|
||||
println!("Other state");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Loops
|
||||
|
||||
Mist supports both functional iteration and traditional low-level loop control.
|
||||
|
||||
### C-Style For Loop
|
||||
|
||||
For manual iteration control, Mist supports the standard three-part `for` loop: initialization, condition, and post-iteration statement.
|
||||
|
||||
```cpp
|
||||
for (var mut i = 0; i < 10; i = i + 1;) {
|
||||
println!("Index: {}", i);
|
||||
}
|
||||
```
|
||||
|
||||
### For-In Loop
|
||||
|
||||
The `for-in` loop iterates over collections or iterators using Mist's pattern matching system.
|
||||
|
||||
```cpp
|
||||
for (var item in collection) {
|
||||
process(item);
|
||||
}
|
||||
|
||||
// Destructuring within the loop
|
||||
for ((i32 x, i32 y) in coordinates) {
|
||||
draw_point(x, y);
|
||||
}
|
||||
```
|
||||
|
||||
### While Loop
|
||||
|
||||
The `while` loop continues execution as long as the parenthesized expression evaluates to `true`.
|
||||
|
||||
```cpp
|
||||
while (active) {
|
||||
wait_for_event();
|
||||
}
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
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 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.
|
||||
|
||||
```java
|
||||
// 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.
|
||||
|
||||
```java
|
||||
// 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 '!'
|
||||
|
||||
```
|
||||
|
||||
## Prefix Operations
|
||||
|
||||
Prefixes modify the primary expression that follows them. Mist uses these for logical negation, dereferencing, and creating references.
|
||||
|
||||
```java
|
||||
var mut value = 10;
|
||||
|
||||
var ref = &value; // Reference
|
||||
var mref = &mut value; // Mutable reference
|
||||
var val = *ref; // Dereference
|
||||
var is_false = !true; // Logical NOT
|
||||
|
||||
```
|
||||
|
||||
## 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.
|
||||
|
||||
```java
|
||||
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** | `&&`, `\|\|` |
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Variables
|
||||
description: Local state management with type inference and explicit mutability.
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
In Mist, variables follow the language-wide `type name` convention. For local scope, the `var` keyword provides type inference, while explicit types can be used for clarity or strictness.
|
||||
|
||||
## Basic Declaration
|
||||
|
||||
Variables are declared using the `var` keyword for automatic type inference. Like Rust, variables are immutable by default.
|
||||
|
||||
```java
|
||||
var message = "Hello Mist"; // Inferred as str*
|
||||
var count = 42; // Inferred as i32
|
||||
```
|
||||
|
||||
## Mutability
|
||||
|
||||
To allow a variable to be reassigned, use the `mut` modifier after the `var` keyword or the explicit type.
|
||||
|
||||
```rust
|
||||
var mut score = 0;
|
||||
score = 100;
|
||||
|
||||
f32 mut price = 19.99;
|
||||
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.
|
||||
|
||||
```rust
|
||||
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.
|
||||
|
||||
```rust
|
||||
// Destructuring a tuple into local variables
|
||||
(i32, i32) (x, y) = get_coordinates();
|
||||
|
||||
// Using 'var' within a pattern for inference
|
||||
(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.
|
||||
|
||||
```rust
|
||||
const i32 MAX_RETRIES = 5;
|
||||
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.
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"pages": [
|
||||
"---[Rocket]Introduction---",
|
||||
"index",
|
||||
"philosophy",
|
||||
"limitations",
|
||||
|
||||
"---[Box]Components---",
|
||||
"components/functions",
|
||||
"components/structs",
|
||||
"components/enums",
|
||||
"components/classes",
|
||||
"components/traits",
|
||||
"components/pointers-references",
|
||||
|
||||
"---[ArrowDownUp]Logic---",
|
||||
"logic/variables",
|
||||
"logic/control-flow",
|
||||
"logic/expressions"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
---
|
||||
title: Philosophy
|
||||
description: The mindset, ergonomics, and feeling of writing Mist.
|
||||
icon: Brain
|
||||
---
|
||||
|
||||
**Mist** is a systems programming language designed for those who value the "craft" of software. It is built to provide a serene, tactile authoring environment that stays out of your way, allowing you to focus entirely on the architecture of your solution.
|
||||
|
||||
By compiling directly to Rust, Mist offers a refined surface layer that maintains industrial-grade safety and performance while prioritizing a flow state that is often lost in modern systems development.
|
||||
|
||||
---
|
||||
|
||||
## The Philosophy of Ergonomics
|
||||
|
||||
Writing Mist should feel intentional and deeply satisfying. It is built on the belief that systems programming is at its best when it is **calm, predictable, and direct**.
|
||||
|
||||
### Reducing Expression Overhead
|
||||
|
||||
Complexity often arises from "expression overhead"—the mental energy spent navigating intricate syntax and symbols. Mist reduces this friction by:
|
||||
|
||||
* **Predictable Flow:** By adopting a consistent `type name` convention, code follows a natural rhythm that is easy to write and instantly scannable.
|
||||
* **Structural Clarity:** Features like unified `class` blocks and explicit `constructor` keywords provide a clear, organized home for your logic, reducing the need to jump between disparate files or implementation blocks.
|
||||
* **Tactile Precision:** Every symbol, from `mut*` pointers to pattern-based variables, is designed to feel physically connected to the data it represents, making the "mechanics" of the language feel like a well-calm tool in your hand.
|
||||
|
||||
---
|
||||
|
||||
## A Transparent Surface Layer
|
||||
|
||||
Mist is not a replacement for Rust; it is a **ergonomic interface** for it. It provides a way to interact with the world’s most powerful systems model through a cleaner lens.
|
||||
|
||||
* **Zero-Cost Abstractions:** Every high-level structure in Mist—whether it’s a class, an enum variant, or a trait implementation—maps directly to an optimized Rust primitive. There is no "magic," no hidden runtime, and no garbage collector.
|
||||
* **Grounded Safety:** Mist doesn't hide memory safety; it makes it easier to express. You retain the full power of the borrow checker, but with a syntax that feels like a classic, high-performance toolkit.
|
||||
* **Native Fluency:** Because Mist compiles to idiomatic, readable Rust, it is a first-class citizen of the ecosystem. You can utilize any existing crate while writing code that feels uniquely "Mist".
|
||||
|
||||
---
|
||||
|
||||
## Why Mist?
|
||||
|
||||
Mist is for the developer who needs the rigor of a systems language but wants the comfort of a modern, streamlined environment.
|
||||
|
||||
* **Mental Longevity:** Designed for large-scale codebases where readability is paramount to long-term maintenance.
|
||||
* **Direct Control:** You stay close to the metal, but the language handles the "noise" of idiomatic expression.
|
||||
* **Craftsmanship:** Mist is where the discipline of systems programming meets the comfort of a high-end workshop.
|
||||
@@ -0,0 +1,7 @@
|
||||
.no-scrollbar::-webkit-scrollbar {
|
||||
display: none;
|
||||
}
|
||||
.no-scrollbar {
|
||||
-ms-overflow-style: none;
|
||||
scrollbar-width: none;
|
||||
}
|
||||
@@ -1,6 +1,13 @@
|
||||
import { HomeLayout } from 'fumadocs-ui/layouts/home';
|
||||
import { baseOptions } from '@/lib/layout.shared';
|
||||
import { HomeLayout } from "fumadocs-ui/layouts/home";
|
||||
import { baseOptions } from "@/lib/layout.shared";
|
||||
|
||||
export default function Layout({ children }: LayoutProps<'/'>) {
|
||||
return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
|
||||
export default function Layout({ children }: LayoutProps<"/">) {
|
||||
return (
|
||||
<HomeLayout
|
||||
{...baseOptions()}
|
||||
className="h-full overflow-hidden no-scrollbar"
|
||||
>
|
||||
{children}
|
||||
</HomeLayout>
|
||||
);
|
||||
}
|
||||
|
||||
+26
-42
@@ -6,6 +6,8 @@ import Link from "next/link";
|
||||
import { useEffect, useRef, useState } from "react";
|
||||
import { motion, Variants } from "framer-motion";
|
||||
|
||||
import "./Home.css";
|
||||
|
||||
const MotionLink = motion(Link);
|
||||
|
||||
export const mistShowcase = [
|
||||
@@ -73,24 +75,12 @@ public class PluginRegistry<T> {
|
||||
self.prefix = prefix.to_string();
|
||||
}
|
||||
|
||||
public void log(self*, LogLevel level, str* message) {
|
||||
match(level) {
|
||||
LogLevel::Info => {
|
||||
println!("{level} {} {}", self.prefix, message);
|
||||
}
|
||||
|
||||
LogLevel::Warning => {
|
||||
println!("{level} {} {}", self.prefix, message);
|
||||
}
|
||||
|
||||
LogLevel::Error => {
|
||||
println!("{level} {} {}", self.prefix, message);
|
||||
}
|
||||
}
|
||||
void log(self*, LogLevel level, str* message) {
|
||||
println!("{level} {} {}", self.prefix, message);
|
||||
}
|
||||
|
||||
impl fmt::Display {
|
||||
fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
|
||||
std::fmt::Result fmt(self*, std::fmt::Formatter<'_> mut* f) {
|
||||
return write!(f, "logger ({})", self.prefix);
|
||||
}
|
||||
}
|
||||
@@ -152,7 +142,7 @@ function ShowSection({
|
||||
return (
|
||||
<motion.section
|
||||
ref={ref}
|
||||
className="h-svh p-10 md:p-20 w-full flex flex-col items-center justify-center"
|
||||
className="h-svh p-10 md:p-20 w-full flex flex-col items-center justify-center snap-center"
|
||||
>
|
||||
<motion.div
|
||||
className="flex flex-col gap-2 items-center justify-center"
|
||||
@@ -175,7 +165,7 @@ function ShowSection({
|
||||
<MotionLink
|
||||
variants={item}
|
||||
className="bg-fd-primary/15 text-fd-primary/90 p-3 px-4.5 rounded-xl cursor-pointer hover:bg-fd-primary/20 hover:text-fd-primary flex gap-2 items-center"
|
||||
href="/docs/get-started"
|
||||
href="/docs"
|
||||
>
|
||||
<RocketIcon className="w-5 h-5" />
|
||||
Get Started
|
||||
@@ -200,51 +190,45 @@ export default function HomePage() {
|
||||
const [currentText, setCurrentText] = useState(mistShowcase[0]?.code || "");
|
||||
|
||||
return (
|
||||
<div className="flex w-full flex-col xl:flex-row">
|
||||
<div className="flex fixed xl:top-0 xl:right-0 w-svw xl:w-[40vw] h-svh xl:items-center mt-10 justify-center z-50 pointer-events-none">
|
||||
<div className="xl:w-full overflow-hidden">
|
||||
<div className="h-[calc(100vh-58px)] overflow-auto snap-y snap-mandatory scroll-smooth no-scrollbar relative flex flex-col xl:flex-row">
|
||||
<div className="hidden pointer-events-none sticky top-0 right-0 z-50 md:flex order-first xl:order-last w-full xl:w-[40vw] h-svh items-center justify-center p-10 no-scrollbar">
|
||||
<div className="w-full max-w-2xl overflow-hidden no-scrollbar">
|
||||
<motion.div
|
||||
className="w-max h-auto border border-fd-border p-5 rounded-xl min-h-24 backdrop-blur bg-black dark:bg-black/20"
|
||||
className="will-change-transform transform-gpu w-full h-auto border border-fd-border p-5 rounded-xl min-h-24 backdrop-blur bg-black dark:bg-black/20 pointer-events-auto"
|
||||
variants={item}
|
||||
initial="hidden"
|
||||
animate="show"
|
||||
>
|
||||
<MorphCode code={currentText} />
|
||||
<MorphCode code={currentText} key="morph-code-logic" />
|
||||
</motion.div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div className="flex-1">
|
||||
<div className="mt-10 xl:mt-0">
|
||||
{mistShowcase.map((show) => (
|
||||
<ShowSection
|
||||
key={show.title}
|
||||
show={show}
|
||||
setActiveCode={setCurrentText}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
<div className="flex-1 w-full xl:w-[60vw]">
|
||||
{mistShowcase.map((show) => (
|
||||
<ShowSection
|
||||
key={show.title}
|
||||
show={show}
|
||||
setActiveCode={setCurrentText}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
<div className="xl:w-[40vw]" />
|
||||
{/* <div className="absolute left-1/2 bottom-1">
|
||||
|
||||
</div> */}
|
||||
<motion.div
|
||||
initial={{ opacity: 0, y: -8 }}
|
||||
animate={{ opacity: 1, y: 0 }}
|
||||
transition={{ duration: 0.6 }}
|
||||
className="absolute bottom-8 left-1/2 -translate-x-1/2"
|
||||
className="fixed bottom-8 left-1/2 -translate-x-1/2 pointer-events-none z-50"
|
||||
>
|
||||
<motion.div
|
||||
animate={{ y: [0, 10, 0] }}
|
||||
transition={{
|
||||
duration: 1.5,
|
||||
repeat: Infinity,
|
||||
ease: "easeInOut",
|
||||
}}
|
||||
transition={{ duration: 1.5, repeat: Infinity, ease: "easeInOut" }}
|
||||
className="flex flex-col items-center gap-1 text-muted-foreground"
|
||||
>
|
||||
<ChevronsDownIcon className="h-6 w-6 text-fd-primary" strokeWidth={1.5} />
|
||||
<ChevronsDownIcon
|
||||
className="h-6 w-6 text-fd-primary"
|
||||
strokeWidth={1.5}
|
||||
/>
|
||||
</motion.div>
|
||||
</motion.div>
|
||||
</div>
|
||||
|
||||
@@ -39,7 +39,7 @@ export default function MorphCode({ code, lang = "rust" }: Props) {
|
||||
}, [code, lang]);
|
||||
|
||||
return (
|
||||
<pre className="text-sm">
|
||||
<pre className="text-sm overflow-x-scroll overflow-y-hidden">
|
||||
<code>
|
||||
<AnimatePresence mode="popLayout">
|
||||
{lines.map((line, lineIndex) => (
|
||||
|
||||
Reference in New Issue
Block a user