Put comments into example scripts.

README.md

@@ -50,8 +50,8 @@ Optional features
 | `no_index`    | Disable arrays and indexing features if not needed.                                                                                                      |
 | `no_float`    | Disable floating-point numbers and math if not needed.                                                                                                   |
 | `no_optimize` | Disable the script optimizer.                                                                                                                            |
-| `only_i32`    | Set the system integer type to `i32` and disable all other integer types.                                                                                |
+| `only_i32`    | Set the system integer type to `i32` and disable all other integer types. `INT` is set to `i32`.                                                         |
-| `only_i64`    | Set the system integer type to `i64` and disable all other integer types.                                                                                |
+| `only_i64`    | Set the system integer type to `i64` and disable all other integer types. `INT` is set to `i64`.                                                         |
 
 By default, Rhai includes all the standard functionalities in a small, tight package.  Most features are here to opt-**out** of certain functionalities that are not needed.
 Excluding unneeded functionalities can result in smaller, faster builds as well as less bugs due to a more restricted language.
@@ -94,26 +94,26 @@ Example Scripts
 There are also a number of examples scripts that showcase Rhai's features, all in the `scripts` folder:
 
 | Language feature scripts                             | Description                                                   |
-| ------------------------ | ------------------------------------------------------------- |
+| ---------------------------------------------------- | ------------------------------------------------------------- |
-| `array.rhai`             | arrays in Rhai                                                |
+| [`array.rhai`](scripts/array.rhai)                   | arrays in Rhai                                                |
-| `assignment.rhai`        | variable declarations                                         |
+| [`assignment.rhai`](scripts/assignment.rhai)         | variable declarations                                         |
-| `comments.rhai`          | just comments                                                 |
+| [`comments.rhai`](scripts/comments.rhai)             | just comments                                                 |
-| `for1.rhai`              | for loops                                                     |
+| [`for1.rhai`](scripts/for1.rhai)                     | for loops                                                     |
-| `function_decl1.rhai`    | a function without parameters                                 |
+| [`function_decl1.rhai`](scripts/function_decl1.rhai) | a function without parameters                                 |
-| `function_decl2.rhai`    | a function with two parameters                                |
+| [`function_decl2.rhai`](scripts/function_decl2.rhai) | a function with two parameters                                |
-| `function_decl3.rhai`    | a function with many parameters                               |
+| [`function_decl3.rhai`](scripts/function_decl3.rhai) | a function with many parameters                               |
-| `if1.rhai`               | if example                                                    |
+| [`if1.rhai`](scripts/if1.rhai)                       | if example                                                    |
-| `loop.rhai`              | endless loop in Rhai, this example emulates a do..while cycle |
+| [`loop.rhai`](scripts/loop.rhai)                     | endless loop in Rhai, this example emulates a do..while cycle |
-| `op1.rhai`               | just a simple addition                                        |
+| [`op1.rhai`](scripts/op1.rhai)                       | just a simple addition                                        |
-| `op2.rhai`               | simple addition and multiplication                            |
+| [`op2.rhai`](scripts/op2.rhai)                       | simple addition and multiplication                            |
-| `op3.rhai`               | change evaluation order with parenthesis                      |
+| [`op3.rhai`](scripts/op3.rhai)                       | change evaluation order with parenthesis                      |
-| `string.rhai`            | string operations                                             |
+| [`string.rhai`](scripts/string.rhai)                 | string operations                                             |
-| `while.rhai`             | while loop                                                    |
+| [`while.rhai`](scripts/while.rhai)                   | while loop                                                    |
 
 | Example scripts                              | Description                                                                        |
-| ----------------- | ---------------------------------------------------------------------------------- |
+| -------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `speed_test.rhai` | a simple program to measure the speed of Rhai's interpreter (1 million iterations) |
+| [`speed_test.rhai`](scripts/speed_test.rhai) | a simple program to measure the speed of Rhai's interpreter (1 million iterations) |
-| `primes.rhai`     | use Sieve of Eratosthenes to find all primes smaller than a limit                  |
+| [`primes.rhai`](scripts/primes.rhai)         | use Sieve of Eratosthenes to find all primes smaller than a limit                  |
 
 To run the scripts, either make a tiny program or use of the `rhai_runner` example:
 
@@ -740,7 +740,9 @@ The following standard functions (defined in the standard library but excluded i
 Strings and Chars
 -----------------
 
-String and char literals follow C-style formatting, with support for Unicode ('`\u`') and hex ('`\x`') escape sequences.
+String and char literals follow C-style formatting, with support for Unicode ('`\u`_xxxx_' or '`\U`_xxxxxxxx_') and hex ('`\x`_xx_') escape sequences.
+
+Hex sequences map to ASCII characters, while '`\u`' maps to 16-bit common Unicode code points and '`\U`' maps the full, 32-bit extended Unicode code points.
 
 Although internally Rhai strings are stored as UTF-8 just like in Rust (they _are_ Rust `String`s),
 in the Rhai language they can be considered a stream of Unicode characters, and can be directly indexed (unlike Rust).
@@ -1051,7 +1053,7 @@ for x in array {
     if x == 42 { break; }
 }
 
-// The 'range' function allows iterating from first..last
+// The 'range' function allows iterating from first to last-1
 for x in range(0, 50) {
     print(x);
     if x == 42 { break; }

scripts/array.rhai

@@ -1,4 +1,7 @@
 let x = [1, 2, 3];
-print(x[1]);
+
+print(x[1]);        // prints 2
+
 x[1] = 5;
-print(x[1]);
+
+print(x[1]);        // prints 5

scripts/assignment.rhai

@@ -1,2 +1,2 @@
 let x = 78;
-print(x)
+print(x);

scripts/comments.rhai

@@ -3,8 +3,8 @@
 let /* I am a spy in a variable declaration! */ x = 5;
 
 /* I am a simple
-   multiline comment */
+   multi-line comment */
 
-/* look /* at /* that, /* multiline */ comments */ can be */ nested */
+/* look /* at /* that, /* multi-line */ comments */ can be */ nested */
 
-/* sorrounded by */ x // comments
+/* surrounded by */ x // comments

scripts/for1.rhai

@@ -1,15 +1,17 @@
-let arr = [1,2,3,4]
+// This script runs for-loops
+
+let arr = [1,2,3,4];
+
 for a in arr {
     for b in [10, 20] {
-        print(a)
+        print(a + "," + b);
-        print(b)
     }
-    if a == 3 {
-        break;
-    }
-}
-//print(a)
 
-for i in range(0,5) {
+    if a == 3 { break; }
-    print(i)
+}
+//print(a);                 // <- if you uncomment this line, the script will fail to run
+                            //    because 'a' is not defined here
+
+for i in range(0, 5) {      // runs through a range from 1 to 5 exclusive
+    print(i);
 }

scripts/function_decl1.rhai

@@ -1,5 +1,7 @@
+// This script defines a function and calls it
+
 fn bob() {
-    3
+    return 3;
 }
 
-print(bob())
+print(bob());       // should print 3

scripts/function_decl2.rhai

@@ -1,5 +1,12 @@
+// This script defines a function with two parameters
+
+let a = 3;
+
 fn addme(a, b) {
-    a+b
+    a = 42;             // notice that 'a' is passed by value
+    a + b;              // notice that the last value is returned even if terminated by a semicolon
 }
 
-print(addme(3, 4))
+print(addme(a, 4));     // should print 46
+
+print(a);               // should print 3 - 'a' is never changed

scripts/function_decl3.rhai

@@ -1,5 +1,7 @@
+// This script defines a function with many parameters and calls it
+
 fn f(a, b, c, d, e, f) {
     a - b * c - d * e - f
 }
 
-print(f(100, 5, 2, 9, 6, 32))
+print(f(100, 5, 2, 9, 6, 32));      // should print 4

scripts/if1.rhai

@@ -1,5 +1,14 @@
-let a = true;
+let a = 42;
-if (a) {
+let b = 123;
-    let x = 56;
+let x = 999;
-    print(x);
+
+if a > b {
+    print("a > b");
+} else if a < b {
+    print("a < b");
+
+    let x = 0;          // this 'x' shadows the global 'x'
+    print(x);           // should print 0
+} else {
+    print("a == b");
 }

scripts/loop.rhai

@@ -1,8 +1,12 @@
+// This script runs an infinite loop, ending it with a break statement
+
 let x = 10;
 
 // simulate do..while using loop
 loop {
     print(x);
+
     x = x - 1;
+
 	if x <= 0 { break; }
 }

scripts/op1.rhai

@@ -1 +1 @@
-print(34 + 12)
+print(34 + 12);     // should be 46

scripts/op2.rhai

@@ -1 +1,2 @@
-print(12 + 34 * 5)
+let x = 12 + 34 * 5;
+print(x);               // should be 182

scripts/op3.rhai

@@ -1 +1,2 @@
-print(0 + (12 + 34) * 5)
+let x = (12 + 34) * 5;
+print(x);               // should be 230

scripts/primes.rhai

@@ -1,6 +1,6 @@
-// This is a script to calculate prime numbers.
+// This script uses the Sieve of Eratosthenes to calculate prime numbers.
 
-const MAX_NUMBER_TO_CHECK = 10000;    // 1229 primes
+const MAX_NUMBER_TO_CHECK = 10_000;     // 1229 primes <= 10000
 
 let prime_mask = [];
 prime_mask.pad(MAX_NUMBER_TO_CHECK, true);
@@ -24,4 +24,3 @@ for p in range(2, MAX_NUMBER_TO_CHECK) {
 }
 
 print("Total " + total_primes_found + " primes.");
-

scripts/speed_test.rhai

@@ -1,5 +1,12 @@
-let x = 1000000;
+// This script runs 1 million iterations
+// to test the speed of the scripting engine.
+
+let x = 1_000_000;
+
+print("Ready... Go!");
+
 while x > 0 {
     x = x - 1;
 }
-print(x);
+
+print("Finished.");

scripts/string.rhai

@@ -1,7 +1,17 @@
+// This script tests string operations
+
 print("hello");
-print("this\nis \\ nice");
+print("this\nis \\ nice");      // escape sequences
-print("40 hex is \x40");
+print("40 hex is \x40");        // hex escape sequence
-print("fun with unicode: \u2764 and \U0001F603");
+print("unicode fun: \u2764");   // Unicode escape sequence
-print("foo" + " " + "bar");
+print("more fun: \U0001F603");  // Unicode escape sequence
-print("foo" < "bar");
+print("foo" + " " + "bar");     // string building using strings
-print("foo" >= "bar");
+print("foo" < "bar");           // string comparison
+print("foo" >= "bar");          // string comparison
+print("the answer is " + 42);   // string building using non-string types
+
+let s = "hello, world!";        // string variable
+print("length=" + s.len());     // should be 13
+
+s[s.len()-1] = '?';             // change the string
+print(s);                       // should print 'hello, world?'

scripts/while.rhai

@@ -1,3 +1,5 @@
+// This script runs a while loop
+
 let x = 10;
 
 while x > 0 {