UI for api

public/css/global.css

@@ -27,6 +27,7 @@
     --c-purple-light: #BA94D1;
     --c-box-shadow: #FBFACD;
     --c-pink: #AE508D;
+    --c-link: #38bdf8;
 
     --c-nav-bg: rgb(18, 18, 18, 0.5);
     --c-secondary: rgba(136, 75, 106, 0.5);
@@ -42,6 +43,7 @@
         --c-box-shadow: #374259;
         --c-primary: rgb(255, 180, 180);
         --c-pink: #374259;
+        --c-link: #0284c7;
 
         --c-nav-bg: rgb(255, 247, 255, 0.5);
         --c-secondary: rgba(255, 255, 240, 0.5);
@@ -57,6 +59,7 @@ html {
         font-size: 17px;
     }
 }
+
 body {
     font-family: Inter, 'Fira Sans', Inter, sans-serif;
 }
@@ -67,7 +70,8 @@ body {
     }
 }
 
-pre, code {
+pre,
+code {
     font-family: "Iosevka Fixed Web", "Iosevka Nerd Font", Iosevka, monospace;
 }
 
@@ -92,6 +96,7 @@ pre, code {
     line-height: 1;
     margin-left: 0.5rem;
 }
+
 .heading-linked :hover {
     text-decoration: underline var(--c-primary);
 }

public/css/pages.css

@@ -48,3 +48,8 @@
     color: var(--code-theme-color);
     background: var(--code-theme-bg-color);
 }
+
+.markdown a {
+    color: var(--c-link);
+    text-decoration: underline;
+}

public/css/xcode-colors.css

@@ -14,11 +14,15 @@
     /* ? */
     --code-theme-c3: #39adb5;
     /* string */
-    --code-theme-c4: #fc6a5d;
+    --code-theme-c4: rgb(124, 201, 117);
+    /* #fc6a5d; */
     /* declaration */
     --code-theme-c5: #5dd8ff;
     /* proyect function */
-    --code-theme-c6: #67b7a4; /*#e53935;*/
+    --code-theme-c6: #67b7a4;
+    /*#e53935;*/
+    /* function */
+    --code-theme-c7: rgb(179, 146, 240);
 
     --code-theme-punctuation: #dedede;
 }
@@ -42,7 +46,10 @@
         --code-theme-c4: #c41a16;
         /* declaration */
         --code-theme-c5: #0f68a0;
-        --code-theme-c6: #326d74; /*#e53935;*/
+        --code-theme-c6: #326d74;
+        /*#e53935;*/
+        /* function */
+        --code-theme-c7: rgb(95, 74, 134);
 
         --code-theme-punctuation: #202020;
     }
@@ -177,7 +184,7 @@ pre[class*="language-"] {
 }
 
 .token.function {
-    color: var(--code-theme-c2);
+    color: var(--code-theme-c7);
 }
 
 .token.hexcode {

src/components/Navbar.astro

@@ -43,10 +43,10 @@ const { showSidebarButton = true } = Astro.props;
             Language reference
         </a>
         <a
-            href="/api/"
+            href="/api/std/"
             class="hidden lg:inline-block px-4 font-display font-bold-text-xl hover:underline"
         >
-            Stdlib API
+            std reference
         </a>
     </div>
 </nav>

src/components/TwoColumn.astro

@@ -0,0 +1,3 @@
+<div class="grid grid-cols-[10rem_auto]">
+    <slot />
+</div>

src/layouts/ApiLayout.astro

@@ -1,6 +1,10 @@
 ---
 import Navbar from "../components/Navbar.astro";
 import BaseLayout from "./BaseLayout.astro";
+import TOC from "../components/TOC.astro";
+
+const {headings} = Astro.props;
+
 ---
 
 <BaseLayout>
@@ -22,7 +26,21 @@ import BaseLayout from "./BaseLayout.astro";
         >
             <slot />
         </main>
+
+        <div
+            class="lg:pt-12 hidden lg:block pt-4 max-h-screen overflow-x-scroll sticky top-0"
+        >
+            <nav class="rounded-md lg:mt-10">
+                <h2 class="font-display font-medium pb-2 text-c-text-2">
+                    On this page
+                </h2>
+
+                <TOC headings={headings} />
+            </nav>
         </div>
+    </div>
+
+    <div class="h-32"></div>
 
     <script>
         import {highlightOnDom} from "./thpHighlighter";

src/pages/api/index.md

@@ -1,38 +0,0 @@
----
-layout: ../../layouts/ApiLayout.astro
----
-
-# module `std`
-
-## The THP standard library
-
-This module contains many functions, classes, constant & enums
-commonly used in THP programs. These can be used directly,
-without having to import them.
-
-This module is not a 1:1 map of the global PHP scope. Instead,
-this module contains all those members organized into classes,
-objects or other modules.
-
-For example, to find if a string contains another, in PHP you'd do:
-
-```php
-<?php
-if (str_contains("abc", "a")) {
-    // ...
-}
-```
-
-In THP there is no `str_contains` function. Instead, you'd call the
-`contains` method on the string:
-
-```thp
-if "abc".contains("a")
-{
-    // ...
-}
-```
-
-
-
-

src/pages/api/std/Array.mdx

@@ -0,0 +1,310 @@
+---
+layout: ../../../layouts/ApiLayout.astro
+---
+import TwoColumn from "../../../components/TwoColumn.astro"
+
+# Array
+
+A THP array is an abstraction on top of PHP arrays.
+
+THP Arrays contain an ordered list of values of a unique datatype, that is to say,
+you cannot store values of different datatypes inside an Array.
+
+If you need to store values of different types, see Tuples.
+
+THP arrays are 0-indexed.
+
+## Signature
+
+```thp
+type Array[T] = Map[Int, T]
+```
+
+Where `T` is the datatype that the Array stores. For example:
+
+```thp
+Array[Int]              // An array of integers
+Array[Float]            // An array of floats
+Array[Array[String]]    // A 2-dimensional array of strings
+```
+
+## PHP array internals
+
+TL;DR: **Never** assign to an array using an invalid index. If you do
+the program will not crash, but it will not behaved as expected
+[(this is a common problem in PHP)](https://eev.ee/blog/2012/04/09/php-a-fractal-of-bad-design/).
+THP tries its best to solve such behavior.
+
+---
+
+
+Since THP compiles down to PHP, it's important to understand how PHP
+represents arrays internally.
+
+PHP doesn't have arrays. Instead, PHP has ordered maps and syntax sugar
+to make them look like arrays.
+
+When declaring an array like:
+
+```thp
+var arr = ["a", "b", "c"]
+```
+
+in reality what goes into memory is a map with numbers as keys:
+
+```php
+array(
+    0 => "a",
+    1 => "b",
+    2 => "c",
+);
+```
+
+As long as this map contains valid keys, it can be treated as an array.
+We can loop over it, read and write.
+
+However, once we assign to an invalid index, it cannot be treated as an array anymore.
+
+Invalid indexes are:
+
+- Negative numbers
+- Numbers greater than the array's length.
+
+### Problems with iterations
+
+PHP maps preserve insertion order. This means that when iterating over
+a PHP map, values are processed in FIFO.
+
+```thp
+var numbers = ["a", "b", "c"]
+numbers[-10] = "?"    // Assign to a negative index
+
+// Now the array will be (using thp notation):
+// .{
+//     0: "a",
+//     1: "b",
+//     2: "c",
+//   -10: "?",
+// }
+
+numbers[7] = "!"    // Out of bounds assignment
+
+// Now the array will be:
+// .{
+//     0: "a",
+//     1: "b",
+//     2: "c",
+//   -10: "?",
+//     7: "!",
+// }
+
+// In this loop, values will be printed following when
+// they were inserted, not by order of the index.
+for #(_, value) in numbers
+{
+    print("{value} ")   // Will print: a b c ? !
+}
+
+numbers[-4] = "???"
+// .{
+//     0: "a",
+//     1: "b",
+//     2: "c",
+//   -10: "?",
+//     7: "!",
+//    -4: "???",
+// }
+
+// When pushing, the value will be assigned to the highest key + 1
+numbers.push("/")   // This will be at position 8
+
+// .{
+//     0: "a",
+//     1: "b",
+//     2: "c",
+//   -10: "?",
+//     7: "!",
+//    -4: "???",
+//     8: "/",
+// }
+```
+
+This is one of many fundamental flaws with PHP. The only way to solve it
+would be to check every insertion at runtime, and this would have a
+performance penalty.
+
+
+From now on, the documentation will continue to work with the Array
+abstraction, as if all indexes were valid.
+
+
+
+## Usage
+
+### Creation
+
+To create an array use square brackets notation:
+
+```thp
+val numbers = [0, 1, 2, 3, 4, 5]
+```
+
+When the Array is declared over many lines, the last
+item should have a trailing comma:
+
+```thp
+val colors = [
+    "red",
+    "blue",
+    "green",  // trailing comma
+]
+```
+
+If it doesn't, the code formatter will automatically
+insert one for you.
+
+### Assignment
+
+Use square brackets notation to insert into an array or modify it:
+
+To modify an array it must be mutable, that is, assigned to a `var`
+instead of a `val`.
+
+```thp
+// This array cannot be modified, as it's declared with `val`
+val immutable = [1, 2, 3]
+// This is a compile time error
+immutable[0] = 322
+
+// This array can be modified, as it's declared with `var`
+var mutable = [1, 2, 3]
+// Ok
+mutable[0] = 322
+```
+
+To append an element to an array, use the method `push()`:
+
+```thp
+mutable.push(4)
+```
+
+Do not insert into an invalid index. See [PHP array internals](#php-array-internals) to learn why.
+
+
+### Iteration
+
+Use a `for` loop to iterate over the elements of an array:
+
+```thp
+val colors = ["red", "green", "blue"]
+
+for #(_index, c) in colors
+{
+    print("{c} ")
+}
+```
+
+```sh
+red green blue
+```
+
+
+
+### Access
+
+To access a value of the array use square brackets notation:
+
+```thp
+print(colors[0])
+```
+
+Since the index might not exist, this will return a 
+[nullable type](/learn/error-handling/null/) that you have to handle.
+
+
+### Destructuring
+
+THP arrays don't have destructuring, since the values can all be `null`.
+If you know that the number of elements is fixed and valid, use Tuples instead.
+
+
+## Methods
+
+In the parameters, <code class="token keyword">self</code> is the array to operate on.
+
+
+<table class="table-fixed w-full border-collapse border-2 border-zinc-900">
+    <thead>
+        <td class="p-2">Method</td>
+        <td class="py-2">Description</td>
+    </thead>
+    <tbody>
+        <tr class="odd:bg-zinc-900">
+            <td class="px-2">
+                <p class="font-mono whitespace-pre">
+                    <span class="token keyword">fun </span>
+                    <span class="token function">filter</span>
+                    <span>[</span>
+                    <span class="token class">T</span>
+                    <span>]</span>
+                    <span>(</span>
+                    <br/>
+                    <span class="token keyword">    self</span>
+                    <span>,</span>
+                    <br />
+                    <span>    (T) -> Bool callback,</span>
+                    <br />
+                    <span>)-> </span>
+                    <span class="token class">Array</span>
+                    <span>[</span>
+                    <span class="token class">T</span>
+                    <span>]</span>
+                </p>
+            </td>
+            <td>
+                Filters elements using a callback function, and returns
+                them in a new array.
+            </td>
+        </tr>
+        <tr class="odd:bg-zinc-900">
+            <td class="px-2">
+                <p class="font-mono">
+                    <span class="token keyword">fun </span>
+                    <span class="token function">push</span>
+                    <span>[</span>
+                    <span class="token class">T</span>
+                    <span>]</span>
+                    <span>(</span>
+                    <span class="token keyword">self</span>
+                    <span>, T ...elements) -> </span>
+                    <span class="token class">Int</span>
+                </p>
+            </td>
+            <td>
+                Appends one or more elements to the end of the array.
+                Returns the new length of the array.
+            </td>
+        </tr>
+        <tr class="odd:bg-zinc-900">
+            <td class="px-2">
+                <p class="font-mono">
+                    <span class="token keyword">fun </span>
+                    <span class="token function">pop</span>
+                    <span>[</span>
+                    <span class="token class">T</span>
+                    <span>]</span>
+                    <span>(</span>
+                    <span class="token keyword">self</span>
+                    <span>) -> </span>
+                    <span class="token class">T</span>
+                </p>
+            </td>
+            <td>
+                Removes the last value of the array, and returns it.
+            </td>
+        </tr>
+    </tbody>
+</table>
+
+
+

src/pages/api/std/index.mdx

@@ -0,0 +1,89 @@
+---
+layout: ../../../layouts/ApiLayout.astro
+---
+import TwoColumn from "../../../components/TwoColumn.astro"
+
+# module `std`
+
+## The THP standard library
+
+This module contains many functions, classes, constant & enums
+commonly used in THP programs. These can be used directly,
+without having to import them.
+
+This module is not a 1:1 map of the global PHP scope. Instead,
+this module contains all those members organized into classes,
+objects or other modules.
+
+For example, to find if a string contains another, in PHP you'd do:
+
+```php
+<?php
+if (str_contains("abc", "a")) {
+    // ...
+}
+```
+
+In THP there is no `str_contains` function. Instead, you'd call the
+`contains` method on the string:
+
+```thp
+if "abc".contains("a")
+{
+    // ...
+}
+```
+
+## On naming
+
+THP enforces `snake_case` for variables/functions. However, PHP has a mixture of `snake_case` and `camelCase`
+in its names. Where PHP would use `camelCase`, THP uses `snake_case`.
+
+For example, the function `PDO::errorCode()` becomes `PDO::error_code()`.
+
+Furthermore, letter case in THP carries semantic meaning. Variables **must** start with either
+lowercase or underscore, and Datatypes **must** start with uppercase.
+
+Those have been changed where neccesary.
+
+### Interop with lowercase classes
+
+If you need to use a PHP class with a lowercase name you can use the following syntax:
+
+```php
+<?php
+class animal {}
+```
+
+```thp
+val my_animal = 'animal()
+```
+
+
+## Datatypes
+
+<TwoColumn>
+
+[`Array[T]`](/api/std/Array/)
+
+A uniform container of values or references.
+
+[`String`](/api/std/String/)
+
+A series of extended ASCII characters (8 bits).
+
+[`Int`](/api/std/Int/)
+
+An integer number.
+
+[`Float`](/api/std/Float/)
+
+A [IEEE 754](https://en.wikipedia.org/wiki/IEEE_754) double precision floating point number.
+
+[`Bool`](/api/std/Bool/)
+
+`true` or `false`
+
+</TwoColumn>
+
+

src/pages/learn/flow-control/loops.md

@@ -14,15 +14,10 @@ Braces are required.
 ```thp
 val numbers = [0, 1, 2, 3]
 
-for number in numbers
+for #(index, number) in numbers
 {
     print(number)
 }
-
-for #(index, number) in numbers.entries()
-{
-    print("{index} => {number}")
-}
 ```
 
 ```thp
@@ -38,15 +33,6 @@ for #(key, value) in dict
 }
 ```
 
-```thp
-for value in collection
-{
-    if condition
-    {
-        break
-    }
-}
-```
 
 
 ## While loop

src/pages/learn/index.mdx

@@ -129,12 +129,8 @@ These are **not** aspects that THP looks to solve or implement.
 - Use PHP syntax/conventions.
 - Be familiar for PHP developers.
 
-
+THP **_intentionally_** uses a different syntax from PHP to signal
-## Philosophy
+that it is a different language, and has different semantics.
-
-- Consistency over familiarity
-- Change over conventions
-- Explicit over implicit
 
 
 ## Some differences with PHP

tailwind.config.mjs

@@ -1,6 +1,6 @@
 /** @type {import('tailwindcss').Config} */
 export default {
-	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'],
+	content: ['./src/**/*.{astro,html,js,jsx,md,mdx,ts,tsx}'],
 	theme: {
 		extend: {
             colors: {