chore: GenericsLibrary: Library tweaks and additions, more examples for

Nectar and Assembly.

Signed-off-by: Amlal El Mahrouss <amlal@nekernel.org>

11 files changed, 184 insertions, 12 deletions

diff --git a/doc/specs/SPEC_NECTAR_LANG.md b/doc/specs/SPEC_NECTAR_LANG.md
index 9663893..aade91b 100644
--- a/doc/specs/SPEC_NECTAR_LANG.md
+++ b/doc/specs/SPEC_NECTAR_LANG.md
@@ -1,19 +1,19 @@
-# Specification of Nectar
+# Specification of Nectar.
 
 ===================================
 
-# 0: General Information
+# 0: General Information:
 
 ===================================
 
 - ABI: PEF based.
 - Typing System: Weak.
 - Output: NeKernel Assembler/Netwide Assembler.
-- Platforms: OS X, NeKernel.
+- Platforms: OS X, POSIX, NeKernel.
 
 ===================================
 
-# 1: Concepts
+# 1: Concepts:
 
 ===================================
 
@@ -32,7 +32,7 @@
 
 ===================================
 
-# 2: Operators
+# 2: Operators:
 
 ===================================
 
@@ -42,11 +42,12 @@
 
 ===================================
 
-# 3: The Generics Library
+# 3: The Generics Library:
 
 ===================================
 
 Nectar runs using the Generics Library (GL) -- it contains foundational code to run nectar applications and systems.
 
 - //@ Are considered NectarDocs comments.
-- NectarDocs are used to describe behavior of the code -- some Javadoc syntax is supported. Such as: @brief, @param.
\ No newline at end of file
+- NectarDocs are used to describe behavior of the code -- some Javadoc syntax is supported. Such as: @brief, @param.
+
diff --git a/doc/specs/SPEC_NEKERNEL_ABI.md b/doc/specs/SPEC_NEKERNEL_ABI.md
index e8141ac..c72ecab 100644
--- a/doc/specs/SPEC_NEKERNEL_ABI.md
+++ b/doc/specs/SPEC_NEKERNEL_ABI.md
@@ -1,4 +1,4 @@
-# Specification of NeKernel ABI
+# Specification of NeKernel's PEF ABI.
 
 The PEF ABI has multiple versions depending on the ISA.
 
diff --git a/example/example_03_masm_sysv_linux/example.asm b/example/example_03_masm_sysv_linux/example.asm
new file mode 100644
index 0000000..c001e6c
--- /dev/null
+++ b/example/example_03_masm_sysv_linux/example.asm
@@ -0,0 +1,30 @@
+%bits 64
+public_segment .code64 main
+
+; This example shows how to write "Hello World" to stdout using
+; Linux syscall interface in x86-64 assembly (NeKernel syntax).
+
+mov [rsp+0],  0x48
+mov [rsp+1],  0x65
+mov [rsp+2],  0x6C
+mov [rsp+3],  0x6C
+mov [rsp+4],  0x6F
+mov [rsp+5],  0x20
+mov [rsp+6],  0x57
+mov [rsp+7],  0x6F
+mov [rsp+8],  0x72
+mov [rsp+9],  0x6C
+mov [rsp+10], 0x64
+mov [rsp+11], 0x0A
+
+mov rax, 1
+mov rdi, 0x01
+lea rsi, [rsp]
+mov rdx, 0x0C
+syscall
+
+mov rax, 60
+xor rdi, rdi
+syscall
+
+ret
\ No newline at end of file
diff --git a/example/example_03_masm_sysv/example.asm b/example/example_03_masm_sysv_osx/example.asm
index b2b9cdb..311536d 100644
--- a/example/example_03_masm_sysv/example.asm
+++ b/example/example_03_masm_sysv_osx/example.asm
@@ -1,6 +1,9 @@
 %bits 64
 public_segment .code64 main
 
+; This example shows how to write "Hello World" to stdout using
+; OS X syscall interface in x86-64 assembly (NeKernel syntax).
+
 mov [rsp+0],  0x48
 mov [rsp+1],  0x65
 mov [rsp+2],  0x6C
diff --git a/include/GenericsLibrary/algorithm.nhh b/include/GenericsLibrary/algorithm.nhh
new file mode 100644
index 0000000..b62faa1
--- /dev/null
+++ b/include/GenericsLibrary/algorithm.nhh
@@ -0,0 +1,34 @@
+// Copyright 2026, Amlal El Mahrouss (amlal@nekernel.org)
+// Licensed under the Apache License, Version 2.0 (See accompanying
+// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0)
+// Official repository: https://github.com/nekernel-org/nectar
+
+#ifndef NECTAR_GL_ALGORITHM_NHH
+#define NECTAR_GL_ALGORITHM_NHH
+
+//@ Free algorithm functions for GenericsLibrary.
+
+let for_each(let iterator_instance, let action)
+{
+    for (let i := iterator_instance.begin(); i < iterator_instance.end(); i += 1)
+    {
+        action(i);
+    }
+
+    return;
+}
+
+let find(let iterator_instance, let predicate)
+{
+    for (let i := iterator_instance.begin(); i < iterator_instance.end(); i += 1)
+    {
+        if (predicate(i))
+        {
+            return i;
+        }
+    }
+
+    return -1;
+}
+
+#endif //@ NECTAR_GL_ALGORITHM_NHH
\ No newline at end of file
diff --git a/include/GenericsLibrary/fstream.nhh b/include/GenericsLibrary/fstream.nhh
index 19cd935..b7a0a2e 100644
--- a/include/GenericsLibrary/fstream.nhh
+++ b/include/GenericsLibrary/fstream.nhh
@@ -45,4 +45,4 @@ impl fstream : fstream_traits
     }
 };
 
-#endif  // NECTAR_GL_FSTREAM_NHH
\ No newline at end of file
+#endif  //@ NECTAR_GL_FSTREAM_NHH
\ No newline at end of file
diff --git a/include/GenericsLibrary/iterator.nhh b/include/GenericsLibrary/iterator.nhh
index 0812861..8ff18ff 100644
--- a/include/GenericsLibrary/iterator.nhh
+++ b/include/GenericsLibrary/iterator.nhh
@@ -53,4 +53,4 @@ impl iterator : iterator_traits
     }
 };
 
-#endif  // NECTAR_GL_ITERATOR_NHH
\ No newline at end of file
+#endif  //@ NECTAR_GL_ITERATOR_NHH
\ No newline at end of file
diff --git a/include/GenericsLibrary/math.nhh b/include/GenericsLibrary/math.nhh
new file mode 100644
index 0000000..c9b66a9
--- /dev/null
+++ b/include/GenericsLibrary/math.nhh
@@ -0,0 +1,84 @@
+// Copyright 2026, Amlal El Mahrouss (amlal@nekernel.org)
+// Licensed under the Apache License, Version 2.0 (See accompanying
+// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0)
+// Official repository: https://github.com/nekernel-org/nectar
+
+#ifndef NECTAR_GL_FUNCTIONS_NHH
+#define NECTAR_GL_FUNCTIONS_NHH
+
+//@ Free math functions for GenericsLibrary.
+
+let min(let a, let b)
+{
+    if (a < b)
+    {
+        return a;
+    }
+    else
+    {
+        return b;
+    }
+}
+
+let max(let a, let b)
+{
+    if (a > b)
+    {
+        return a;
+    }
+    else
+    {
+        return b;
+    }
+}
+
+let abs(let value)
+{
+    if (value < 0)
+    {
+        return -value;
+    }
+    else
+    {
+        return value;
+    }
+}
+
+let clamp(let value, let min_value, let max_value)
+{
+    if (value < min_value)
+    {
+        return min_value;
+    }
+    else if (value > max_value)
+    {
+        return max_value;
+    }
+    else
+    {
+        return value;
+    }
+}
+
+let lerp(let a, let b, let t)
+{
+    return a + t * (b - a);
+}
+
+let sign(let value)
+{
+    if (value > 0)
+    {
+        return 1;
+    }
+    else if (value < 0)
+    {
+        return -1;
+    }
+    else
+    {
+        return 0;
+    }
+}
+
+#endif //@ NECTAR_GL_FUNCTIONS_NHH
\ No newline at end of file
diff --git a/include/GenericsLibrary/swap.nhh b/include/GenericsLibrary/swap.nhh
new file mode 100644
index 0000000..7090535
--- /dev/null
+++ b/include/GenericsLibrary/swap.nhh
@@ -0,0 +1,20 @@
+// Copyright 2026, Amlal El Mahrouss (amlal@nekernel.org)
+// Licensed under the Apache License, Version 2.0 (See accompanying
+// file LICENSE or copy at http://www.apache.org/licenses/LICENSE-2.0)
+// Official repository: https://github.com/nekernel-org/nectar
+
+#ifndef NECTAR_GL_SWAP_NHH
+#define NECTAR_GL_SWAP_NHH
+
+//@ Free swap functions for GenericsLibrary.
+
+let swap(let a, let b)
+{
+    let temp := a;
+    a := b;
+    b := temp;
+
+    return;
+}
+
+#endif //@ NECTAR_GL_SWAP_NHH
\ No newline at end of file
diff --git a/include/ThirdParty/.keep b/include/ThirdParty/.keep
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/include/ThirdParty/.keep
diff --git a/src/DebuggerKit/src/POSIXMachContractCLI.cc b/src/DebuggerKit/src/POSIXMachContractCLI.cc
index 5b8ab21..dd1411c 100644
--- a/src/DebuggerKit/src/POSIXMachContractCLI.cc
+++ b/src/DebuggerKit/src/POSIXMachContractCLI.cc
@@ -9,7 +9,7 @@
 #include <DebuggerKit/POSIXMachContract.h>
 #include <ThirdParty/Dialogs/Dialogs.h>
 
-#ifdef __APPLE__
+#ifdef DK_MACH_DEBUGGER
 #include <DebuggerKit/Common.inl>
 
 /// @internal
@@ -38,7 +38,7 @@ NECTAR_MODULE(DebuggerMachPOSIX) {
     kStdOut << "[+] Image set to: " << kPath << "\n";
   } else {
     kStdOut << "usage: " << argv[0] << " -p <path>\n";
-    kStdOut << "example: " << argv[0] << " -p /path/to/program\n";
+    kStdOut << "example: " << argv[0] << " -p </path/to/program>\n";
 
     return EXIT_FAILURE;
   }