fernando/thp-lang.org
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

UI for api

Browse Source
This commit is contained in:
Araozu 2024-05-28 21:12:04 -05:00
parent 4dc0b8524f
commit 34efcc780d
12 changed files with 464 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
public/css/global.css
View File

@ -20,16 +20,17 @@
:root {
--c-bg: #121212;
--c-text: rgb(200,200,200);
--c-text: rgb(200, 200, 200);
--c-text-2: white;
--c-primary: #884b6a;
--c-purple: #7F669D;
--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);
--c-secondary: rgba(136, 75, 106, 0.5);
}
@media (prefers-color-scheme: light) {
@ -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;
}
@ -84,7 +88,7 @@ pre, code {
}
/* Used by headers generated from markdown */
.heading-linked :hover::after{
.heading-linked :hover::after {
color: var(--c-primary);
content: "#";
display: inline-block;
@ -92,6 +96,7 @@ pre, code {
line-height: 1;
margin-left: 0.5rem;
}
.heading-linked :hover {
text-decoration: underline var(--c-primary);
}

5
public/css/pages.css
View File

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

25
public/css/xcode-colors.css
View File

@ -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;
}
@ -86,13 +93,13 @@ pre[class*="language-"] ::selection {
color: var(--code-theme-color_selection);
}
:not(pre) > code[class*="language-"] {
:not(pre)>code[class*="language-"] {
white-space: normal;
border-radius: 0.2em;
padding: 0.1em;
}
:not(pre) > code {
:not(pre)>code {
background-color: var(--code-theme-bg-color);
padding: 0 0.25rem;
border-radius: 5px;
@ -106,9 +113,9 @@ pre[class*="language-"] {
border: 1px solid var(--code-theme-border-color);
}
.language-css > code,
.language-sass > code,
.language-scss > code {
.language-css>code,
.language-sass>code,
.language-scss>code {
color: var(--code-theme-c1);
}
@ -177,7 +184,7 @@ pre[class*="language-"] {
}
.token.function {
color: var(--code-theme-c2);
color: var(--code-theme-c7);
}
.token.hexcode {

4
src/components/Navbar.astro
View File

@ -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>

3
src/components/TwoColumn.astro Normal file
View File

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

18
src/layouts/ApiLayout.astro
View File

@ -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";

38
src/pages/api/index.md
View File

@ -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")
{
// ...
}
```

310
src/pages/api/std/Array.mdx Normal file
View File

@ -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>

89
src/pages/api/std/index.mdx Normal file
View File

@ -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>

16
src/pages/learn/flow-control/loops.md
View File

@ -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

8
src/pages/learn/index.mdx
View File

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

2
tailwind.config.mjs
View File

@ -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: {