From aeb47efce843a10183d3d278ff7b5f8b449574c6 Mon Sep 17 00:00:00 2001 From: Stephen Chung Date: Thu, 25 Jun 2020 11:07:56 +0800 Subject: [PATCH] Revise docs. --- doc/src/appendix/keywords.md | 50 ++++++++++++++++----------------- doc/src/language/constants.md | 2 ++ doc/src/language/convert.md | 4 +++ doc/src/language/for.md | 10 +++++++ doc/src/language/keywords.md | 5 ++-- doc/src/language/logic.md | 36 ++++++++++++++++++++---- doc/src/language/loop.md | 3 ++ doc/src/language/modules.md | 1 - doc/src/language/overload.md | 7 +++++ doc/src/language/print-debug.md | 3 ++ doc/src/language/variables.md | 19 ++++++++----- 11 files changed, 99 insertions(+), 41 deletions(-) delete mode 100644 doc/src/language/modules.md diff --git a/doc/src/appendix/keywords.md b/doc/src/appendix/keywords.md index f6cdd67e..55299f22 100644 --- a/doc/src/appendix/keywords.md +++ b/doc/src/appendix/keywords.md @@ -3,28 +3,28 @@ Keywords List {{#include ../links.md}} -| Keyword | Description | -| :--------: | ------------------------------------- | -| `true` | Boolean true literal | -| `false` | Boolean false literal | -| `let` | Variable declaration | -| `const` | Constant declaration | -| `if` | If statement | -| `else` | else block of if statement | -| `while` | While loop | -| `loop` | Infinite loop | -| `for` | For loop | -| `in` | Containment test, part of for loop | -| `continue` | Continue a loop at the next iteration | -| `break` | Loop breaking | -| `return` | Return value | -| `throw` | Throw exception | -| `private` | Mark function private | -| `import` | Import module | -| `export` | Export variable | -| `as` | Alias for variable export | -| `fn` | Function definition | -| `type_of` | Get type name of value | -| `print` | Print value | -| `debug` | Print value in debug format | -| `eval` | Evaluate script | +| Keyword | Description | Not available under | +| :--------: | ------------------------------------- | ------------------- | +| `true` | Boolean true literal | | +| `false` | Boolean false literal | | +| `let` | Variable declaration | | +| `const` | Constant declaration | | +| `if` | If statement | | +| `else` | else block of if statement | | +| `while` | While loop | | +| `loop` | Infinite loop | | +| `for` | For loop | | +| `in` | Containment test, part of for loop | | +| `continue` | Continue a loop at the next iteration | | +| `break` | Loop breaking | | +| `return` | Return value | | +| `throw` | Throw exception | | +| `private` | Mark function private | [`no_function`] | +| `import` | Import module | [`no_module`] | +| `export` | Export variable | [`no_module`] | +| `as` | Alias for variable export | [`no_module`] | +| `fn` | Function definition | [`no_function`] | +| `type_of` | Get type name of value | | +| `print` | Print value | | +| `debug` | Print value in debug format | | +| `eval` | Evaluate script | | diff --git a/doc/src/language/constants.md b/doc/src/language/constants.md index b4ced7df..d88ecd4f 100644 --- a/doc/src/language/constants.md +++ b/doc/src/language/constants.md @@ -9,7 +9,9 @@ Constants follow the same naming rules as [variables]. ```rust const x = 42; + print(x * 2); // prints 84 + x = 123; // <- syntax error: cannot assign to constant ``` diff --git a/doc/src/language/convert.md b/doc/src/language/convert.md index a0cd7a83..0c2226eb 100644 --- a/doc/src/language/convert.md +++ b/doc/src/language/convert.md @@ -11,10 +11,14 @@ That's it; for other conversions, register custom conversion functions. ```rust let x = 42; + let y = x * 100.0; // <- error: cannot multiply i64 with f64 + let y = x.to_float() * 100.0; // works + let z = y.to_int() + x; // works let c = 'X'; // character + print("c is '" + c + "' and its code is " + c.to_int()); // prints "c is 'X' and its code is 88" ``` diff --git a/doc/src/language/for.md b/doc/src/language/for.md index ff784d12..6780a1cd 100644 --- a/doc/src/language/for.md +++ b/doc/src/language/for.md @@ -14,7 +14,9 @@ let s = "hello, world!"; for ch in s { if ch > 'z' { continue; } // skip to the next iteration + print(ch); + if x == '@' { break; } // break out of for loop } @@ -23,21 +25,27 @@ let array = [1, 3, 5, 7, 9, 42]; for x in array { if x > 10 { continue; } // skip to the next iteration + print(x); + if x == 42 { break; } // break out of for loop } // The 'range' function allows iterating from first to last-1 for x in range(0, 50) { if x > 10 { continue; } // skip to the next iteration + print(x); + if x == 42 { break; } // break out of for loop } // The 'range' function also takes a step for x in range(0, 50, 3) { // step by 3 if x > 10 { continue; } // skip to the next iteration + print(x); + if x == 42 { break; } // break out of for loop } @@ -47,7 +55,9 @@ let map = #{a:1, b:3, c:5, d:7, e:9}; // Property names are returned in unsorted, random order for x in keys(map) { if x > 10 { continue; } // skip to the next iteration + print(x); + if x == 42 { break; } // break out of for loop } diff --git a/doc/src/language/keywords.md b/doc/src/language/keywords.md index 48c32015..82eddce4 100644 --- a/doc/src/language/keywords.md +++ b/doc/src/language/keywords.md @@ -13,8 +13,9 @@ The following are reserved keywords in Rhai: | `while`, `loop`, `for`, `in`, `continue`, `break` | Looping | | | `fn`, `private` | Functions | [`no_function`] | | `return` | Return values | | -| `throw` | Return errors | | +| `throw` | throw exceptions | | | `import`, `export`, `as` | Modules | [`no_module`] | +| `type_of`, `print`, `debug`, `eval` | Special functions | | -Keywords cannot be the name of a [function] or [variable], unless the relevant exclusive feature is enabled. +Keywords cannot be the name of a [function] or [variable], unless the relevant feature is enabled. For example, `fn` is a valid variable name under [`no_function`]. diff --git a/doc/src/language/logic.md b/doc/src/language/logic.md index 7867a3d8..c660aa52 100644 --- a/doc/src/language/logic.md +++ b/doc/src/language/logic.md @@ -13,8 +13,11 @@ set of types (see [built-in operators]). ```rust 42 == 42; // true + 42 > 42; // false + "hello" > "foo"; // true + "42" == 42; // false ``` @@ -23,13 +26,17 @@ except for '`!=`' (not equals) which results in `true`. This is in line with int ```rust 42 == 42.0; // false - i64 cannot be compared with f64 + 42 != 42.0; // true - i64 cannot be compared with f64 42 > "42"; // false - i64 cannot be compared with string + 42 <= "42"; // false - i64 cannot be compared with string let ts = new_ts(); // custom type + ts == 42; // false - types cannot be compared + ts != 42; // true - types cannot be compared ``` @@ -51,9 +58,11 @@ Single boolean operators `&` and `|` always evaluate both operands. ```rust this() || that(); // that() is not evaluated if this() is true + this() && that(); // that() is not evaluated if this() is false this() | that(); // both this() and that() are evaluated + this() & that(); // both this() and that() are evaluated ``` @@ -61,14 +70,29 @@ Compound Assignment Operators ---------------------------- ```rust -let number = 5; -number += 4; // number = number + 4 -number -= 3; // number = number - 3 -number *= 2; // number = number * 2 -number /= 1; // number = number / 1 -number %= 3; // number = number % 3 +let number = 9; + +number += 8; // number = number + 8 + +number -= 7; // number = number - 7 + +number *= 6; // number = number * 6 + +number /= 5; // number = number / 5 + +number %= 4; // number = number % 4 + +number ~= 3; // number = number ~ 3 + number <<= 2; // number = number << 2 + number >>= 1; // number = number >> 1 + +number &= 0x00ff; // number = number & 0x00ff; + +number |= 0x00ff; // number = number | 0x00ff; + +number ^= 0x00ff; // number = number ^ 0x00ff; ``` The `+=` operator can also be used to build [strings]: diff --git a/doc/src/language/loop.md b/doc/src/language/loop.md index 299ca3ff..b92c3f7e 100644 --- a/doc/src/language/loop.md +++ b/doc/src/language/loop.md @@ -13,8 +13,11 @@ let x = 10; loop { x = x - 1; + if x > 5 { continue; } // skip to the next iteration + print(x); + if x == 0 { break; } // break out of loop } ``` diff --git a/doc/src/language/modules.md b/doc/src/language/modules.md deleted file mode 100644 index a55ecc05..00000000 --- a/doc/src/language/modules.md +++ /dev/null @@ -1 +0,0 @@ -# Modules diff --git a/doc/src/language/overload.md b/doc/src/language/overload.md index b83a8028..b841d00a 100644 --- a/doc/src/language/overload.md +++ b/doc/src/language/overload.md @@ -10,13 +10,20 @@ New definitions _overwrite_ previous definitions of the same name and number of ```rust fn foo(x,y,z) { print("Three!!! " + x + "," + y + "," + z) } + fn foo(x) { print("One! " + x) } + fn foo(x,y) { print("Two! " + x + "," + y) } + fn foo() { print("None.") } + fn foo(x) { print("HA! NEW ONE! " + x) } // overwrites previous definition foo(1,2,3); // prints "Three!!! 1,2,3" + foo(42); // prints "HA! NEW ONE! 42" + foo(1,2); // prints "Two!! 1,2" + foo(); // prints "None." ``` diff --git a/doc/src/language/print-debug.md b/doc/src/language/print-debug.md index bd031b4a..515b098f 100644 --- a/doc/src/language/print-debug.md +++ b/doc/src/language/print-debug.md @@ -7,8 +7,11 @@ The `print` and `debug` functions default to printing to `stdout`, with `debug` ```rust print("hello"); // prints hello to stdout + print(1 + 2 + 3); // prints 6 to stdout + print("hello" + 42); // prints hello42 to stdout + debug("world!"); // prints "world!" to stdout using debug formatting ``` diff --git a/doc/src/language/variables.md b/doc/src/language/variables.md index 581aa9c4..be4abbce 100644 --- a/doc/src/language/variables.md +++ b/doc/src/language/variables.md @@ -6,15 +6,20 @@ Variables Valid Names ----------- -Variables in Rhai follow normal C naming rules (i.e. must contain only ASCII letters, digits and underscores '`_`'). +Variables in Rhai follow normal C naming rules - must contain only ASCII letters, digits and underscores '`_`', +and cannot start with a digit. -Variable names must start with an ASCII letter or an underscore '`_`', must contain at least one ASCII letter, -and must start with an ASCII letter before a digit. +For example: '`_c3po`' and '`r2d2`' are valid variable names, but '`3abc`' is not. -Therefore, names like '`_`', '`_42`', '`3a`' etc. are not legal variable names, but '`_c3po`' and '`r2d2`' are. -Variable names are also case _sensitive_. +However, unlike Rust, a variable name must also contain at least one ASCII letter, and an ASCII letter must come before any digit. +In other words, the first character that is not an underscore '`_`' must be an ASCII letter and not a digit. -Variable names cannot be the same as a [keyword]. +Therefore, some names acceptable to Rust, like '`_`', '`_42foo`', '`_1`' etc., are not valid in Rhai. +This restriction is to reduce confusion because, for instance, '`_1`' can easily be misread (or mis-typed) as `-1`. + +Variable names are case _sensitive_. + +Variable names also cannot be the same as a [keyword]. Declare a Variable @@ -23,7 +28,7 @@ Declare a Variable Variables are declared using the `let` keyword. Variables do not have to be given an initial value. -If none is provided, then it defaults to [`()`]. +If none is provided, it defaults to [`()`]. A variable defined within a statement block is _local_ to that block.