From b7ba600d21ca3ce53f5ea4677daad92f741d4c48 Mon Sep 17 00:00:00 2001 From: Klesti Selimaj Date: Sun, 28 Jun 2026 22:19:52 +0200 Subject: [PATCH] Update: Philosphy and index --- content/docs/index.mdx | 36 ++++++++++-------- content/docs/philosophy.mdx | 73 ++++++++++++++++++++++++++++--------- 2 files changed, 75 insertions(+), 34 deletions(-) diff --git a/content/docs/index.mdx b/content/docs/index.mdx index 226a1e0..ecb4092 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -8,12 +8,16 @@ icon: Rocket Mist is currently distributed as a Cargo crate. To get started, you'll need to have the Rust toolchain installed. -Run the following command to install the Mist compiler: +Run the following command to install the Mist toolchain: ```bash title="Terminal" -cargo install mist-lang@0.3.1-alpha.0 +cargo install mist-lang@0.3.7-alpha.0 ``` +> (ℹ) For a more streamlined development experience, Install the following VSCode extensions: +> 1. [Mist syntax highlighting VSCode extension](https://marketplace.visualstudio.com/items?itemName=selimaj-dev.mist-syntax) +> 2. [Mist analyzer LSP VSCode extension](https://marketplace.visualstudio.com/items?itemName=selimaj-dev.mist-analyzer) + Once the installation finishes, verify it by checking the version: ```bash title="Terminal" @@ -22,39 +26,39 @@ mist version --- -## 2. Setting Up Your Project +## 2. Setting Up Your Cargo Project -Mist works alongside Cargo to handle the heavy lifting. Use `init` to scaffold a new project: +Mist works alongside Cargo to handle the heavy lifting. Use `cargo new` or `cargo init` to scaffold a new project: ```bash title="Terminal" cargo new my-mist-app cd my-mist-app -mist init ``` This creates a `src/main.mist` and wires up the output directory (`.mist/src/`) in your `Cargo.toml`. -### Manual Setup +### 3. Adding mist to your Cargo project -If you prefer to configure things yourself, create a `mist.json` file: +Mist needs a `Mist.toml` in the root of the project (Alongside `Cargo.toml`) to know what to transpile as the main file (eg. main.mist, lib.mist). -```json title="mist.json" -{ - "src": "src", - "output": "build" -} +```toml title="Mist.toml" +# main.mist is now the main package +package = "main.mist" + +# Side packages that work as cargo binaries +packages = [] ``` 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 +## 4. Your First Program Create a new file at `src/main.mist` and add the following code: ```mist title="src/main.mist" -fn main() { +void main() { println!("Hello World!"); } ``` @@ -62,7 +66,7 @@ fn main() { ### Build and Run ```bash title="Terminal" -mist run # or the short alias: mist r +mist run # or: mist r mist build # or: mist b mist check # or: mist c mist transpile # or: mist t @@ -74,7 +78,7 @@ mist transpile # or: mist t | Command | Alias | Description | | -------------------- | ----- | ----------------------------------------------- | -| `mist init` | | Initializes a new Mist project | +| `mist init` | | Initializes a new Mist project (Deprecated) | | `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 | diff --git a/content/docs/philosophy.mdx b/content/docs/philosophy.mdx index 397421d..abab179 100644 --- a/content/docs/philosophy.mdx +++ b/content/docs/philosophy.mdx @@ -4,33 +4,71 @@ 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. +**Mist** is a pragmatic systems programming language built on Rust. It uses C/C++ style syntax for quick onboarding while compiling directly to efficient Rust code with zero-cost abstractions and no runtime overhead. -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. +All of your favorite Rust libraries work with Mist. It is designed for **low-level applications and embedded programming**, where a type-first approach is preferred and staying close to the metal matters. --- -## The Philosophy of Ergonomics +## C++ You Know, Rust You Trust -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**. +Mist is meant to feel like C++ but **be** Rust. It bridges the gap between the ergonomics of a classic systems language and the safety guarantees of Rust's ownership model. -### Reducing Expression Overhead +### Type-First Syntax -Complexity often arises from "expression overhead"—the mental energy spent navigating intricate syntax and symbols. Mist reduces this friction by: +Low-level and embedded development demands clarity about what your data is. Mist puts the **type first** — before the name — so declarations read naturally: -* **Predictable Flow:** By adopting a consistent `name: Type` 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. +```mist +i32 score = 100; +Vec args = env::args().collect(); +void* data = allocate(size); +``` + +This mirrors C/C++ declaration syntax, making Mist instantly familiar to embedded and systems programmers while compiling into Rust's strict type system. + +### C-Style Functions + +Functions use the return type before the name — no `fn` keyword needed: + +```mist +i32 add(i32 a, i32 b) { + a + b +} + +void log(message *str) { + println!("{}", message); +} +``` + +Every function maps directly to a Rust `fn` underneath. + +### Minimal Friction + +* No `let` keyword — `Type name = value` is all you need. +* Consistent `name Type` convention across parameters, fields, and locals. +* Explicit pointers with `*T` and `*mut T` — clear intent without ceremony. +* String references use `str&` for a natural left-to-right read. + +--- + +## Built for Low-Level and Embedded + +Mist is designed from the ground up for systems where resources are constrained and control is required: + +* **No runtime** — no garbage collector, no hidden allocator, no VM. +* **Direct memory control** — explicit pointers, manual allocation, predictable layout. +* **Zero-cost abstractions** — classes, traits, and generics all resolve at compile time. +* **Works with existing Cargo tooling** — use any Rust crate as a library. --- ## 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. +Mist is not a replacement for Rust; it is an **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". +* **Zero-Cost Abstractions:** Every high-level structure in Mist — classes, enums, traits — maps directly to optimized Rust primitives. No magic, no hidden runtime. +* **Grounded Safety:** Mist doesn't hide memory safety; it makes it easier to express. You retain the full power of the borrow checker with syntax that feels like classic C++. +* **Native Fluency:** Mist compiles to idiomatic, readable Rust, making it a first-class citizen of the ecosystem. Use any crate while writing code that feels distinctly Mist. --- @@ -40,8 +78,7 @@ Mist is partially bootstrapped — the compiler's CLI, transpiler, and analyzer ## 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. +* **Familiarity:** C/C++ developers can be productive immediately — no new optical model to learn. +* **Safety:** Rust's borrow checker and type system under every expression, no exceptions. +* **Control:** Explicit types, explicit pointers, explicit allocation — nothing hidden. +* **Ecosystem:** The entire Rust crate ecosystem available at your fingertips.