From 72f31898bdd3bf33883d7ab52775f43f32df62d5 Mon Sep 17 00:00:00 2001
From: pmqueiroz <pedroqueiroz593@gmail.com>
Date: Wed, 6 Nov 2024 16:24:12 -0300
Subject: [PATCH] docs: add hello world, loops, values and variables examples

---
 docs/docs/examples/hello-word.md | 21 +++++++++++++++
 docs/docs/examples/loops.md      | 44 ++++++++++++++++++++++++++++++++
 docs/docs/examples/values.md     | 33 ++++++++++++++++++++++++
 docs/docs/examples/variables.md  | 33 ++++++++++++++++++++++++
 docs/mkdocs.yml                  | 13 ++++++++++
 5 files changed, 144 insertions(+)
 create mode 100644 docs/docs/examples/hello-word.md
 create mode 100644 docs/docs/examples/loops.md
 create mode 100644 docs/docs/examples/values.md
 create mode 100644 docs/docs/examples/variables.md

diff --git a/docs/docs/examples/hello-word.md b/docs/docs/examples/hello-word.md
new file mode 100644
index 0000000..3f9ffd9
--- /dev/null
+++ b/docs/docs/examples/hello-word.md
@@ -0,0 +1,21 @@
+This example demonstrates how to print a message to the terminal using the Umbra language.
+
+### Code
+
+```u title="hello-world.u" hl_lines="3"
+import "io"
+
+io::printLn("Hello world")
+```
+
+### How to Run
+
+To run the code above, save it in a file with the `.u` extension, such as `hello-world.u`. Then, execute the command:
+
+```sh
+umbra hello-world.u
+```
+
+This command will display `Hello world` in the terminal, showcasing the basic output functionality in Umbra.
+
+Next example: [Values](/examples/values)
diff --git a/docs/docs/examples/loops.md b/docs/docs/examples/loops.md
new file mode 100644
index 0000000..8826ba0
--- /dev/null
+++ b/docs/docs/examples/loops.md
@@ -0,0 +1,44 @@
+In Umbra, for is the only looping construct, offering two distinct forms: the initialized `for` statement and the conditional for statement.
+
+### Initialized
+
+The initialized `for` loop has an initializer, stop condition, and an optional step value, structured as 
+
+```u title="loops.u"
+for mut i num = 0, 10, 2 {
+  io::printLn(i)
+}
+```
+where `i` starts at `0`, runs until `10`, and increments by `2` on each iteration, resulting in
+
+```
+0
+2
+4
+6
+8
+10
+```
+### Conditional
+
+The conditional `for` loop, on the other hand, is structured with a condition, executing as long as the condition remains true.
+
+```u title="loops.u"
+if i < 10 {
+  
+}
+```
+
+If no condition is specified, the loop becomes infinite, running until explicitly broken with `break`.
+
+```u title="loops.u"
+mut i num = 0
+
+for {
+  if i > 10 {
+    break
+  }
+
+  i = i + 1
+}
+```
diff --git a/docs/docs/examples/values.md b/docs/docs/examples/values.md
new file mode 100644
index 0000000..0df3036
--- /dev/null
+++ b/docs/docs/examples/values.md
@@ -0,0 +1,33 @@
+Umbra has various value types including strings (`str`), numbers (`num`), booleans (`bool`), etc. Here are a few basic examples.
+
+Strings, which can be added together with +.
+
+```u title="values.go"
+io::printLn("umbra" + "lang")
+```
+Numbers.
+
+```u title="values.go"
+io::printLn("1+1 =", 1+1)
+io::printLn("7/3 =", 7/3)
+```
+
+Booleans, with boolean operators as you’d expect.
+
+```u title="values.go"
+io::printLn(true and false)
+io::printLn(true or false)
+io::printLn(!true)
+```
+
+```sh
+$ go run values.go
+# golang
+# 1+1 = 2
+# 7.0/3.0 = 2.3333333333333335
+# false
+# true
+# false
+```
+
+Next example: [Variables](/examples/variables)
diff --git a/docs/docs/examples/variables.md b/docs/docs/examples/variables.md
new file mode 100644
index 0000000..802e74d
--- /dev/null
+++ b/docs/docs/examples/variables.md
@@ -0,0 +1,33 @@
+In Umbra, variables must always be explicitly typed, with the option to declare them as either `const` or `mut`, providing control over immutability and mutability in code.
+
+### Mutable and constants
+
+```u title="types.u"
+const name str = "Peam"
+mut age num = 24
+const fool bool = true
+
+mut person hashmap = {
+  name: name,
+  age: age,
+}
+
+const people arr = [person]
+```
+
+### Nullable
+
+Additionally, by adding a `?` after the type, a variable can be made nullable, allowing it to hold either a value of the specified type or `null`.
+
+```u title="types.u"
+mut name str? = "Peam"
+name = null
+```
+
+!!! info "Not initialized"
+    Variables not initialized should be set as nullable when declaring
+    ```u title="types.u"
+    mut name str?
+    ```
+
+Next example: [Loops](/examples/loops)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 4a33ea5..9a3cdd7 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -9,6 +9,11 @@ nav:
   - Libs:
     - "Math": libs/math.md
     - IO: libs/io.md
+  - "Umbra by example":
+    - "Hello World": examples/hello-word.md
+    - "Values": examples/values.md
+    - "Variables": examples/variables.md
+    - "Loops": examples/loops.md
 
 theme:
   name: material
@@ -17,6 +22,8 @@ theme:
   favicon: assets/favicon.png
   palette:
     primary: custom
+  features:
+    - content.code.copy
 
 extra_css:
   - styles/global.css
@@ -31,6 +38,12 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
   - admonition
   - pymdownx.details
   - pymdownx.superfences