Merge pull request #5 from Isible/rewrite

Rewrite

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "key": "alt+s",
+    "command": "editor.action.smartSelect.grow",
+    "when": "editorTextFocus"
+}

Cargo.toml

@@ -1,18 +1,10 @@
 [package]
-name = "nexus"
+name = "nexus-lib"
 version = "0.1.0"
 edition = "2021"
-
-description = "A modern and simple scripting language"
 license = "MIT"
-repository = "https://github.com/MuffinGroup/nexus"
 readme = "README.md"
-
-authors = ["Thepigcat76 <benpospo@gmail.com>", "TheHackerChampion"]
-keywords = ["rust", "nexus", "scripting", "language"]
-homepage = "https://muffingroup.github.io/MuffinSite/"
+description = "The raw implementation of the nexus scripting language"
 
 [dependencies]
-clutils = "0.0.3"
-colored = "2.0.4"
-maplit = "1.0.2"
+clutils = "0.0.7"

README.md

@@ -50,7 +50,7 @@ Let's start off simple with a "Hello, World" program
 print("Hello, World")
 ```
 
-Let's start defining some variables to make our code cleaner and life bit easier
+Let's start defining some variables to make our code cleaner and more flexible
 
 ```kotlin
 var message = "Hello, World!"

design/null-handling.md

@@ -0,0 +1,125 @@
+# Null handling
+
+## The Problem with null/none
+
+Null or None as it is called in some programming languages, bears a huge risk: Using a null-value where a non-null-value is expected, leading to errors, crashes or even undefined behaviour.
+
+However, not having a null/none type in many cases is as bad if not even worse than having one. Since the absense of this concept leads to people using others ways to display the absence of a value which due to not being handled as well as null can lead to the same bugs that are a lot harder to debug.
+
+And if you don't have any ideas, just take **inspiration** from other languages :p
+
+## Taking a look at other languages
+
+Let's look at other languages and how they handle intializing a nullable value
+
+### Kotlin
+
+Let's look at this kotlin code to see a very simple example of using null
+
+```kotlin
+fun main() {
+    var test: String? = "Hello"
+    test = null
+}
+```
+
+As you might have realised there is a question mark behind the type annotation which indicates that we want the variable to be able to represent `null`.
+
+While this system is very intuitive, this is also one of its main flaws, sice you don't want null to be intuitive or people will use it without thinking about it twice, leading to the previously mentioned problems.
+
+So let's take a look at the next language, `rust`!
+
+### Rust
+
+```rust
+fn main() {
+    let mut test: Option<&str> = Some("Hello");
+    test = None;
+}
+```
+
+As you might have realized, this is a lot more code than the kotlin example. And if you also looked at the type you can spot that unlike the previous example this is not actually a direct string but a wrapper around it.
+
+While this is not as intuitive and simple as the kotlin example it also makes the user think twice if they actually want to/need to use null and also makes them aware of the potential null value beforehand.
+
+### Conclusion
+
+While I praised rust's implementation a lot, I think that in the context of a simple, interpreted, beginner-friendly language it does not make sense to use a complex system like that but rather take a closer look at kotlin.
+
+## Null references
+
+Before we actually take a look at how we ourselves can fix the issue, we also need to consider the other part of the puzzle: Referencing a value that potentially is a null value.
+
+### Kotlin
+
+While kotlin's solution looks a lot more distinct from rust, under the hood they basically work the same. You have a wrapper for the value and when you want to access it you have to consider that the value might be null. There are two effective ways to do so:
+
+#### 1. The safe approach
+
+We pass on the value to the next variable until we are ready to safely unwrap it
+
+```kotlin
+fun main() {
+    var test: String? = null
+    val firstChar: Char? = test?.get(0)
+    //                         ^ this way we safely call the method
+    if firstChar != null {
+        // unwrap the value and do something with it
+    }
+}
+```
+
+#### 2. The unsafe approach
+
+We just unwrap the value regardless of whether it might be null or not and risk throwing an error.
+
+```kotlin
+fun main() {
+    var test: String? = "Test"
+    var firstChar: Char = test!!.get(0)
+    //                        ^^ this way we just unwrap the value  
+}
+```
+
+### Rust
+
+As previously stated both rust and kotlin's systems works similar. The biggest difference most likely is the difference in handling the nullable value.
+
+#### 1. The safe approach
+
+```rust
+fn main() {
+    let test: Option<&str> = Some("Hello");
+    // Test if the value is none or not-none. Match statement is pretty much the same as kotlin and nexus' `when` statement
+    match test {
+        Some(val) => println("{}", val), // print the value if it is not-none
+        None => (), // do nothing if the value is None
+    }
+}
+```
+
+#### 2. The unsafe approach
+
+```rust
+fn main() {
+    let test: Option<&str> = Some("Hello");
+    println!("{}", test.unwrap()); // We just use tha value and risk it being none. Luckily rust directly throws an error when trying to unwrap the value, before we can do even more damage
+}
+```
+
+### Conclusion
+
+Personally I think having a mix between kotlin and rust's safe none handling would be be best so we will go with something along those lines. As for the unsafe approach however, I prefer rust.
+
+
+## Our own solution
+
+```kotlin
+const myVal? = none
+#          ^ we use the question mark, similar to kotlin but without requiring the type
+
+when myVal? {
+    none -> (),
+    else -> puts(myVal), # we can safely use myVal now and dont need to unwrap it
+}
+```

docs/beginnners/advanced_variables.md

@@ -4,7 +4,7 @@ This guide will teach you more about variables and data types.
 
 ## The difference between `const` and `var`
 
-### Mutatable variables
+### Mutable variables
 
 In nexus, there are two ways to define a variable. The first way, we have already talked about is by using `var`.
 
@@ -20,7 +20,7 @@ x = 2 // Here we give the variable x a new value
 print(x) // And here we print the variables value
 ```
 
-This will output the value 2 as we reassigned x before outputting it.
+This will output the value `2` as we reassigned `x` to this value before outputting it.
 
 As you already saw you can reassign variables by using their name (`x`), `=` and the new value (`2`)
 
@@ -35,18 +35,19 @@ Let's look at this for a quick example quick example:
 ```go
 const y = 0 // We assign 0 to the variable y
 
-y = 2 // We try to reassign this value, but it throws an error. Because it is a const
+y = 2 // We try to reassign this value, but it throws an error. Because it is constant
 ```
 
 As you can see it is not possible to reassign this variable because it will throw an error.
+We can still use this like any other variable however.
 
 ## Type annotations
 
 Another common cause of bugs are type modifications.
 
 For example:
 ```go
-// We define the variable name and give it the value "John". As we learned in the previous tutorial, this text's datatype is called string and it always has to be in quotation marks.
+// We define the variable name and give it the value "John". As we learned in the previous tutorial, this variables's datatype is called string and it always has to be in quotation marks.
 var name = "John"
 
 // We mistake this variable for the age and give it the value 45
@@ -99,4 +100,6 @@ y :: 0
 
 We now know how to quickly assign variables. Amazing!
 
-**The end**
+## The end (for now)
+
+Great, you now know everything about variables and constants. In the next tutorial we will take a look at one of the most important features of any programming language: [Functions](functions.md)

docs/beginnners/functions.md

@@ -6,10 +6,9 @@ You might already know about functions in mathematics but we will still elaborat
 
 ## The theory behind functions
 
-Like variables can be used to store values, functions are used to store a sequence of functions and variables.
-
-Like most topics it will take some time before you fully understand how functions work
+Like variables they can be used to store values, functions in particular mainly are used to store a sequence of functions and variables.
 
+Disclaimer: Like most topics it will take some time before you fully understand how functions work but don't be discouraged by that :)
 ## Functions in Nexus
 
 As previously stated, this will be a learning by doing experience so let's just dive into the code

docs/beginnners/setup.md

@@ -1,9 +1,9 @@
 # Setup
 
-1. Start by installing the Nexus interpreter from <https://github.com/MuffinGroup/nexus/releases>
+1. Start by installing the Nexus interpreter from <https://github.com/MuffinGroup/nexus/releases> [WIP]
 
 2. Install an IDE (Integrated Development Environment) or Text Editor like [Visual Studio Code](https://code.visualstudio.com/) or our upcoming editor [Void](https://github.com/MuffinGroup/void)
 
-3. Install an extension if nessecary [WIP]
+3. Install the extension if nessecary [WIP]
 
 4. Run the commands `nexus` and `matrix` in your console (Matrix is not yet part of the Nexus distribution) to check if Nexus is installed.

docs/beginnners/your_first_program.md

@@ -8,7 +8,7 @@ After you have finished the [setup](setup.md), create your first nexus script fi
 
 Note: The file has to end with .nx
 
-Now we can finally start writing code! An important notice though: Especially in more complex examples, copy the code by hand and not some keyboard shortcuts.
+Now we can finally start writing code! An important notice though: Especially in more complex examples, I advise you to type the code by hand and not some keyboard shortcuts.
 
 ## Writing the code
 
@@ -55,7 +55,7 @@ In nexus we define variables with the `var` keyword and then assign a value to i
 
 The next thing you might notice is that we have changed the print(...) function. This change allows us to print out the value of the `name` variable. When you see curly brackets (`{...}`) in a String (String = sequence of words encased by quotation marks) most of the time this means that we want to use the value of the variable in the String.
 
-**IMPORTANT:** Variable names are only allowed to have letters (abc...z), numbers (not at the beginning tho) and underscores `_`
+**IMPORTANT:** Variable names are only allowed to have letters `abc...z`, `numbers` (not at the beginning tho) and underscores `_`
 
 **Challenge:** Print your own name and change the variable name to be `my_name`
 
@@ -81,9 +81,15 @@ This can be any number between 0 and infinite
 var age = 9
 ```
 
+Numbers can also be represented more precisely with a floating point
+
+```go
+var age = 0.9123
+```
+
 **Booleans:**
 
-Although the name sounds complex, booleans are very simple. They can represent two values: `true or false`
+Although the name sounds complex, booleans are very simple. They can represent two values: `true` or `false`
 
 ```go
 var is_cool = true
@@ -93,4 +99,4 @@ var has_skill_issue = false
 
 ## The End (for now)
 
-This is the end of the first tutorial. More to come soon!
+The next chapter will cover how to use handle variables even better [Advanced-variables](advanced_variables.md)