commit e38e2baf59f24440a490e1e5964307caca42a72c
Author: erick-alcachofa <erick@artichoke.dev>
Date:   Thu Oct 2 00:25:29 2025 -0600

    chore: Initial wiki push
    
    Signed-off-by: erick-alcachofa <erick@artichoke.dev>

diff --git a/Home.md b/Home.md
new file mode 100644
index 0000000..a2300fb
--- /dev/null
+++ b/Home.md
@@ -0,0 +1,286 @@
+# 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;
+```
diff --git a/grammar.ebnf b/grammar.ebnf
new file mode 100644
index 0000000..134ac36
--- /dev/null
+++ b/grammar.ebnf
@@ -0,0 +1,348 @@
+/*
+================================================================================
+|                                                                              |
+|                      The Artichoke Programming Language                      |
+|                           Official EBNF Grammar                              |
+|                                                                              |
+================================================================================
+*/
+
+
+/* --- Program Structure --- */
+/* A program is a sequence of top-level declarations and statements. */
+
+<program> =
+  ( <import_statement>
+  | <module_statement>
+  | <alias_statement>
+  | <struct_declaration>
+  | <enum_declaration>
+  | <function_declaration> )*
+
+<module_statement> =
+  "export"? "module" <namespaced_identifier> "{"
+    ( <module_statement>
+    | <alias_statement>
+    | <struct_declaration>
+    | <enum_declaration>
+    | <function_declaration> )*
+  "}"
+
+<import_statement> =
+  "import" <import_target> ";"
+
+<import_target> =
+    <namespaced_identifier>
+  | <namespaced_identifier> "::" "*"
+
+<alias_statement> =
+  "using" <identifier> "=" <namespaced_identifier> ";"
+
+
+/* --- Declarations --- */
+/* Rules for defining functions, structs, enums, and their components. */
+
+<function_declaration> =
+  "export"? "fn" <identifier> <generic_params> "(" <fn_params> ")" ( "->" <type> )? <code_block>
+
+<fn_params> =
+  <fn_params_list>?
+
+<fn_params_list> =
+    "this" <type> ("," <fn_param> ( "," <fn_param> )* )?
+  | <fn_param> ( "," <fn_param> )*
+
+<fn_param> =
+  <identifier> ":" <type>
+
+<struct_declaration> =
+  "export"? "struct" <identifier> <generic_params> "{" <struct_members> "}"
+
+<struct_members> =
+  <struct_member> ( "," <struct_member> )*
+
+<struct_member> =
+  <identifier> ":" <type>
+
+<enum_declaration> =
+  "export"? "enum" <identifier> <generic_params> "{" <enum_members> "}"
+
+<enum_members> =
+  <enum_member> ( "," <enum_member> )*
+
+<enum_member> =
+  <identifier> ( "(" <type> ")" )?
+
+<generic_params> =
+  ( "<" <generic_params_list> ">" )?
+
+<generic_params_list> =
+  <generic_param> ( "," <generic_param> )*
+
+<generic_param> =
+  "typename" <identifier>
+
+
+/* --- Statements & Control Flow --- */
+/* Rules for code blocks, variable declarations, and control structures. */
+
+<code_block> =
+  "{" <statements>? "}"
+
+<statements> =
+  <statement> ( <statement> )*
+
+<statement> =
+    <variable_declaration> ";"
+  | <if_statement>
+  | <loop_statement>
+  | <defer_statement> ";"
+  | <errdefer_statement> ";"
+  | <return_statement> ";"
+  | <break_statement> ";"
+  | <continue_statement> ";"
+  | <expression_statement>
+  | <alias_statement>
+  | <match_statement>
+  | <switch_statement>
+
+<variable_declaration> =
+    <variable_declarator> <identifier> ( ":" <type> )? "=" <expression>
+  | <variable_declarator> <identifier> ":" <type> ( "=" <expression> )?
+
+<variable_declarator> =
+    "let"
+  | "def"
+
+<if_statement> =
+  "if" "(" <expression> ")" <variable_unwrapper>? <code_block>
+  <else_statement>?
+
+<else_statement> =
+    "else" <variable_unwrapper>? <code_block>
+  | "else" <if_statement>
+
+<variable_unwrapper> =
+  "|" <identifier> "|"
+
+<loop_statement> =
+  (<identifier> ":=")? (
+      <c_for_statement>
+    | <range_for_statement>
+    | <while_statement>
+    | <do_while_statement>
+    | <inf_loop_statement>
+  )
+
+<c_for_statement> =
+  "for" "(" <variable_declaration>? ";" <expression> ";" <expression> ")"
+  <code_block>
+
+<range_for_statement> =
+  "for" "(" <variable_declarator> <identifier> ":=" <expression> ")"
+  <code_block>
+
+<while_statement> =
+  "while" "(" <expression> ")" <variable_unwrapper>? <code_block>
+  <else_statement>?
+
+<do_while_statement> =
+  "do" <code_block> "while" "(" <expression> ")"
+
+<inf_loop_statement> =
+  "loop" <code_block>
+
+<match_statement> =
+  "match" "(" <expression> ")" "{" <match_case>* <default_case>? "}"
+
+<switch_statement> =
+  "switch" "(" <expression> ")" "{" <switch_case>* <default_case>? "}"
+
+<match_case> =
+  ( <type_name> | <scoped_access_expression> ) ( "(" <identifier> ")" )? "->" <code_block>
+
+<switch_case> =
+  <expression> "->" <code_block>
+
+<default_case> =
+  "_" "->" <code_block>
+
+<break_statement> =
+  "break" <identifier>?
+
+<continue_statement> =
+  "continue" <identifier>?
+
+<defer_statement> =
+  "defer" ( <expression> | <code_block> )
+
+<errdefer_statement> =
+  "errdefer" ( <expression> | <code_block> )
+
+<return_statement> =
+  "return" <expression>?
+
+<expression_statement> =
+  <expression> ";"
+
+
+/* --- Expressions & Operator Precedence --- */
+/* The full expression hierarchy, from lowest to highest precedence. */
+
+<expression> =
+  <assign_expression>
+
+<assign_expression> =
+  <bool_or_expression> ( ( <assign_op> | <compound_assign_op> ) <expression> )?
+
+<bool_or_expression> =
+  <bool_and_expression> ( ( "||" | "or" ) <bool_and_expression> )*
+
+<bool_and_expression> =
+  <compare_expression> ( ( "&&" | "and" ) <compare_expression> )*
+
+<compare_expression> =
+  <bitwise_expression> ( <compare_op> <bitwise_expression> )?
+
+<bitwise_expression> =
+  <bitwise_shift_expression> ( <bitwise_op> <bitwise_shift_expression> )*
+
+<bitwise_shift_expression> =
+  <addition_expression> ( <bitshift_op> <addition_expression> )*
+
+<addition_expression> =
+  <multiply_expression> ( <addition_op> <multiply_expression> )*
+
+<multiply_expression> =
+  <prefix_expression> ( <multiply_op> <prefix_expression> )*
+
+<prefix_expression> =
+  <prefix_op>* <primary_expression>
+
+<primary_expression> =
+  <primary_type_expression> ( <suffix_op> | <fn_call_arguments> )*
+
+
+/* --- Primary Expressions & Literals --- */
+/* The highest-precedence expressions, including literals and grouped expressions. */
+
+<primary_type_expression> =
+    <char_literal>
+  | <null_literal>
+  | <string_literal>
+  | <number_literal>
+  | <boolean_literal>
+  | <grouped_expression>
+  | <identifier>
+  | <struct_literal>
+  | <scoped_access_expression>
+  | <reflection_expression>
+
+<grouped_expression> =
+  "(" <expression> ")"
+
+<scoped_access_expression> =
+  <type_name> "::" <identifier>
+
+<reflection_expression> =
+  ( <primary_expression> | <type_name> | <scoped_access_expression> ) ".@" <identifier>?
+
+<fn_call_arguments> =
+  "(" <expression_list> ")"
+
+<expression_list> =
+  (<expression> ",")* <expression>?
+
+<struct_literal> =
+  <type> "{" ( <named_field_list> | <positional_field_list> )? ","? "}"
+
+<named_field_list> =
+  <named_field_init> ( "," <named_field_init> )*
+
+<named_field_init> =
+  <identifier> ":" <expression>
+
+<positional_field_list> =
+  <expression> ( "," <expression> )*
+
+<null_literal> =
+  "null"
+
+<boolean_literal> =
+    "true"
+  | "false"
+
+<number_literal> = /* Assumed to be defined by the tokenizer */
+<string_literal> = /* Assumed to be defined by the tokenizer */
+<char_literal> = /* Assumed to be defined by the tokenizer */
+
+
+/* --- Operators --- */
+/* Definitions for all operator token sets. */
+
+<assign_op> = "="
+<compound_assign_op> = "+=" | "-=" | "*=" | "/=" | "%=" | "&=" | "|=" | "<<=" | ">>=" | "||=" | "&&="
+<compare_op> = "==" | "!=" | ">" | "<" | ">=" | "<="
+<bitwise_op> = "&" | "^" | "|"
+<bitshift_op> = "<<" | ">>"
+<addition_op> = "+" | "-"
+<multiply_op> = "*" | "/" | "%"
+<prefix_op> = "!" | "-" | "~" | "&" | "*"
+
+<suffix_op> =
+    "[" <expression>? ":" <expression>? "]"
+  | "[" <expression> "]"
+  | ".[" <expression> "]"
+  | "." <identifier>
+  | "->" <identifier>
+  | ".#"
+  | ".*"
+
+/* --- Type System --- */
+/* Rules for defining types, type names, and type qualifiers. */
+
+<type> =
+  <type_qualifier_chain> <type_name>
+
+<type_qualifier_chain> =
+    ( "*" | "[]" ) <type_qualifier_chain>?
+  | "$" <type_qualifier_chain_after_mutable>?
+  | "?" <type_qualifier_chain_after_optional>?
+
+<type_qualifier_chain_after_optional> =
+    ( "*" | "[]" ) <type_qualifier_chain>?
+  | "$" <type_qualifier_chain_after_mutable>?
+
+<type_qualifier_chain_after_mutable> =
+    ( "*" | "[]" ) <type_qualifier_chain>?
+  | "?" <type_qualifier_chain_after_optional>?
+
+<type_name> =
+  <namespaced_identifier> ( "<" <types_list> ">" )?
+
+<namespaced_identifier> =
+    <identifier>
+  | <identifier> "::" <namespaced_identifier>
+
+<types_list> =
+  <type> ( "," <types_list> )*
+
+
+/* --- Lexical Tokens & Base Definitions --- */
+/* The lowest-level building blocks of the language. */
+
+<identifier> =
+  <nondigit> <identifier_tail>
+
+<identifier_tail> =
+    <empty>
+  | <nondigit> <identifier_tail>
+  | <digit> <identifier_tail>
+
+<nondigit> = "_" | [a-z] | [A-Z]
+<digit> = <zero> | <nonzero_digit>
+<zero> = "0"
+<nonzero_digit> = [1-9]
+
+<empty> = E /* Represents an empty terminal string */
+