feat: v0.0.1 docs
This commit is contained in:
parent
1465ec23be
commit
432862a253
@ -52,7 +52,9 @@ const posts_2 = posts
|
||||
// being `/spec/ast/tokens` would be `/ast/tokens`
|
||||
path: post.url.substring(base_len),
|
||||
}))
|
||||
.sort((p1, p2) => (p1.frontmatter.order > p2.frontmatter.order ? 1 : -1));
|
||||
.sort((p1, p2) =>
|
||||
p1.frontmatter.order > p2.frontmatter.order ? 1 : -1,
|
||||
);
|
||||
|
||||
// build a hierarchy of the files
|
||||
const second_level: Record<string, Array<AstroFile>> = {
|
||||
@ -117,7 +119,7 @@ const rc = url_components[1] ?? "";
|
||||
---
|
||||
|
||||
<BaseLayout title={frontmatter.title}>
|
||||
<Navbar />
|
||||
<Navbar version={version} />
|
||||
|
||||
<div
|
||||
class="lg:grid lg:grid-cols-[14rem_auto_12rem] lg:container mx-auto font-display"
|
||||
@ -127,13 +129,20 @@ const rc = url_components[1] ?? "";
|
||||
class="pt-12 h-screen lg:sticky top-0 fixed z-10 bg-c-bg w-60 lg:w-auto border-r-2 lg:border-0
|
||||
border-c-border-1 -translate-x-64 lg:translate-x-0 transition-transform"
|
||||
>
|
||||
<nav class="py-4 pr-2 overflow-x-scroll h-[calc(100vh-3rem)]">
|
||||
<div class="mb-2 relative" x-data="{open: false}">
|
||||
<nav
|
||||
class="py-4 pr-2 overflow-x-scroll h-[calc(100vh-3rem)]"
|
||||
>
|
||||
<div
|
||||
class="mb-2 relative"
|
||||
x-data="{open: false}"
|
||||
>
|
||||
<button
|
||||
class="bg-c-bg text-c-text border border-c-primary rounded px-3 w-full font-mono mt-2 flex items-center hover:dark:bg-zinc-800 transition-colors cursor-pointer text-left"
|
||||
@click="open = !open"
|
||||
>
|
||||
<span class="inline-block w-full">
|
||||
<span
|
||||
class="inline-block w-full"
|
||||
>
|
||||
{version}
|
||||
</span>
|
||||
<svg
|
||||
@ -157,14 +166,18 @@ const rc = url_components[1] ?? "";
|
||||
class="absolute top-0 w-full bg-c-bg border border-c-primary rounded"
|
||||
>
|
||||
{
|
||||
versions.map((x) => (
|
||||
versions.map(
|
||||
(x) => (
|
||||
<a
|
||||
class="px-3 py-1 hover:dark:bg-zinc-800 transition-colors font-mono inline-block w-full text-left"
|
||||
href={`${lc}${x}${rc}`}
|
||||
>
|
||||
{x}
|
||||
{
|
||||
x
|
||||
}
|
||||
</a>
|
||||
))
|
||||
),
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
@ -172,7 +185,11 @@ const rc = url_components[1] ?? "";
|
||||
|
||||
<hr class="my-6" />
|
||||
|
||||
{entries.map((entry) => <Sidebar entry={entry} />)}
|
||||
{
|
||||
entries.map((entry) => (
|
||||
<Sidebar entry={entry} />
|
||||
))
|
||||
}
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
@ -186,7 +203,9 @@ const rc = url_components[1] ?? "";
|
||||
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">
|
||||
<h2
|
||||
class="font-display font-medium pb-2 text-c-text-2"
|
||||
>
|
||||
On this page
|
||||
</h2>
|
||||
|
||||
|
||||
@ -7,6 +7,105 @@ order: 1
|
||||
import InteractiveCode from "@/components/InteractiveCode.astro";
|
||||
import Code from "@/components/Code.astro";
|
||||
|
||||
# THP :D
|
||||
# Welcome
|
||||
|
||||
Welcome to the documentation of the THP programming languague.
|
||||
|
||||
THP ~~is~~ will be a new programming language that compiles to PHP.
|
||||
|
||||
|
||||
|
||||
## Compiler rewrite
|
||||
|
||||
THP was previously written on Rust, but now it's being rewritten in Zig.
|
||||
|
||||
|
||||
|
||||
Due to the rewrite everything has reversed. The Rust version was `v0.1.3`,
|
||||
the Zig rewrite is `v0.0.1`. Also, this is a good opportunity to version
|
||||
the docs.
|
||||
|
||||
The `latest` branch contains future ideas and stuff, but the versioned branches
|
||||
(for example, `v0.0.1`) will document **only** actual, implemented
|
||||
things, and new branches will be published as the compiler evolves.
|
||||
|
||||
## Why?
|
||||
|
||||
PHP is an old language. It has been growing since 1995, adopting a
|
||||
lot of features from many places like C, Perl, Java, etc. This was
|
||||
done in a very inconsistent way, as detailed by Eevee in their article
|
||||
[PHP: a fractal of bad design.](https://eev.ee/blog/2012/04/09/php-a-fractal-of-bad-design/)
|
||||
|
||||
Along the years PHP has been improving. PHP added classes, exceptions,
|
||||
interfaces, traits, type hints and checks, functional features,
|
||||
reflection, etc., etc. However, by building on top of the existing
|
||||
language without a clear design philosophy, and by keeping backwards
|
||||
compatibility, we ended up with a messy language. The article
|
||||
above goes into detail about this.
|
||||
|
||||
In spite of this, PHP has remained widely used and loved, in a
|
||||
weird way (I'd say in the same way that people love JavaScript),
|
||||
and at the time of writing PHP 8.3 is available. However,
|
||||
PHP is to my eyes fundamentally flawed, and cannot be fixed
|
||||
without completely breaking what came before.
|
||||
|
||||
This is where THP comes in. I wanted a modern language
|
||||
that could run in the same environment that PHP does.
|
||||
And I quickly realized that building on top of PHP
|
||||
in the same way that TypeScript did for JavaScript would be
|
||||
detrimental. It would be better to create a completely new
|
||||
language, treat PHP source code as a "low level" compilation
|
||||
target, and focus entirely on the new language.
|
||||
|
||||
This new language would be mainly inspired by what **I** consider the best
|
||||
designed languages out there: Rust as a baseline, Zig for
|
||||
its null and error handling and Kotlin for its OOP features.
|
||||
In a way, PHP will be adapted to, say, Rust's syntax and semantics,
|
||||
instead of having Rust adapt to PHP.
|
||||
|
||||
In pursue of this THP **will** ditch many things about PHP,
|
||||
in name of consistency. These are things that PHP devs are
|
||||
used to doing, but that I consider bad practices, hacks or
|
||||
workarounds. One example of this are variable variables on PHP:
|
||||
`$$variable`.
|
||||
|
||||
Another critical point of THP is type safety. It is a goal
|
||||
to approach the same level of type safety that have compiled
|
||||
languages like Java/Go/Rust, and leave aside dynamic typing
|
||||
as much as possible. Types cannot be turned off, you cannot
|
||||
use `Any` to avoid typechecking, and so on.
|
||||
|
||||
Finally, there are some additions to the language that I consider
|
||||
essential today: A good, unified LSP, type definitions,
|
||||
accesible documentation, an opinionated code formatter
|
||||
and plugins for major editors like VSCode and Neovim.
|
||||
|
||||
## Goals
|
||||
|
||||
- Implement a strongly typed language, without unknown types
|
||||
- Implement generics
|
||||
- Reduce implicit type conversion to a minimum.
|
||||
- Remove the inconsistencies in the language.
|
||||
- Organize the PHP stdlib.
|
||||
- Have a clear distinctions between Arrays, Tuples, Maps and Sets.
|
||||
- Implement Sum types
|
||||
- Have typings for popular libraries (like TS's `.d.ts`).
|
||||
- Have a simple instalation, with a single binary
|
||||
- Ship a **_blazingly fast_**, native binary, written in Zig.
|
||||
- Ship a language server, linter & formatter built in.
|
||||
- Configure a THP project with a single file.
|
||||
- Support in-place compilation of individual files.
|
||||
|
||||
## Not goals
|
||||
|
||||
These are **not** things that THP wants to solve or implement
|
||||
|
||||
- Be what TypeScript is for JavaScript (PHP with types).
|
||||
- Strictly adhere to PHP syntax/conventions.
|
||||
- Strictly reuse PHP syntax
|
||||
|
||||
THP **_intentionally_** uses a different syntax from PHP to signal
|
||||
that it is a different language, and has different semantics.
|
||||
|
||||
|
||||
|
||||
Version 0.0.1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user