From 5b260e2f6fe3bd49614782c7dfa69e429c9d1e4d Mon Sep 17 00:00:00 2001
From: Araozu <fernando@araozu.dev>
Date: Sat, 15 Jun 2024 22:26:44 -0500
Subject: [PATCH] Add explanation for indentation

---
 src/pages/learn/cheatsheet.md    |  62 +++++++++++++++++++
 src/pages/learn/index.mdx        |   1 +
 src/pages/spec/ast/expression.md |   8 +++
 src/pages/spec/index.md          | 101 +++++++++++++++++++++++++++++--
 4 files changed, 167 insertions(+), 5 deletions(-)
 create mode 100644 src/pages/learn/cheatsheet.md
 create mode 100644 src/pages/spec/ast/expression.md

diff --git a/src/pages/learn/cheatsheet.md b/src/pages/learn/cheatsheet.md
new file mode 100644
index 0000000..b50dea0
--- /dev/null
+++ b/src/pages/learn/cheatsheet.md
@@ -0,0 +1,62 @@
+---
+layout: ../../layouts/DocsLayout.astro
+title: Cheatsheet
+---
+
+# Language cheatsheet
+
+Comparisons to PHP are noted.
+
+```thp
+// THP code is written directly, it's not enclosed in any ?php tag
+
+// Single line comments are written with two slashes 
+
+/*
+    Multiline comments use slash-asterisk
+    and can be /* nested */
+*/
+
+// print writes input to stdout in terminal mode
+print("Hello world")
+```
+
+## Types and variables
+
+```thp
+// Variables are always declared
+// Variables don't start with a dollar sign ($)
+// Variables are declared with `var`
+var age = 32
+
+// Immutable variables are declared with `val`,
+// and can't be reassigned
+val name = "John"
+
+// A variable name starts with either a:
+//  - lowercase letter
+//  - underscore
+// and then may contain any letter, underscore or number
+val my_variable = "my value"
+
+// Datatypes' names start with an uppercase letter, always
+// A declaration may optionally specifiy its datatype, after
+// the var/val keyword
+var String lastname = "Doe"
+
+//
+// Bool
+//
+
+// Booleans are only `true` and `false`, case sensitive
+val condition = true
+val accepted  = false
+
+//
+// Int
+//
+
+
+```
+
+
diff --git a/src/pages/learn/index.mdx b/src/pages/learn/index.mdx
index f5c2c44..1ce4ea2 100644
--- a/src/pages/learn/index.mdx
+++ b/src/pages/learn/index.mdx
@@ -4,6 +4,7 @@ title: Welcome
 pagesLayout:
 - path: index
 - path: install
+- path: cheatsheet
 - path: basics
   title: Basics
   children:
diff --git a/src/pages/spec/ast/expression.md b/src/pages/spec/ast/expression.md
new file mode 100644
index 0000000..62e2eed
--- /dev/null
+++ b/src/pages/spec/ast/expression.md
@@ -0,0 +1,8 @@
+---
+layout: ../../../layouts/SpecLayout.astro
+title: Expression
+---
+
+# Expression
+
+Expression
diff --git a/src/pages/spec/index.md b/src/pages/spec/index.md
index a6f40b9..41594b4 100644
--- a/src/pages/spec/index.md
+++ b/src/pages/spec/index.md
@@ -18,6 +18,7 @@ pagesLayout:
   title: THP AST
   children:
   - path: ast
+  - path: expression
 ---
 
 
@@ -120,10 +121,100 @@ if true {   // 0 indentation
 }
 ```
 
-These tokens are used to detect when a expression is done, instead of relying on
-semicolons. This is performed by the parser.
-
-Every other production of the grammar doesn't care about whitespace/indentation, so
-those ignore whitespace.
+All productions of the grammar ignore whitespace/indentation, except those involved in
+semicolon inference.
+
+
+## Statement termination / Semicolon inference
+
+**Only inside a block of code** whitespace is used to determine where a statement ends
+and a new one begins. Everywhere else whitespace is ignored.
+
+Statements in THP end when a new line is encountered:
+
+
+
+```thp
+// The statement ends         | here, on the newline
+val value = (123 + 456) * 0.75
+```
+
+```thp
+// Each line contains a different statement. They all end on their new lines
+
+var a = 1 + 2   // a = 3
++ 3             // this is not part of `a`, this is a different statement
+```
+
+This is true even if the line ends with an operator:
+
+```thp
+// These are still different statements
+
+var a = 1 + 2 +     // This is now a compile error, there is a hanging `+`
+3                   // This is still a different statement
+```
+
+
+### Parenthesis
+
+Exception 1: When a parenthesis is open, all following whitespace is ignored
+until the closing parenthesis.
+
+```thp
+// open parenthesis found, all whitespace is ignored until the closing
+name.contains(
+"weird"
+    )
+```
+
+However, for a parenthesis to begin to act, it needs to be open on the same line.
+
+```thp
+// Still 2 statements, because the parenthesis is in a new line
+print
+(
+    "hello"
+)
+
+// Now it's one single statement
+print(
+    "hello"
+)
+```
+
+### Indented binary operator
+
+Exception 2:
+
+- When a binary operator is followed by indentation:
+
+```thp
+val sum = 1 + 2 +   // The line ends with a binary operator
+    3               // There is indentation
+```
+
+- Or when indentation is followed by a binary operator:
+
+```thp
+val sum = 1 + 2
+    + 3             // Indentation and a binary operator
+```
+
+In theses cases, all whitespace will be ignored
+until the indentation returns to the initial level.
+
+```thp
+// This method chain is a single statement because of the indentation
+val person = PersonBuilder()
+    .set_name("john")
+    .set_lastname("doe")
+    .set_age(32)
+    .set_children(2)
+    .build()
+
+// Here indentation returns, and a new statement begins
+print(person)
+```