artichoke-lang/docs/Home.md

# The `artichoke` Programming Language: A Technical Overview

## 1. Introduction

`artichoke` is a statically-typed, general-purpose programming language designed
with an emphasis on performance, safety, and expressive syntax. It combines
low-level control over memory with modern, high-level features like generics,
algebraic data types, and integrated error handling. This document provides an
overview of the language's features as defined by its core grammar.

Is highly inspired by C, C++, Rust, and mostly Zig.

## 2. Basic Syntax & Structure

### Modules, Imports, and Aliases

`artichoke` code is organized into modules. The `import` statement is used to bring
symbols from other modules into the current scope.

* **Importing a specific element:** `import my_module::some_function;`
* **Importing all direct elements of a module:** `import std::*;`
* **Importing an entire submodule:** `import std::memory;`

The `using` keyword creates a local, more convenient alias for a type, function,
or module name.

```
using mem = std::memory;
using FileHandle = std::fs::File;
```

### Comments

The language uses C-style block comments.

```
/* This is a multi-line
   comment. */
```

## 3. The Type System

`artichoke`'s type system is strong and static, with a rich set of features for
defining complex data structures.

### Type Qualifiers

Qualifiers modify the type to their immediate right, allowing for precise and
complex type definitions.

* **`*` (Pointer):** Creates a pointer to a type. Pointers cannot be `null`.
* **`$` (Mutable):** Marks a type as mutable. This is used for function
               parameters, local variables, and struct fields to allow modification.
* **`?` (Optional):** Marks a type as nullable. An optional type can hold either a
                value of its underlying type or `null`.
* **`[]` (Slice):** A "fat pointer" representing a view into a contiguous
              sequence of elements. It contains both a pointer to the data and a length.

These qualifiers can be combined. For example, `*$?int` defines a **pointer to a
mutable optional integer**.

### Generics

Generics allow for writing flexible, reusable code that can operate on multiple
types. They are defined using `<typename T>`.

```
/* A generic struct */
struct Point<typename T> {
    x: T,
    y: T
}

/* A generic function */
fn scale<typename T>(lhs: *Point<T>, rhs: T) -> Point {
    /* ... */
}
```


## 4. Declarations

### Variables

Variables are declared using the `let` (mutable) and `def` (immutable/constant)
keywords.

* **Type inference** is supported when the type can be determined from the initializer.
* Variables must be initialized with either a type, a value, or both.

```
/* Mutable variable with explicit type */
let x: i32 = 10;

/* Immutable variable with type inference */
def do_you_get_it = meaning_of_life();
```

### Structs

Structs are composite data types that group together variables under one name.
They support generics.

```
struct Rectangle {
    top: Point<i32>,
    bot: Point<i32>
}
```

**Initialization:** Structs can be initialized using positional or named fields,
but not a mix of both.

```
/* Positional initialization */
def top_left = Point<i32>{ 0, 10 };

/* Named-field initialization */
def top_right = Point<i32>{ x: 10, y: 10 };
```

### Enums (Tagged Unions)

Enums define a type that can be one of several different variants. Variants can
optionally hold data.

```
enum AssetType {
    Texture,
    Model,
    Sound,
}

enum Result<typename T, typename E> {
    Ok(T),
    Err(E)
}
```

**Initialization:** Enum variants are accessed using scope resolution (`::`).

```
def my_asset = AssetType::Texture;
def success = Result<i32, string>::Ok(100);
```

### Functions

Functions are defined with the fn keyword. The return type is specified after
the parameter list with `->`.

```
fn meaning_of_life() -> i32 {
    return 42;
}
```

#### Member Functions (`this` parameter)

If the first parameter of a function is declared with the `this` keyword, it can
be called using "member function" syntax.

```
/* Definition */
fn add<typename T>(this *$Point<T>, other: *Point<T>) {
    this->x += other->x;
    this->y += other->y;
}

/* Can be called in two ways: */
/* Member function syntax */
my_point.add(&other_point);

/* Normal function syntax */
add(&my_point, &other_point);
```

## 5. Control Flow

### `if`/`else` Statements

`artichoke` supports C-style `if`/`else` and `else if` chains. It also integrates a
powerful unwrapping feature for handling `Result` and optional (`?`) types.

```

/* Standard if/else */
if (argc < 2) {
    return Result::Err(-1);
}

/* Unwrapping a Result */
if (foo()) |ok| {
    /* `ok` holds the success value */
}
else |err| {
    /* `err` holds the error value */
}
```

### Loops

The language provides a comprehensive set of looping constructs.

* **C-Style `for`:** `for (let i \= 0; i \< 10; i \+= 1\) { ... }`
* **Range-based `for`:** `for (let e := arrSlice) { ... }`
* **`while` Loop:** Can optionally have an `else` block that executes when the loop
              condition is no longer met.
* **Iterator `while`:** Supports unwrapping `Result`/optional types, executing as
                  long as the value is valid.
* **`do-while` Loop:** Guarantees the body executes at least once.
* **Infinite `loop`:** `loop { ... }`

#### Loop Labels and Control

Loops can be labeled. The `break` and `continue` statements can optionally specify a
label to control nested loops.

```
outer_loop := while (condition) {
    inner_loop := for (...) {
        break outer_loop;
    }
}
```

## 6. Expressions and Operators

### Pointer and Member Access

* **`&` (Address-of):** Gets a pointer to a variable.
* **`*` (Dereference):** Accesses the value a pointer points to.
* **`.` (Member Access):** Accesses a member of a struct value.
* **`->` (Pointer Member Access):** Dereferences a pointer and accesses a member
                              (`p->x` is shorthand for `(*p).x`).

### Slice Operators

Slices have a dedicated set of operators for manipulation.

* **`[start:end]` (Slicing):** Creates a new slice from an existing one.
* **`.*` (Pointer Access):** Gets the underlying raw pointer of the slice.
* **`.#` (Length Access):** Gets the number of elements in the slice.
* **`.[length]` (Slice from Pointer):** Creates a slice from a raw pointer and a length.

### Assignment

The language supports simple (`=`) and compound assignment (`+=`, `*=`, etc.)
operators.

## 7. Advanced Features

### Resource Management (`defer` and `errdefer`)

`artichoke` uses `defer` for deterministic resource management.

* **`defer`:** Schedules an expression or code block to be executed when the
         current scope is exited. Deferred calls are executed in Last-In, First-Out
         (LIFO) order.
* **`errdefer`:** Similar to `defer`, but the code is only executed if the scope is
            exited due to a function returning an error (an `Err` variant of a `Result`).

```
defer call_cleanup();

errdefer {
    log("An error occurred!");
}
```

### Reflection (`.@`)

The language provides a compile-time reflection mechanism via the `.@` operator.
It can be applied to values, types, and static members to query metadata.

* **On values:** `my_variable.@type`
* **On types:** `Point<u32>.@size, Point<u32>.@alignment`
* **On static members:** `Point<u32>::x.@offset`

```
/* Gets size in bytes */
def size_bytes = Point<u32>.@size;

/* Gets string representation of the type */
def point_name = Point<u32>.@typename;
```