Merge pull request #9 from angelcaru/update-docs

Update the docs

Author: Almas-Ali

docs/arrays.md

@@ -13,7 +13,7 @@
   start index to the specified end index
 
 ```rn linenums="1" title="methods.rn"
-arr = [1, 2, 3, 4, 5]
+const arr = [1, 2, 3, 4, 5]
 print(arr_len(arr)) # 5
 
 arr_push(arr, 6)
@@ -40,8 +40,8 @@ print(arr_slice(arr, 0, 5)) # [1, 2, 3, 4, 5]
 - `*` (repetition)
 
 ```rn linenums="1" title="operators.rn"
-arr1 = [1, 2, 3]
-arr2 = [4, 5, 6]
+const arr1 = [1, 2, 3]
+const arr2 = [4, 5, 6]
 
 print(arr1 + arr2) # [1, 2, 3, 4, 5, 6]
 print(arr1 * 2) # [1, 2, 3, 1, 2, 3]

docs/classes.md

@@ -6,7 +6,7 @@ Object Oriented Programming (OOP) is a programming paradigm that uses objects
 and their interactions to design and program applications. It is based on the
 concept of objects rather than just functions and procedures. These objects
 are organized into classes, which allow individual objects to be grouped
-together. Most modern programming languages including Java, C/C++, and Python
+together. Most modern programming languages including Java, C++, and Python
 are object-oriented languages, and many older programming languages now have
 object-oriented versions.
 
@@ -32,42 +32,22 @@ object by simply calling the class like as a function. It is followed by the
 name of the class and the arguments in parentheses. The arguments are optional.
 
 ```rn linenums="1" title="objects.rn"
-person = Person()
+const person = Person()
 ```
 
 ## Fields
 
 Fields are the variables that are declared inside a class. They are used to
 store data. They are also called instance variables because they are unique
-to each instance of the class. They are declared using the `var` keyword. It
-is followed by the name of the field and the type of the field.
-The type of the field is optional.
+to each instance of the class. They are declared like any variable.
 
 ```rn linenums="1" title="fields.rn"
 class Person {
-    name = "John"
-    age = 20
+    var name = "John"
+    var age = 20
 }
 ```
 
-## Constructors
-
-Constructors are special methods that are used to initialize the fields of a
-class. They are called when an object is created. They are declared using the
-`fun` keyword. It is followed by the name (class name) of the constructor and
-the parameters in parentheses. The parameters are optional.
-
-```rn linenums="1" title="constructors.rn"
-class Person {
-    fun Person(name, age) {
-        this.name = name
-        this.age = age
-    }
-}
-
-person = Person("John", 20)
-```
-
 ## Methods
 
 Methods are the functions that are declared inside a class. They are used to
@@ -90,3 +70,27 @@ class Person {
 person = Person("John", 20)
 person.say_hello() # Output: Hello, John!
 ```
+
+## Magic Methods/Operator Overloading
+You may have noticed we declared a method called `__constructor__` in the above example. This is an example of a magic method. Magic methods are used for operator overloading. Here is an incomplete list:
+
+| Method Name | Operator | Example | Example if we used regular function calls instead of operators |
+|-------------|----------|---------|----------------------------------------------------------------|
+`__constructor__` | Class instantiation | `var foo = Foo(1, 2, 3)` | `var foo = create(Foo); foo.__constructor(1, 2, 3)`[^create_func] |
+`__add__` | Addition | `a + b` | `a.__add__(b)` |
+`__sub__` | Subtraction | `a - b` | `a.__sub__(b)` |
+`__mul__` | Multiplication | `a * b` | `a.__mul__(b)` |
+`__div__` | Division | `a / b` | `a.__div__(b)` |
+`__pow__` | Exponentiation | `a ^ b` | `a.__pow__(b)` |
+`__eq__` | Equality | `a == b` | `a.__eq__(b)` |
+`__ne__` | Non-equality | `a != b` | `a.__ne__(b)` |
+`__call__` | Calling | `f(1, 2, 3)` | `f.__call__(1, 2, 3)` |
+`__getitem__` | Subscripting | `a[b]` | `a.__getitem__(b)` |
+`__setitem__` | Subscripting | `a[b] = c` | `a.__setitem(b, c)` |
+`__contains__` | `in` | `a in b` | `b.__contains__(a)` |
+`__truthy__` | Implicit conversions to bool | `if x { ... }` | `if x.__truthy__() { ... }`[^truthy_errors][^truthy_recursion]
+
+
+[^create_func]: `create` doesn't actually exist. It's just pseudocode
+[^truthy_errors]: If `__truthy__` throws an error, it is ignored and treated as if it returned `false`
+[^truthy_recursion]: The `__truthy__` operator of the returned object will be called recursively until it is a `bool`

docs/data-types.md

@@ -4,8 +4,7 @@
 
 The basic types are:
 
-- `int` - integer number.
-- `float` - floating point number.
+- `number` - floating point number
 - `bool` - boolean value.
 - `string` - string of characters.
 
@@ -15,8 +14,7 @@ Arrays are declared using the `[]` syntax. The type of the array is the type
 of the elements it contains.
 
 ```rn linenums="1" title="arrays.rn"
-a = [1, 2, 3] # a is an array of ints
-b = [1.0, 2.0, 3.0] # b is an array of floats
+a = [1, 2, 3] # a is an array of numbers
 c = ["a", "b", "c"] # c is an array of strings
 
 # Arrays can be nested
@@ -28,22 +26,21 @@ e = [] # e is an empty array of unknown type
 
 ## Hashmaps
 
-Hashmaps (or objects) are declared using the `{}` syntax.
-The type of the object is the type of the fields it contains.
+Hashmaps are declared using the `{}` syntax.
 
-```rn linenums="1" title="objects.rn"
-# a is an object with fields x and y of type int
-a = { x: 1, y: 2 };
-# b is an object with fields x and y of type float
-b = { x: 1.0, y: 2.0 };
-# c is an object with fields x and y of type string
-c = { x: "a", y: "b" };
+```rn linenums="1" title="hashmaps.rn"
+const a = { "x": 1, "y": 2 }
+const b = { "x": 1.0, "y": 2.0 }
+const c = { "x": "a", "y": "b" }
 
-# Objects can be nested
-# d is an object with fields x and w of type object
-d = { x: { y: 1, z: 2 }, w: { y: 3, z: 4 } };
+# Hashmaps can be nested
+const d = { "x": { "y": 1, "z": 2 }, "w": { "y": 3, "z": 4 } }
 
-# Objects can be empty
-# e is an empty object of unknown type
-e = {};
+# Hashmaps can be empty
+const e = {}
+
+# Hashmaps can be initialized with keys known at runtime
+const key = "foo"
+const f = {key: "bar"}
+print(f["foo"]) # -> bar
 ```

docs/error-handling.md

@@ -13,7 +13,7 @@ the code that handles the exception.
 ```rn linenums="1" title="exceptions.rn"
 try {
     # code that may throw an exception (in this case, zero division)
-    a = 1 / 0
+    1 / 0
 } catch as err {
     # code that handles the exception
     print("Exception caught: " + err)
@@ -33,7 +33,7 @@ use the exception message, you can omit the variable.
 ```rn linenums="1" title="exceptions.rn"
 try {
     # code that may throw an exception
-    a = 1 / 0
+    1 / 0
 } catch as _ {
     # code that handles the exception
     print("Exception caught")
@@ -65,10 +65,10 @@ if 2 != 4 {
 ```rn
 Radiation (most recent call last):
   File <stdin>, line 2
-ValueError: 2 + 2 != 4
+ValueError: 2 != 4
 
-    raise radiation.ValueError("2 + 2 != 4")
-          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+    raise radiation.ValueError("2 != 4")
+          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ```
 
@@ -92,7 +92,7 @@ raise CustomError("custom-error.rn")
 ```rn
 Radiation (most recent call last):
   File <stdin>, line 5
-FunctionError: Something went wrong in custom-error.rn
+CustomError: Something went wrong in custom-error.rn
 
 raise CustomError("custom-error.rn")
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/file-handling.md

@@ -14,7 +14,7 @@ read and write files in Radon.
 
 When opening a file, we can specify the mode in which we want to open the file.
 
-The modes are:
+The modes are the same as in C fopen() or Python open():
 
 - `r`: Read mode. Opens the file for reading. The file must exist.
 - `w`: Write mode. Opens the file for writing. If the file does not exist,
@@ -39,24 +39,24 @@ instance of `File` class by passing the file path to the constructor. We can
 then use the `read` method to read the contents of the file.
 
 ```rn linenums="1" title="file-handling.rn"
-file = File("file.txt")
-content = file.read()
+const file = File("file.txt")
+const content = file.read()
 print(content)
 ```
 
 You can also read the file line by line using the `readline` method.
 
 ```rn linenums="1" title="file-handling.rn"
-file = File("file.txt")
-line = file.readline()
+const file = File("file.txt")
+const line = file.readline()
 print(line)
 ```
 
 You can also read all the lines of the file using the `readlines` method.
 
 ```rn linenums="1" title="file-handling.rn"
-file = File("file.txt")
-lines = file.readlines()
+const file = File("file.txt")
+const lines = file.readlines()
 print(lines)
 ```
 
@@ -66,7 +66,7 @@ To write to a file, we use the `write` method. We can pass the content to the
 `write` method to write to the file.
 
 ```rn linenums="1" title="file-handling.rn"
-file = File("file.txt")
+const file = File("file.txt", "w")
 file.write("Hello, World!")
 ```
 
@@ -76,7 +76,7 @@ After reading or writing to a file, it is important to close the file. We can
 use the `close` method to close the file.
 
 ```rn linenums="1" title="file-handling.rn"
-file = File("file.txt")
+const file = File("file.txt", "r")
 # code that reads or writes to the file
 file.close()
 ```

docs/functions.md

@@ -24,7 +24,7 @@ fun add(a, b) {
 ### Anonymous functions
 
 ```rn linenums="1" title="anonymous_functions.rn"
-add = fun (a, b) {
+const add = fun (a, b) {
     return a + b
 }
 ```
@@ -38,12 +38,17 @@ fun add(a, b) -> a + b
 ## Calling functions
 
 Calling a function is done by using the function name followed by the arguments
-in parentheses.
+in parentheses, like in all C-like languages.
 
 ```rn linenums="1" title="calling_functions.rn"
 add(1, 2) # Output: 3
 ```
 
+There are also keyword arguments:
+```rn linenums="1" title="kwargs.rn"
+add(a=34, b=35) # Output: 69
+```
+
 That's it! You now know how to call functions in Radon.
 
 ## Function parameters
@@ -75,3 +80,18 @@ fun new_user(name="Guest") {
 new_user() # Output: Hello, Guest!
 new_user("World") # Output: Hello, World!
 ```
+
+## Variadic parameters
+```rn linenums="1" title="variadics.rn"
+fun sum(...nums) {
+    var ret = 0
+    for x in nums {
+        ret += x
+    }
+    return ret
+}
+
+sum(1, 2, 3) # Output: 6
+sum(1, 2, 3, 4) # Output: 10
+sum() # Output: 0
+```

docs/input-output.md

@@ -17,6 +17,6 @@ followed by the argument in parentheses. The argument are mandatory. It takes
 only one argument. We can concatenate data types using the `+` operator.
 
 ```rn linenums="1" title="input.rn"
-name = input("Enter your name: ")
+const name = input("Enter your name: ")
 print("Hello, " + name + "!") # Output: Hello, World!
 ```

docs/loops.md

@@ -105,7 +105,7 @@ o
 Here we are using `HashMap`. The loop will run for each key in the `HashMap`.
 
 ```rn linenums="1" title="for_hashmap.rn"
-hash = {"name": "John", "age": 30}
+const hash = {"name": "John", "age": 30}
 for i in hash {
     print("Key: " + i)
     print("Value: " + hash[i])
@@ -127,10 +127,10 @@ With while loop we can specify the condition.
 The loop will run until the condition is true.
 
 ```rn linenums="1" title="while.rn"
-i = 0
+var i = 0
 while i < 5 {
     print(i)
-    nonlocal i += 1
+    i += 1
 }
 ```
 
@@ -144,9 +144,6 @@ while i < 5 {
 4
 ```
 
-We have used `nonlocal` keyword to update the value of `i` in the loop.
-If we don't use `nonlocal` then it will run into infinite loop.
-
 ## Loop control statements
 
 In Radon we have 2 loop control statements.
@@ -229,14 +226,14 @@ for i=0 to 5 {
 While loop example:
 
 ```rn linenums="1" title="while_continue.rn"
-i = 0
+var i = 0
 while i < 5 {
     if i == 3 {
-        nonlocal i += 1
+        i += 1
         continue
     }
     print(i)
-    nonlocal i += 1
+    i += 1
 }
 ```